api 接口对接文档

本文说明如何调用 https://token.kelly.cloud/v1/chat/completions。该接口兼容 OpenAI Chat Completions 请求和响应格式，使用OpenAI Chat Completions 时，请求地址变为https://token.kelly.cloud/v1。模型是否可用以及具体参数支持情况以实际分配的 API Key 和模型为准。

1. 接口信息

项目	值
请求地址	`https://token.kelly.cloud/v1/chat/completions`
请求方法	`POST`
鉴权	`Authorization: Bearer <API_KEY>`
请求格式	`Content-Type: application/json`
非流式响应	JSON
流式响应	`text/event-stream`（SSE）

请使用分配给调用方的平台 API Key。密钥应保存在服务端，不要写入前端代码或公开仓库。

2. 请求参数

字段	类型	必填	说明
`model`	string	是	模型 ID，必须是当前 API Key 可调用的模型。下例使用 `qwen3.8-flash`；如实际分配的模型 ID 不同，请替换。
`messages`	array	是	对话消息，至少一条。每项包含 `role` 和 `content`。
`messages[].role`	string	是	常见值：`system`、`user`、`assistant`；工具调用时还可能使用 `tool`。
`messages[].content`	string 或内容数组	是	纯文本对接传字符串。
`stream`	boolean	否	`true` 返回 SSE 流；省略或 `false` 返回完整 JSON。

model 和 messages 不能为空，否则请求会失败。

3. 非流式请求示例

如果使用 Postman：选择 POST，在 Headers 设置以上两个请求头，在 Body 选择 raw → JSON，粘贴同一份 JSON 请求体。无需填写 URL 查询参数。

4. 非流式成功响应

HTTP 200 时，响应是一个 Chat Completions JSON 对象。以下为结构示例，ID、时间、内容和 token 数每次都可能不同：

{
  "id": "chatcmpl-7ae5b515-4079-9aa3-a1ab-413ca4d79c97",
  "object": "chat.completion",
  "created": 1789372371,
  "model": "qwen3.8-flash",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "reasoning_content": "模型生成的推理内容（如该模型返回）",
        "content": "你好！有什么我可以帮你的吗？"
      },
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": {
    "prompt_tokens": 62,
    "completion_tokens": 32,
    "total_tokens": 94,
    "prompt_tokens_details": {
      "cached_tokens": 0,
      "text_tokens": 62
    },
    "completion_tokens_details": {
      "reasoning_tokens": 19,
      "text_tokens": 32
    }
  }
}

响应字段说明

字段	类型	说明
`id`	string	本次生成请求的唯一标识，可用于日志记录和问题排查。
`object`	string	响应对象类型。非流式响应通常为 `chat.completion`。
`created`	integer	响应创建时间的 Unix 秒级时间戳。
`model`	string	本次响应使用的模型 ID。
`choices`	array	模型生成结果列表。一般至少包含一项；请求多个候选结果时可能包含多项。
`choices[].index`	integer	当前候选结果在 `choices` 数组中的序号，从 `0` 开始。
`choices[].message`	object	模型返回的完整消息对象。
`choices[].message.role`	string	消息角色，正常文本回复通常为 `assistant`。
`choices[].message.content`	string、array 或 null	模型给最终用户的回复内容。普通文本回复通常为字符串；工具调用时可能为 `null`。
`choices[].message.reasoning_content`	string 或 null	模型的推理内容扩展字段，仅部分模型返回。
`choices[].message.reasoning`	string 或 null	另一种推理内容扩展字段，不保证与 `reasoning_content` 同时出现。
`choices[].message.tool_calls`	array	模型发起的工具调用列表。没有工具调用时通常不返回；出现时应结合 `finish_reason: "tool_calls"` 处理。
`choices[].finish_reason`	string 或 null	生成结束原因。常见值包括：`stop`（正常结束）、`length`（达到生成长度限制）、`tool_calls`（请求调用工具）、`function_call`（旧版函数调用）和 `content_filter`（内容被过滤）。流式生成尚未结束时通常为 `null`。
`choices[].logprobs`	object 或 null	token 对数概率信息。未请求或模型不支持时可能不返回或为 `null`。
`usage`	object	本次请求的 token 用量统计。
`usage.prompt_tokens`	integer	输入消息消耗的 token 数。
`usage.completion_tokens`	integer	模型生成消耗的 token 数。
`usage.total_tokens`	integer	总 token 数，通常为输入与生成 token 数之和。
`usage.prompt_tokens_details`	object	输入 token 的分类明细。
`usage.prompt_tokens_details.cached_tokens`	integer	报告的缓存命中 token 数；未命中、未统计或不支持时通常为 `0`。
`usage.prompt_tokens_details.text_tokens`	integer	报告的文本输入 token 数。
`usage.completion_tokens_details`	object	生成 token 的分类明细。
`usage.completion_tokens_details.reasoning_tokens`	integer	报告的推理 token 数。
`usage.completion_tokens_details.text_tokens`	integer	报告的文本生成 token 数。

对接时主要读取 choices[0].message.content 作为最终回复。choices[0].message.reasoning_content 是可能出现的扩展字段，不能作为必填字段处理。usage 用于展示 token 用量；明细字段是否出现以及统计口径随模型变化，不要用明细字段自行推导账单金额。finish_reason 为结束原因，普通完成通常为 stop。

5. 流式调用（可选）

将请求体中的 stream 改为 true，其余鉴权和地址不变：

{
  "model": "qwen3.8-flash",
  "messages": [{"role": "user", "content": "你好"}],
  "stream": true
}

响应为 SSE 事件，每条数据以 data: 开头。客户端按顺序读取 choices[0].delta.content 并拼接；如果模型返回 delta.reasoning_content，应单独处理。收到 data: [DONE] 表示流结束。流式事件中的 usage 可能为 null，如需用量可尝试传入 "stream_options": {"include_usage": true}。

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"你好"},"finish_reason":null}],"usage":null}

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"！"},"finish_reason":null}],"usage":null}

data: [DONE]

以上 SSE 仅展示主要字段；实际事件还可能包含 id、created、model 等字段。

6. Responses API 调用方式（可选）

除 Chat Completions 外，也可以使用 OpenAI 兼容的 Responses API。鉴权方式不变，请求地址为：

POST https://token.kelly.cloud

请求示例

Responses API 使用 input 传递输入内容。model 和 input 为必填字段：

对应的 JSON 请求体为：

{
  "model": "qwen3.8-flash",
  "input": "你好",
  "stream": false
}

python代码示例

返回示例

HTTP 200 时，非流式响应示例如下。ID、时间、内容和 token 数每次都可能不同：

{
  "id": "resp_7ae5b51540799aa3a1ab413ca4d79c97",
  "object": "response",
  "created_at": 1789372371,
  "status": "completed",
  "model": "qwen3.8-flash",
  "output": [
    {
      "id": "msg_7ae5b51540799aa3a1ab413ca4d79c97",
      "type": "message",
      "status": "completed",
      "role": "assistant",
      "content": [
        {
          "type": "output_text",
          "text": "你好！有什么我可以帮你的吗？",
          "annotations": []
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 62,
    "output_tokens": 32,
    "total_tokens": 94,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens_details": {
      "reasoning_tokens": 19
    }
  }
}

Responses API 不使用 choices[0].message.content。普通文本响应应在 output 数组中找到 type 为 message 的项目，再读取其 content 数组中 type 为 output_text 的 text。本例对应的读取路径为：

output[0].content[0].text

主要返回字段如下：

字段	类型	说明
`id`	string	本次响应的唯一标识。
`object`	string	对象类型，通常为 `response`。
`created_at`	integer	响应创建时间的 Unix 秒级时间戳。
`status`	string	响应状态，常见值包括 `completed`、`incomplete`、`failed` 和 `in_progress`。
`model`	string	本次响应使用的模型 ID。
`output`	array	输出项目列表，可能包含文本消息、推理内容或工具调用。
`output[].type`	string	输出项目类型。普通文本消息为 `message`。
`output[].content`	array	当前消息包含的内容列表。
`output[].content[].type`	string	内容类型。普通输出文本为 `output_text`。
`output[].content[].text`	string	模型生成的文本。
`usage.input_tokens`	integer	输入消耗的 token 数。
`usage.output_tokens`	integer	输出消耗的 token 数。
`usage.total_tokens`	integer	本次请求消耗的总 token 数。

使用响应 ID 继续对话

如果当前模型支持连续响应，可以把上一次返回的 id 作为 previous_response_id 传入下一次请求：

{
  "model": "qwen3.8-flash",
  "previous_response_id": "resp_7ae5b51540799aa3a1ab413ca4d79c97",
  "input": "请继续说明",
  "stream": false
}

previous_response_id 是否可用取决于实际模型。调用方应保存接口返回的响应 ID，不要自行生成。

7. 错误处理

请求失败时，应先检查 HTTP 状态码，再读取响应体中的 error.message；error.type、error.code 可辅助定位问题。错误响应的结构示例：

{
  "error": {
    "message": "model is required",
    "type": "错误信息",
    "code": "invalid_request",
    "param": ""
  }
}

常见情况包括：401 API Key 无效、403 令牌或用户无权调用、429 触发请求限流，以及 5xx 服务异常。请求格式或参数错误可能在不同处理阶段返回 400 或 5xx，不要只靠状态码判断错误类型；应结合 error.message 和 error.code。具体状态码和错误文案以实际响应为准。排查时保留请求时间、模型 ID、HTTP 状态码和响应中的错误信息，不要提供完整 API Key。

API 接口对接文档

api 接口对接文档#

1. 接口信息#

2. 请求参数#

3. 非流式请求示例#

4. 非流式成功响应#

响应字段说明#

5. 流式调用（可选）#

6. Responses API 调用方式（可选）#

请求示例#

返回示例#

使用响应 ID 继续对话#

7. 错误处理#