对话补全 Chat Completions

最通用的对话接口，与 OpenAI Chat Completions 完全兼容。 不确定用哪个端点时就用它——覆盖模型最全、客户端生态最广。

POST https://www.apigoto.com/v1/chat/completions

请求头

Authorizationstring必填

形如 Bearer sk-rouertcode-…。此端点只读这一个头，不支持 x-api-key。

Content-Typestring必填

application/json

请求体

modelstring必填

平台模型 ID，例如 claude-sonnet-5。可用值见模型、准入与回退。填上游厂商的原始模型名不生效。

messagesarray必填

对话消息列表，按时间顺序排列。每条含 role（system / user / assistant / tool）与 content。

streamboolean可选

默认 false。置 true 走 SSE 流式返回，见流式响应。

max_tokensinteger可选

本次生成的最大 token 数。这是控制单次调用成本上界最直接的手段。 超过模型自身的输出上限时，网关不做拦截，请求照常转发，由上游厂商裁定并返回其原始错误（网关会把上游响应体原样包在 upstream_body 里下发）。

temperaturenumber可选

采样温度，一般取值 0–2。值越大输出越发散。与 top_p 建议只调一个。

top_pnumber可选

核采样阈值，0–1。

stopstring | array可选

停止序列，最多若干个。命中时生成立即结束，finish_reason 为 stop。

toolsarray可选

可供模型调用的工具定义（type: "function"）。见下方「工具调用」。

tool_choicestring | object可选

auto / none / required，或指定某个函数强制调用。

response_formatobject可选

置 {"type": "json_object"} 约束模型输出合法 JSON。 支持程度取决于上游模型，不支持的模型会忽略该字段。

userstring可选

终端用户标识。网关会读取并记入调用日志，便于按你自己的用户维度做归因。

💡

未列出的字段会原样转发

网关只解析 model、stream、user 三个字段用于路由与记账， 请求体的其余部分原样转发给上游。所以厂商的新参数不需要等网关支持—— 但同理，上游不认识的字段该报错还是会报错，错误由上游原样返回。

响应

200 OK

{
  "id": "chatcmpl-a1b2c3",
  "object": "chat.completion",
  "created": 1755500000,
  "model": "claude-sonnet-5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！有什么可以帮你的吗？"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 11,
    "total_tokens": 23
  }
}

字段	说明
model	实际使用的模型。触发回退时这里与请求里的不同，见模型回退。
choices[].finish_reason	`stop` 正常结束 / `length` 触达 `max_tokens` / `tool_calls` 请求调用工具
usage	token 用量。计费以网关记录为准，与这里一致。

调用示例

chat.sh

curl https://www.apigoto.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $APIGOTO_API_KEY" \
  -d '{
    "model": "claude-sonnet-5",
    "messages": [
      {"role": "system", "content": "你是一个简洁的助手。"},
      {"role": "user", "content": "用一句话解释什么是 API 网关"}
    ],
    "max_tokens": 200
  }'

chat.py

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://www.apigoto.com/v1",
    api_key=os.environ["APIGOTO_API_KEY"],
)

resp = client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[
        {"role": "system", "content": "你是一个简洁的助手。"},
        {"role": "user", "content": "用一句话解释什么是 API 网关"},
    ],
    max_tokens=200,
)
print(resp.choices[0].message.content)

chat.mjs

import OpenAI from 'openai'

const client = new OpenAI({
  baseURL: 'https://www.apigoto.com/v1',
  apiKey: process.env.APIGOTO_API_KEY,
})

const resp = await client.chat.completions.create({
  model: 'claude-sonnet-5',
  messages: [{ role: 'user', content: '用一句话解释什么是 API 网关' }],
  max_tokens: 200,
})
console.log(resp.choices[0].message.content)

流式返回

置 "stream": true 后，响应变为 text/event-stream，每个增量是一个 data: 行，末尾以 data: [DONE] 收束：

stream chunks

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"你"}}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"好"}}]}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

判定流式请求是否成功，看有没有收到 [DONE]，不要只看 HTTP 状态码—— 详见流式响应。

工具调用

在请求里给出 tools，模型决定要调用时会返回 finish_reason: "tool_calls" 与结构化的调用参数；你执行完把结果作为 role: "tool" 的消息追加回去再发一次。

tool_calls 响应片段

{
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": null,
      "tool_calls": [{
        "id": "call_abc123",
        "type": "function",
        "function": {
          "name": "get_weather",
          "arguments": "{\"city\":\"杭州\"}"
        }
      }]
    },
    "finish_reason": "tool_calls"
  }]
}

⚠️

arguments 是字符串，不是对象

它是一段 JSON 文本，需要自己 parse。而且模型生成的参数不保证合法—— 解析失败与字段缺失都要有兜底，别直接信任。

工具调用在跨协议转换时会被完整映射，所以对 Anthropic 系模型使用 OpenAI 的 tools 格式也是可以的，见协议与端点选择。

多模态输入

支持图片输入的模型（support_features 含 image）可以用数组形式的 content：

图片输入

{
  "model": "claude-sonnet-5",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "这张图里有什么？" },
      { "type": "image_url",
        "image_url": { "url": "data:image/jpeg;base64,/9j/4AAQ..." } }
    ]
  }]
}

base64 图片会显著撑大请求体。请求体上限是 100 MiB，超出返回 413 41301。

可能的错误

HTTP	code	常见原因
400	40000	请求体不是合法 JSON
400	40002	`model` 缺失
401	40001 / 40101–40103	密钥缺失、不存在、被禁用或已过期
403	40202 / 40203	未开通计费 / 模型准入不足
413	41301	请求体超 100 MiB
429	42901–42908	限流或额度耗尽
502	50201	模型名写错，或该模型没有可用上游
504	50401	上游超时

完整清单见错误码总表，重试策略见错误处理与重试。