OpenAI Chat Completions 接入教程

从零接入对话补全能力：鉴权、请求参数、流式响应、多模态输入、工具调用与常见问题

概述

本文档介绍平台的对话补全接口 /v1/chat/completions，完全兼容 OpenAI Chat Completions API 规范。你可以直接使用 OpenAI 官方 SDK 或任何兼容 OpenAI 协议的客户端接入，只需替换 API 地址和密钥。

系统根据请求中的 model 字段自动路由到对应的上游提供商，同一个接口即可调用 GPT、Claude、Gemini、DeepSeek、Qwen 等多种模型（前提是账户分组下已配置对应渠道）。

本文示例统一使用 https://www.yunsell.com 作为接入地址；示例中的模型名仅供参考，请替换为控制台中实际可用的模型名称。

快速开始

前提条件

已获取有效的 API Key（sk- 开头），获取方式见快速接入教程。
账户所在分组下已配置目标模型的可用渠道。

最小示例

curl -X POST "https://www.yunsell.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "你好，介绍一下你自己"}
    ]
  }'

响应示例：

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1748227200,
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "你好！我是一个 AI 助手……"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 12,
    "completion_tokens": 28,
    "total_tokens": 40
  }
}

一、接口信息

项目	说明
路径	`/v1/chat/completions`
方法	`POST`
Content-Type	`application/json`
鉴权	请求头 `Authorization: Bearer sk-xxx`

二、请求参数

基础参数

参数名	类型	必填	说明
`model`	string	是	模型名称，决定路由到哪个上游。示例：`gpt-4o`、`claude-sonnet-4-5`、`deepseek-chat`
`messages`	array	是	对话消息列表，结构见下方「messages 消息结构」
`stream`	bool	否	是否流式返回，默认 `false`。设为 `true` 时以 SSE 流式输出
`max_tokens`	int	否	限制模型最大输出 token 数
`max_completion_tokens`	int	否	同 `max_tokens`，OpenAI 新版参数名（o 系列 / gpt-5 等推理模型使用此字段），两者传其一即可
`temperature`	float	否	采样温度，通常 0~2，越大越随机
`top_p`	float	否	核采样阈值，与 `temperature` 二选一调整即可
`stop`	string / string[]	否	停止词，生成到此序列即停止
`n`	int	否	生成候选条数，默认 1
`seed`	int	否	随机种子，尽力保证结果可复现（是否生效取决于上游）
`frequency_penalty`	float	否	频率惩罚，-2.0~2.0
`presence_penalty`	float	否	存在惩罚，-2.0~2.0
`user`	string	否	终端用户标识，用于上游滥用检测

messages 消息结构

messages 是一个按时间顺序排列的消息数组，每条消息包含 role 和 content：

role	说明
`system`	系统提示词，通常放在数组第一条，用于设定模型行为
`user`	用户消息
`assistant`	模型的历史回复（多轮对话时回传）；发起工具调用时含 `tool_calls` 字段
`tool`	工具执行结果，需携带 `tool_call_id`，见下方「工具调用」

纯文本消息 content 直接传字符串；多模态消息（图文混合）传内容块数组：

{
  "role": "user",
  "content": [
    { "type": "text", "text": "这张图片里有什么？" },
    { "type": "image_url", "image_url": { "url": "https://example.com/photo.jpg" } }
  ]
}

图片也可以用 Base64 Data URI 内嵌传入：

{ "type": "image_url", "image_url": { "url": "data:image/jpeg;base64,/9j/4AAQSk..." } }

进阶参数

参数名	类型	必填	说明
`stream_options`	object	否	流式选项，仅 `stream: true` 时生效。`{"include_usage": true}` 会在流末尾追加一个携带 `usage` 的 chunk
`response_format`	object	否	输出格式约束。`{"type": "json_object"}` 强制输出 JSON；`{"type": "json_schema", "json_schema": {...}}` 按 Schema 结构化输出
`tools`	array	否	工具（函数）定义列表，见下方「工具调用」
`tool_choice`	string / object	否	工具选择策略：`auto`（默认）/ `none` / `required` / 指定某个函数
`parallel_tool_calls`	bool	否	是否允许并行工具调用
`logprobs`	bool	否	是否返回输出 token 的对数概率
`top_logprobs`	int	否	每个位置返回概率最高的 N 个候选 token（0-20），需 `logprobs: true`
`reasoning_effort`	string	否	推理强度（仅推理类模型生效）：`low` / `medium` / `high`

参数是否生效取决于所选模型的上游供应商：网关会尽量原样透传或做等价转换，上游不支持的参数可能被忽略或直接报错，请以实际调用结果为准。

三、响应参数（非流式）

字段	类型	说明
`id`	string	本次补全的唯一 ID
`object`	string	固定值：`"chat.completion"`
`created`	int64	创建时间戳（Unix 秒）
`model`	string	实际使用的模型名称
`choices`	array	生成结果列表，长度等于请求参数 `n`
`choices[].index`	int	结果序号
`choices[].message`	object	模型回复消息：`role` 固定为 `assistant`；文本在 `content`；发起工具调用时含 `tool_calls`
`choices[].finish_reason`	string	结束原因，见下表
`usage`	object	用量统计：`prompt_tokens`（输入）、`completion_tokens`（输出）、`total_tokens`（合计），计费依据

finish_reason 取值

值	含义
`stop`	正常结束（模型输出完毕或命中 `stop` 停止词）
`length`	达到 `max_tokens` 上限被截断
`tool_calls`	模型请求调用工具，需执行工具后回传结果
`content_filter`	内容被上游安全策略过滤

四、流式响应

请求体中设置 "stream": true，响应变为 SSE（Server-Sent Events）流，Content-Type: text/event-stream。每个事件是一行 data: {JSON}，增量内容在 choices[].delta.content 中，流以 data: [DONE] 结束：

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1748227200,"model":"gpt-4o","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1748227200,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"你好"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1748227200,"model":"gpt-4o","choices":[{"index":0,"delta":{"content":"！"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1748227200,"model":"gpt-4o","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]

流式获取用量统计

流式模式下默认不返回 usage。如需在流式下拿到用量，请加上 stream_options：

{
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "你好"}],
  "stream": true,
  "stream_options": { "include_usage": true }
}

此时 [DONE] 之前会多一个 chunk：其 choices 为空数组、usage 字段携带完整用量。客户端解析时务必先判断 choices 非空再取 delta，否则会在这个 usage chunk 上报数组越界。

cURL 示例

curl -N -X POST "https://www.yunsell.com/v1/chat/completions" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "写一首关于春天的短诗"}],
    "stream": true,
    "stream_options": {"include_usage": true}
  }'

（-N 参数禁用 curl 缓冲，便于实时观察流式输出。）

五、工具调用（Function Calling）

第一步：携带工具定义发起请求

{
  "model": "gpt-4o",
  "messages": [
    { "role": "user", "content": "北京今天天气怎么样？" }
  ],
  "tools": [
    {
      "type": "function",
      "function": {
        "name": "get_weather",
        "description": "查询指定城市的当前天气",
        "parameters": {
          "type": "object",
          "properties": {
            "city": { "type": "string", "description": "城市名，如：北京" }
          },
          "required": ["city"]
        }
      }
    }
  ]
}

模型决定调用工具时，响应的 finish_reason 为 tool_calls，message.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"
    }
  ]
}

第二步：执行工具并回传结果

在你的业务侧执行 get_weather("北京") 后，把 assistant 消息和工具结果一起追加到 messages，再次请求：

{
  "model": "gpt-4o",
  "messages": [
    { "role": "user", "content": "北京今天天气怎么样？" },
    {
      "role": "assistant",
      "content": null,
      "tool_calls": [
        { "id": "call_abc123", "type": "function",
          "function": { "name": "get_weather", "arguments": "{\"city\":\"北京\"}" } }
      ]
    },
    { "role": "tool", "tool_call_id": "call_abc123", "content": "{\"weather\":\"晴\",\"temp\":\"26°C\"}" }
  ],
  "tools": [ ... 与第一次请求相同 ... ]
}

模型会基于工具结果生成最终自然语言回复。

流式模式下工具调用参数通过 delta.tool_calls[].function.arguments 分片下发，客户端需按 index 拼接完整 JSON 字符串后再解析。

六、结构化输出

强制模型输出合法 JSON 对象（提示词中需明确提到 JSON，否则部分上游会报错）：

{
  "model": "gpt-4o",
  "messages": [
    { "role": "system", "content": "从用户输入中提取信息，以 JSON 格式输出，包含 name 和 city 两个字段" },
    { "role": "user", "content": "我叫张三，住在杭州" }
  ],
  "response_format": { "type": "json_object" }
}

如需严格约束字段结构，使用 json_schema（是否支持取决于所选模型）：

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "user_info",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "city": { "type": "string" }
        },
        "required": ["name", "city"],
        "additionalProperties": false
      }
    }
  }
}

七、错误码说明

HTTP 状态码	含义
`200`	请求成功
`400`	请求参数错误（如缺少必填参数、messages 结构不合法）
`401`	未认证（缺少 Authorization 头或 API Key 无效/已禁用）
`403`	无权限（API Key 无权访问该模型，或账户额度不足）
`429`	请求频率超限，请降低调用频率后重试
`500`	服务器内部错误
`502`	上游服务异常（上游模型不可用或超时）

错误响应体遵循 OpenAI 错误格式：

{
  "error": {
    "message": "Invalid API key",
    "type": "invalid_request_error",
    "code": "invalid_api_key"
  }
}

八、注意事项

模型路由：系统根据 model 字段自动路由，请确保模型名称在账户/分组下已配置可用渠道，否则会返回「无可用渠道」类错误。
计费依据：按响应 usage 中的 token 用量计费；流式调用建议开启 stream_options.include_usage 以便本地对账。
max_tokens 与 max_completion_tokens：两者语义相同，传其一即可；调用 o 系列 / gpt-5 等推理模型时建议使用 max_completion_tokens。
流式解析：usage chunk 的 choices 为空数组，取 delta 前先判空；整个流以 data: [DONE] 结束。
多模态：图片 URL 需公网可访问；Base64 内嵌会显著增大请求体，大图建议先压缩或改用 URL。
参数兼容性：同一接口背后是不同上游，logprobs、seed、json_schema 等进阶参数并非所有模型都支持，切换模型后请回归验证。

下一步

查看 Anthropic Messages 接入教程了解 Claude 原生接口接入
查看 SDK 示例获取 Python / Node.js / Go 完整代码
返回快速接入教程了解密钥获取与基础配置

OpenAI Chat Completions 接入教程

On this page