POST/v1/chat/completions

Chat Completions API

创建对话补全响应。接口兼容 OpenAI Chat Completions 的核心请求与响应格式，可直接使用 OpenAI 官方 SDK（Python / Node.js）接入，只需修改 base_url 和 api_key。流式输出、Function Calling、视觉理解等能力以模型详情页的参数与协议声明为准。

✓ 协议支持范围

/v1/chat/completions 支持模型目录中明确声明该协议的可用模型。预告模型会展示计划支持的协议，但在状态变为可用前不能调用。

请求端点

POSThttps://nexusflow.hk/v1/chat/completions

请求头

Header	值	必选	说明
`Authorization`	`Bearer <API_KEY>`	*	API 密钥。在控制台创建后以 sk-air- 开头。
`Content-Type`	`application/json`	*	请求体格式，固定为 JSON。Content-Length 可选，支持 HTTP/1.1 chunked 请求体。

请求参数

参数	类型	必选	说明
`model`	string	*	模型 ID。例如 qwen3.5-plus、deepseek-v4.1-flash 等。查看列表 →
`messages`	array	*	对话消息数组。每条消息包含 role（system / user / assistant / tool）和 content 字段。content 可以是字符串或内容数组；多模态内容是否可用取决于模型能力。
`stream`	boolean	-	是否启用流式输出。启用后以 SSE（Server-Sent Events）格式逐 token 返回。默认：`false`
`temperature`	number	-	采样温度，范围 [0, 2)。值越高输出越随机，值越低越确定。建议与 top_p 二选一调节。默认：`1.0`
`top_p`	number	-	核采样概率阈值，范围 (0, 1]。模型仅从累计概率达到 top_p 的 token 集合中采样。默认：`1.0`
`max_tokens`	integer	-	生成的最大 token 数。不同模型有不同上限，未设置时使用模型默认值。
`tools`	array	-	可用工具/函数定义列表，用于 Function Calling。每个工具包含 type 和 function 字段。
`tool_choice`	string \| object	-	工具调用策略。稳定支持 "auto"、"none"，或 {"type":"function","function":{"name":"..."}} 指定函数。思考模式模型不建议强制指定工具。默认：`"auto"`
`stop`	string \| string[]	-	停止词或停止词数组（最多 4 个）。模型生成到停止词时立即结束输出。
`frequency_penalty`	number	-	频率惩罚，范围 [-2.0, 2.0]。正值根据 token 在已生成文本中出现的频率进行惩罚，降低重复。默认：`0`
`presence_penalty`	number	-	存在惩罚，范围 [-2.0, 2.0]。正值根据 token 是否已出现过进行惩罚，提升话题多样性。默认：`0`
`enable_thinking`	boolean	-	是否开启思考模式。仅混合思考模型支持 true/false 开关；仅思考模型即使传 false 也会继续思考。
`stream_options`	object	-	流式请求附加选项。设置 {"include_usage": true} 可在最后一个 SSE chunk 中返回 token 用量。
`response_format`	object	-	响应格式控制。支持 {"type":"text"}（默认）和 {"type":"json_object"}（JSON 模式）。

代码示例

curl

curl -X POST https://nexusflow.hk/v1/chat/completions \
  -H "Authorization: Bearer sk-air-your-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5-plus",
    "messages": [
      {"role": "system", "content": "你是一个有帮助的助手。"},
      {"role": "user", "content": "什么是机器学习？"}
    ],
    "temperature": 0.7,
    "max_tokens": 1000
  }'

响应格式（非流式）

非流式请求返回完整的 JSON 对象，object 字段值为 "chat.completion"。

响应示例

json

{
  "id": "chatcmpl-abc123xyz789",
  "object": "chat.completion",
  "created": 1709123456,
  "model": "qwen3.5-plus",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "机器学习是人工智能的一个分支..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 28,
    "completion_tokens": 256,
    "total_tokens": 284
  }
}

响应字段

字段	类型	说明
`id`	string	本次请求的唯一标识符，如 chatcmpl-abc123xyz789。
`object`	string	固定为 "chat.completion"。
`created`	integer	创建时间，Unix 时间戳（秒）。
`model`	string	实际使用的模型名称。
`choices`	array	生成结果数组（通常包含 1 个元素）。
`choices[].index`	integer	结果在数组中的索引位置。
`choices[].message.role`	string	消息角色，固定为 "assistant"。
`choices[].message.content`	string \| null	生成的文本内容。当模型调用工具时可能为 null。
`choices[].message.reasoning_content`	string	推理模型（如 QwQ）返回的思维链内容。非推理模型不返回此字段。
`choices[].message.tool_calls`	array	工具调用请求数组。仅在模型决定调用工具时返回。
`choices[].finish_reason`	string	停止原因：stop（自然结束）、length（达到 max_tokens）、tool_calls（调用工具）。
`usage.prompt_tokens`	integer	输入消耗的 token 数。
`usage.completion_tokens`	integer	输出消耗的 token 数。
`usage.total_tokens`	integer	总 token 消耗（prompt_tokens + completion_tokens）。

流式响应格式（SSE）

当 stream: true 时，响应以 Server-Sent Events (SSE) 格式逐步返回。每条事件以 data: 开头，最后以 data: [DONE] 标记结束。每个 chunk 的 object 字段值为 "chat.completion.chunk"。

SSE 数据格式

text

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1709123456,"model":"qwen3.5-plus","choices":[{"index":0,"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1709123456,"model":"qwen3.5-plus","choices":[{"index":0,"delta":{"content":"机器"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1709123456,"model":"qwen3.5-plus","choices":[{"index":0,"delta":{"content":"学习"},"finish_reason":null}]}

data: {"id":"chatcmpl-abc123","object":"chat.completion.chunk","created":1709123456,"model":"qwen3.5-plus","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":28,"completion_tokens":256,"total_tokens":284}}

data: [DONE]

Chunk 字段说明

字段	类型	说明
`id`	string	与完整响应相同的请求 ID。
`object`	string	固定为 "chat.completion.chunk"。
`choices[].delta.role`	string	仅在首个 chunk 中出现，值为 "assistant"。
`choices[].delta.content`	string	本次 chunk 的增量文本内容。
`choices[].delta.reasoning_content`	string	本次 chunk 的增量思维链内容（推理模型）。
`choices[].delta.tool_calls`	array	工具调用的增量数据（流式 Function Calling）。
`choices[].finish_reason`	string \| null	仅在最后一个 chunk 中非 null，表示停止原因。
`usage`	object	仅当 stream_options.include_usage 为 true 时，在最终 chunk 中返回 token 用量。

提示：使用 OpenAI SDK 时无需手动解析 SSE，SDK 会自动处理流式响应并提供迭代器接口。仅在使用 cURL 或原生 HTTP 客户端时需要自行解析 SSE 数据。

协议透传说明

NexusFlow 的 /v1/chat/completions 与 OpenAI Chat Completions 协议完全透传：请求体原样转发上游，响应原样回传。tools、tool_choice、response_format、enable_thinking、thinking_budget、enable_search、search_options、seed、top_k、logprobs、stream_options 等扩展字段都可直接使用，具体支持范围以模型为准。

计费说明

阶梯计费

通义千问、GLM 等系列模型采用按请求输入 token 数分阶梯计费。单次请求的 prompt token 总量决定该请求适用的价格档位，输入和输出分别按对应档位的单价计费。

示例：qwen3-max输入 Token 范围输入价格 (¥/M)输出价格 (¥/M)

第一阶0 ~ 32K2.510

第二阶32K ~ 128K416

第三阶128K ~ 256K728

例如：一次请求含 50K 输入 token + 2K 输出 token，则输入按 ¥4/M 计费、输出按 ¥16/M 计费（落入第二阶）。完整阶梯价格见定价页。

上下文缓存（Prompt Caching）

通过 /v1/messages（Anthropic 协议）调用时支持上下文缓存。对重复的 system prompt 或长文档，上游会自动缓存 prompt 前缀，后续请求命中缓存部分享受折扣：

Token 类型计费倍率说明

cache_creation_input_tokens1.25x 输入价首次写入缓存，略高于常规输入

cache_read_input_tokens0.1x 输入价命中缓存，享 90% 折扣

input_tokens（非缓存部分）1x 输入价正常计费

/v1/chat/completions 支持通过 enable_context_caching: true 参数启用显式缓存。/v1/messages（Anthropic 协议）支持 cache_control 内容块注解。两种协议均自动享受隐式缓存折扣。

注意事项

不同模型的 max_tokens 上限不同，请参考模型列表了解各模型限制。
temperature 和 top_p 建议只调节其中一个，同时设置可能产生不可预期的结果。
流式输出时，只有最后一个 chunk 的 finish_reason 为非 null 值，代表生成结束。
图像理解功能建议使用 Qwen-VL 系列等多模态模型。content 需传入数组格式包含 image_url 类型。
Function Calling 推荐使用 Qwen、DeepSeek、GLM 等支持工具调用的模型系列。
思考模式（enable_thinking）必须按模型 ID 使用；支持矩阵见参数矩阵。
请求体与上游协议透传，文档之外的扩展字段（如 thinking_budget、enable_search、search_options）可直接使用，具体支持以模型为准。
完整参数说明与模型兼容矩阵见参数矩阵。