OpenAI Chat Completions

官方文档：Create chat completion · Streaming responses · Text generation

POST /v1/chat/completions 是兼容面最广的文本入口：OpenAI 官方 SDK、各类第三方客户端和大部分历史代码都按这套形状发起请求，切换到 ModelGo 通常只需要替换 Base URL 与 API Key。

项目	值
端点	`POST /v1/chat/completions`
Base URL（OpenAI SDK）	`https://api.modelgo.ai/v1`
鉴权	`Authorization: Bearer $MODELGO_API_KEY`
协议声明	`openai_chat_completions`

请求示例

bash

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

python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["MODELGO_API_KEY"],
    base_url="https://api.modelgo.ai/v1",
)

resp = client.chat.completions.create(
    model="<model>",
    messages=[{"role": "user", "content": "用一句话介绍 ModelGo。"}],
)
print(resp.choices[0].message.content)

常用字段

字段	说明
`model`	平台逻辑模型名
`messages`	对话数组，`role` 取 `system` / `developer` / `user` / `assistant` / `tool`
`content`	字符串，或文本、图片等内容块数组；多模态能力取决于模型
`max_tokens` / `max_completion_tokens`	输出上限。新一代模型只接受 `max_completion_tokens`，网关按模型自动改写，两种写法都可以用
`temperature` / `top_p`	采样参数
`tools` / `tool_choice`	函数调用定义与选择策略；工具结果以 `role: "tool"` 的消息回传
`stream`	为 `true` 时以 SSE 返回
`stream_options`	网关会强制打开 `include_usage` 以满足计费，客户端无需自己设置

较新的字段与角色由网关按上游能力吸收：对只认旧角色集的上游，developer 会被降级为 system；对只接受新字段的模型，max_tokens 会被改写为 max_completion_tokens。客户端不必为上游差异改写请求。

响应与流式

非流式返回 object: "chat.completion"，正文在 choices[0].message.content，用量在 usage。部分推理模型会额外返回 reasoning_content，此时 usage.completion_tokens 可能明显大于所写的 max_tokens。

流式（"stream": true）返回 Content-Type: text/event-stream，每帧为 data: {"choices":[{"delta":{...}}]}，正常结束发送 data: [DONE]。网关会向内层上游强制打开 stream_options.include_usage，因此流式调用同样按上游实际回报的用量结算。

关键约定

逻辑模型未声明 openai_chat_completions 协议时，本入口返回 HTTP 400、error_class=model_protocol_not_offered（app_error_id=4005）。换入口或换模型，不要改写请求体。
错误信封是 OpenAI 形状：{"error":{"code":..., "message":..., "metadata":{...}}}，并带与 X-Trace-ID 一致的顶层 trace_id。
请求体上限 10 MiB；超限返回 HTTP 400、client_invalid，错误信息写明上限。
流中若出现 error 数据块，按失败处理——此类中断不会再有独立的 HTTP 状态码。

其他入口对比见文本生成总览，Anthropic 原生报文见 Anthropic Messages，错误清单见错误码与限流。