接口清单

本页列出当前对外开放的模型调用 HTTP 接口（mgk_ API Key，网关 https://api.modelgo.com）。

接入前置

1. 在 https://console.modelgo.com 创建 API Key（mgk_ 前缀），完整明文只展示一次。
2. export MODELGO_API_KEY="你的-API-Key"。
3. 调用 GET /v1/models 确认该 Key 能用的逻辑模型名。
4. 选接口前先确认该模型是否声明了对应协议：打到模型未提供的入口，网关返回 HTTP 400、error_class=model_protocol_not_offered（app_error_id=4005），而不是帮你改写成别的协议。

鉴权

所有下列接口都用同一套 API Key：

Authorization: Bearer $MODELGO_API_KEY

Anthropic 客户端可用 x-api-key，Gemini 客户端可用 x-goog-api-key。多头同时出现时优先级为 Authorization > x-api-key > x-goog-api-key。详见认证鉴权。

缺 Key 或 Key 无效时的真实响应（HTTP 401）：

{
  "error": {
    "code": 401,
    "message": "unauthorized",
    "metadata": {
      "app_error_id": 4011,
      "error_class": "auth",
      "request_id": "gw_0a80995b-7712-4ffb-885e-f84d0bb2b06b"
    }
  },
  "trace_id": "bbaf7b379c1dbb4b42adbabf65f5f530"
}

排障请同时保留响应头 X-Request-ID、X-Trace-ID 与 body 里的 trace_id。

协议匹配（必读）

平台按模型目录里的 public_protocols 决定一个逻辑模型能打哪些入口。文档里的 curl 不能对任意模型复制粘贴。

全量清单

状态含义：

• 正式对外：网关已挂载，客户可调；能否对某个模型调通，仍取决于该模型的 public_protocols 与 Key 策略。
• 正式对外 / 别名：与上一行行为相同。

文本与模型目录

向量 / 图像 / 音频 / 重排

视频与异步任务（托管）

查询模型清单

curl https://api.modelgo.com/v1/models \
  -H "Authorization: Bearer $MODELGO_API_KEY"

真实响应形态（条目已截断）：

{
  "object": "list",
  "data": [
    {
      "id": "claude-fable-5",
      "object": "model",
      "created": 1735689600,
      "context_length": 1000000,
      "input_modalities": ["file", "image", "text"],
      "output_modalities": ["text"]
    }
  ]
}

id 就是请求里的 model。清单不包含 public_protocols；某个模型能不能打某个入口，以实际调用结果和控制台模型页为准。

文本调用（已验证）

POST /v1/chat/completions

curl https://api.modelgo.com/v1/chat/completions \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.6-flash",
    "messages": [{"role": "user", "content": "用一句话介绍 ModelGo。"}],
    "max_tokens": 64
  }'

成功时 HTTP 200，object 为 chat.completion，含 choices[0].message 与 usage。部分推理模型会额外返回 reasoning_content，且 usage.completion_tokens 可能远大于 max_tokens（实测 max_tokens: 64 时 completion 仍可达上千）。

流式：同一路径加 "stream": true，响应 Content-Type: text/event-stream，每行 data: {chunk}，以 data: [DONE] 结束。

空 body {} 的真实错误（HTTP 400）：

{
  "error": {
    "code": 400,
    "message": "invalid request",
    "metadata": {
      "app_error_id": 4001,
      "error_class": "client_invalid",
      "request_id": "gw_a542461f-fe16-4f72-88d7-4c67b4bc9d7c"
    }
  },
  "trace_id": "d6630b36c387a9e1e2d7bc9b6aa89020"
}

模型不在目录（HTTP 403）：

{
  "error": {
    "code": 403,
    "message": "model is not registered or enabled in catalog",
    "metadata": {
      "app_error_id": 4031,
      "error_class": "policy",
      "reason": "model_not_in_catalog",
      "request_id": "gw_ecc21066-c4a9-4eb1-97e7-799c4b1290"
    }
  }
}

POST /v1/responses

curl https://api.modelgo.com/v1/responses \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.6-flash",
    "input": "用一句话介绍 ModelGo。",
    "max_output_tokens": 64
  }'

成功时 object 为 response，output 为数组（可能含 reasoning 与 message），并带 output_text。

POST /v1/messages

curl https://api.modelgo.com/v1/messages \
  -H "x-api-key: $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-fable-5",
    "max_tokens": 64,
    "messages": [{"role": "user", "content": "用一句话介绍 ModelGo。"}]
  }'

成功时 Anthropic 消息形态：type: "message"，content[].type: "text"。响应里的 model 可能是上游内部名（实测为 pa/venus-cathedral-5），与请求里的逻辑名不同，请以请求 model 和控制台为准。

向量 / 图像 / 语音（已验证）

POST /v1/embeddings

curl https://api.modelgo.com/v1/embeddings \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"text-embedding-3-small","input":"hello ModelGo"}'

成功：data[0].embedding 为浮点数组（text-embedding-3-small 实测维度 1536），usage.prompt_tokens 为计费 token。

POST /v1/images/generations

doubao-seedream-5.0-lite 拒绝过小的 size。1024x1024 实测 HTTP 400、error_class=provider_invalid，上游要求像素总数至少 3686400（约 1920×1920）。用 2048x2048 可通过：

curl https://api.modelgo.com/v1/images/generations \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5.0-lite",
    "prompt": "a tiny red apple on white background, simple",
    "size": "2048x2048"
  }'

成功响应含 data[0].url（对象存储地址，有时效）和 usage.generated_images。响应 model 可能是上游名（实测 doubao-seedream-5-0-260128）。

POST /minimax/v1/t2a_v2

见MiniMax 音频入站协议。speech-2.8-turbo / speech-2.8-hd 当前声明的是这条 MiniMax 原生协议，不是 OpenAI /v1/audio/speech。

异步视频（已验证）

Seedance 类模型走托管异步任务，而不是 OpenAI /v1/video/generations。

curl https://api.modelgo.com/v1/content_generation/tasks \
  -H "Authorization: Bearer $MODELGO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2.0-mini",
    "content": [{"type": "text", "text": "a red apple on a table"}]
  }'

创建成功（HTTP 200）：

{
  "id": "gw_c731f504-5a53-4e37-a972-30653a8ee390",
  "model": "doubao-seedance-2.0-mini",
  "status": "queued",
  "created_at": 1789012940,
  "error": null
}

同一 id 也可在 GET /ark/api/v3/contents/generations/tasks/{id} 轮询，状态会变为 running，完成后为 succeeded（实测 resolution=720p、ratio=16:9、duration=5）。DELETE 取消在该上游上实测返回 HTTP 400、error_class=provider_unsupported、endpoint not supported by provider——不要假设所有视频模型都支持取消。

POST /minimax/v2/video_generation 若缺少计费维度，返回 HTTP 400、client_invalid（billing_error_code=4223）。按 MiniMax 视频文档补齐 duration / resolution 等字段后再试。

流式约定

• 文本流式接口（/v1/chat/completions、/v1/responses、/v1/messages）在请求体设 stream: true（Anthropic 为 stream: true）。
• OpenAI 形态：Content-Type: text/event-stream，帧为 data: <json>，正常结束带 data: [DONE]。
• Anthropic /v1/messages 保持原生 event: 帧，网关不会改写成 OpenAI SSE。
• 流中若出现带 error 的数据块，按失败处理；此时可能没有独立的 HTTP 错误状态码。

限流、超时、幂等、分页

• 限流：HTTP 429，error_class 为 quota 或 provider_rate_limit；平台限流时会带 Retry-After。
• 超时：客户端自行设置；上游超时为 provider_timeout（408）。
• 幂等：同步文本/图像/语音请求没有客户侧幂等键。异步视频任务以返回的 id / task_id 为后续轮询主键；重复 POST 会再创建新任务。
• 分页：模型调用面没有 cursor/page 列表接口。GET /v1/models 一次返回当前 Key 可见的全部逻辑模型。

下一步

• 认证鉴权
• 错误码与限流
• 文本生成
• 图像生成
• MiniMax 音频入站协议
• 通用异步内容生成任务