文本与对话

文本模型通常通过 OpenAI 兼容的 Chat Completions 接口调用。模型标识必须来自当前 API Key 可访问的 /v1/models 响应。

接口

POST https://api.topapis.cn/v1/chat/completions
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

请求参数

参数	类型	必填	说明
model	string	是	/v1/models 返回的对话模型标识
messages	array	是	按顺序排列的对话消息
stream	boolean	否	true 时使用 SSE 流式返回
temperature	number	否	采样随机性，支持范围取决于模型
max_tokens	integer	否	最大输出 Token 数，支持情况取决于模型

消息通常包含 role 和 content。常用角色为 system、user 和 assistant。

非流式请求

curl "https://api.topapis.cn/v1/chat/completions" \
  -H "Authorization: Bearer $TOPAPIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL",
    "messages": [
      { "role": "system", "content": "回答保持简洁。" },
      { "role": "user", "content": "解释什么是指数退避。" }
    ]
  }'

读取 choices[0].message.content 获取首个回答：

{
  "id": "chatcmpl_example",
  "object": "chat.completion",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "指数退避会逐步增加重试间隔。"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 14,
    "total_tokens": 34
  }
}

字段可能因模型和通道而变化。客户端不应假设 usage 始终存在。

流式请求

在请求体中加入：

{
  "model": "YOUR_MODEL",
  "messages": [
    { "role": "user", "content": "逐步说明请求流程。" }
  ],
  "stream": true
}

服务通过 text/event-stream 返回数据帧。逐帧读取 choices[0].delta.content，收到 [DONE] 后结束。

data: {"choices":[{"delta":{"content":"第一步"}}]}

data: [DONE]

流式响应开始后，HTTP 状态可能已经是成功；客户端还应处理流中断和不完整 JSON 帧。

错误处理

• 模型不存在或无权限时，重新查询模型列表。
• 429 和临时 5xx 可按错误码与重试进行有限退避。
• 对话请求可能产生计费，不要在超时后无条件并发重发。