OpenAI 兼容接口

MoziaVerse 提供 OpenAI API 兼容接口。支持 OpenAI API 格式的客户端只需替换基础地址和 API Key，即可通过统一网关调用当前账号可用的文本与向量模型。

本文档描述平台通用协议，不绑定任何具体模型。不同模型对工具调用、结构化输出、推理、流式响应等高级能力的支持可能不同，请以控制台模型信息和实际响应为准。

接口总览

方法	路径	作用
GET	/v1/models	查询当前 API Key 可用的模型
GET	/v1/models/{model}	查询指定模型
POST	/v1/chat/completions	创建聊天补全
POST	/v1/responses	使用 Responses API 创建响应
POST	/v1/completions	传统文本补全兼容接口
POST	/v1/embeddings	创建文本向量

基础地址：https://mzsjai.com

所有请求都需要 API Key：

Authorization: Bearer <YOUR_API_KEY>

请只在服务端保存 API Key，不要将其写入浏览器代码、公开仓库或日志。以下示例使用环境变量：

export MOZIA_API_KEY='<YOUR_API_KEY>'
export MODEL_ID='<MODEL_ID>'

查询可用模型

不同 API Key 可能因为账号分组、权限或 Key 的模型限制而看到不同的模型列表。调用前可以查询当前 Key 实际可用的模型：

curl --fail-with-body \
  'https://mzsjai.com/v1/models' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}"

响应采用 OpenAI 模型列表结构：

{
  "object": "list",
  "data": [
    {
      "id": "<MODEL_ID>",
      "object": "model",
      "created": 0,
      "owned_by": "<OWNER>"
    }
  ]
}

请求中 model 字段必须填写返回结果里的完整 id，不要使用页面展示名称或自行缩写。

Chat Completions

POST /v1/chat/completions 接收 OpenAI Chat Completions 格式的消息数组，支持非流式和流式响应。

简单调用

curl --fail-with-body \
  'https://mzsjai.com/v1/chat/completions' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"model\": \"${MODEL_ID}\",
    \"messages\": [
      {
        \"role\": \"system\",
        \"content\": \"You are a helpful assistant.\"
      },
      {
        \"role\": \"user\",
        \"content\": \"用三句话解释什么是向量数据库。\"
      }
    ]
  }"

常用参数

字段	类型	必填	说明
model	string	是	/v1/models 返回的完整模型 ID
messages	array	是	对话消息，常用角色为 system、user、assistant 和 tool
stream	boolean	否	是否使用 SSE 流式响应，默认 false
stream_options.include_usage	boolean	否	流式响应结束前是否返回用量信息
max_completion_tokens	integer	否	最大输出 Token 数，新接入优先使用此字段
max_tokens	integer	否	最大输出 Token 数的兼容字段
temperature	number	否	采样温度
top_p	number	否	核采样参数
stop	string 或 array	否	停止序列
tools	array	否	可供模型调用的工具定义
tool_choice	string 或 object	否	工具选择策略
response_format	object	否	结构化输出格式
reasoning_effort	string	否	推理强度；仅对支持该能力的模型生效

推荐在 temperature 与 top_p 中只调整一个。模型不支持的参数可能被忽略或返回错误。

非流式响应

{
  "id": "chatcmpl_...",
  "object": "chat.completion",
  "created": 1780000000,
  "model": "<MODEL_ID>",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 60,
    "total_tokens": 80
  }
}

调用方应从 choices[0].message.content 读取文本，并使用 finish_reason 判断生成结束原因。Token 用量以实际响应为准，部分模型或渠道可能不会返回完整明细。

流式调用

curl --fail-with-body -N --no-buffer \
  'https://mzsjai.com/v1/chat/completions' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"model\": \"${MODEL_ID}\",
    \"messages\": [
      {
        \"role\": \"user\",
        \"content\": \"介绍一下杭州。\"
      }
    ],
    \"stream\": true,
    \"stream_options\": {
      \"include_usage\": true
    }
  }"

流式响应使用 Server-Sent Events。客户端应逐行处理 data: 事件，并在流结束后关闭连接。是否返回单独的用量事件取决于模型与渠道支持情况。

工具调用

curl --fail-with-body \
  'https://mzsjai.com/v1/chat/completions' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"model\": \"${MODEL_ID}\",
    \"messages\": [
      {
        \"role\": \"user\",
        \"content\": \"杭州现在天气怎么样？\"
      }
    ],
    \"tools\": [
      {
        \"type\": \"function\",
        \"function\": {
          \"name\": \"get_weather\",
          \"description\": \"查询指定城市的天气\",
          \"parameters\": {
            \"type\": \"object\",
            \"properties\": {
              \"city\": {
                \"type\": \"string\"
              }
            },
            \"required\": [\"city\"]
          }
        }
      }
    ],
    \"tool_choice\": \"auto\"
  }"

当 finish_reason 为 tool_calls 时，调用方需要执行 message.tool_calls 中的函数，将结果作为 tool 消息加入对话，再发起下一次请求。工具不会由平台自动执行。

Responses API

POST /v1/responses 支持 OpenAI Responses API 格式。适合使用字符串或结构化输入，并支持工具调用、推理和流式输出等能力。

简单调用

curl --fail-with-body \
  'https://mzsjai.com/v1/responses' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"model\": \"${MODEL_ID}\",
    \"instructions\": \"回答应简洁、准确。\",
    \"input\": \"解释 HTTP 状态码 429 的含义。\"
  }"

常用参数

字段	类型	必填	说明
model	string	是	/v1/models 返回的完整模型 ID
input	string 或 array	条件必填	输入文本或结构化消息
instructions	string	否	对本次响应的系统级指令
stream	boolean	否	是否使用流式响应
max_output_tokens	integer	否	最大输出 Token 数
temperature	number	否	采样温度
top_p	number	否	核采样参数
tools	array	否	工具定义
tool_choice	string 或 object	否	工具选择策略
reasoning	object	否	推理配置，仅对支持该能力的模型生效
previous_response_id	string	否	用于关联上一轮响应
truncation	string	否	上下文截断策略，可用值包括 auto、disabled

响应正文位于 output 数组中。调用方应按 output[].type 和 output[].content[].type 解析内容，不要假设所有输出都是纯文本。

流式调用

curl --fail-with-body -N --no-buffer \
  'https://mzsjai.com/v1/responses' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"model\": \"${MODEL_ID}\",
    \"input\": \"列出设计 REST API 时最重要的五条原则。\",
    \"stream\": true
  }"

Embeddings

POST /v1/embeddings 将文本转换为向量。输入可以是一段文本，也可以是文本数组。

curl --fail-with-body \
  'https://mzsjai.com/v1/embeddings' \
  -H "Authorization: Bearer ${MOZIA_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d "{
    \"model\": \"${MODEL_ID}\",
    \"input\": [
      \"第一段待向量化的文本\",
      \"第二段待向量化的文本\"
    ],
    \"encoding_format\": \"float\"
  }"

字段	类型	必填	说明
model	string	是	支持向量生成的完整模型 ID
input	string 或 array	是	待向量化的文本
encoding_format	string	否	float 或 base64，默认 float
dimensions	integer	否	输出向量维度；仅对支持该参数的模型生效

响应中的向量位于 data[].embedding，顺序与输入文本一致。

兼容客户端配置

支持自定义 OpenAI 服务地址的客户端通常只需要以下配置：

配置项	值
Base URL	https://mzsjai.com/v1
API Key	Matrix API Key
Model	/v1/models 返回的完整模型 ID

如果客户端要求填写不带 /v1 的服务器地址，请使用 https://mzsjai.com。是否需要包含 /v1 取决于客户端会不会自动拼接版本路径。

错误处理

错误响应采用 OpenAI 兼容结构：

{
  "error": {
    "message": "Error description",
    "type": "invalid_request_error",
    "param": null,
    "code": "error_code"
  }
}

状态码	说明	建议
400	请求体或参数无效	修正请求后重试
401	API Key 缺失或无效	检查鉴权配置
403	当前 Key 无权使用该模型	检查模型权限和 Key 限制
404	接口或模型不存在	检查路径和完整模型 ID
429	余额不足、请求过多或触发限流	检查余额并降低请求频率
500	平台或上游处理失败	保存请求 ID 后联系平台
502/503/504	上游服务暂不可用或超时	使用指数退避进行有限重试

不要无限重试参数错误。对 429 和临时服务错误重试时，应设置最大次数，并使用指数退避和随机抖动。