Chat Completions 概览

本节说明如何通过 OpenAI 兼容的 Chat Completions 接口调用模型。

本节只覆盖 /v1/chat/completions。Responses API、Claude Messages 原生（仅 Claude Code 用，见 Claude Code 文档）、Gemini 原生、Embedding 等接口实际可用，但兼容性未经统一测试，使用需自行验证。

接入信息

接口地址：

POST https://api.aiqizhilian.tech/v1/chat/completions

请求头：

Authorization: Bearer <你的 API Key>
Content-Type: application/json

所有请求都必须携带 API Key。API Key 由运营方分配，请妥善保管，不要写入前端代码、公开仓库、日志或截图。

最小可用请求

curl https://api.aiqizhilian.tech/v1/chat/completions \
  -H "Authorization: Bearer <你的 API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      {
        "role": "user",
        "content": "用一句话介绍你自己。"
      }
    ],
    "max_tokens": 256
  }'

正常响应会返回 OpenAI Chat Completions 风格结构：

{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "created": 1760000000,
  "model": "gpt-5.5",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 20,
    "total_tokens": 30
  }
}

业务侧通常读取：

• 回复内容：choices[0].message.content
• 结束原因：choices[0].finish_reason
• Token 用量：usage

messages 格式

messages 是一个数组，按对话顺序传入。

常用角色：

Role	用途
system	设置助手身份、规则、输出格式。
user	用户输入。
assistant	历史助手回复，多轮对话时传回。
tool	工具调用结果，仅在使用 tools 时需要。

示例：

{
  "model": "gpt-5.5",
  "messages": [
    {
      "role": "system",
      "content": "你是一个严谨的客服助手。"
    },
    {
      "role": "user",
      "content": "帮我写一段退款说明。"
    }
  ],
  "max_tokens": 512
}

多轮对话时，客户端需要自行保存历史消息，并在下一次请求中带上必要上下文。

常用参数

参数	类型	是否必填	说明
model	string	是	模型名称。
messages	array	是	对话消息数组。
max_tokens	number	建议填写	限制最大输出 token 数。
temperature	number	否	控制随机性，值越高越发散。
top_p	number	否	nucleus sampling 参数。
stream	boolean	否	是否使用流式返回，详见 流式输出。
stream_options	object	否	流式选项，例如 {include_usage: true}。
response_format	object	否	可请求 JSON object 输出，详见 JSON 输出。
tools	array	否	OpenAI 风格函数工具定义，详见 工具调用。
tool_choice	string/object	否	是否强制调用指定工具。部分模型不支持强制指定。

建议：

• 普通问答：只传 model、messages、max_tokens。
• 需要稳定输出：降低 temperature，例如 0.2。
• 需要 JSON：使用 response_format，同时在提示词里要求只输出 JSON。
• 需要低延迟：开启 stream: true。

下一步

• 可用模型 — 完整模型清单与适用场景
• 流式输出 — SSE 格式与 usage chunk
• JSON 输出 — 强结构化输出建议
• 工具调用 — function calling
• 错误码 — HTTP 状态码与处理建议