对话补全

OpenAI 兼容的 Chat Completions 接口。Swarmix 的核心端点，路由到当前已配置和已上架的上游模型。

POST/v1/chat/completions

给定一组聊天消息，模型返回补全。协议与 OpenAI POST /v1/chat/completions保持兼容，兼容 OpenAI 的 SDK 和工具可以直接使用。

厂商高级参数以模型文档为准

阿里百炼、火山方舟、腾讯混元都可以通过 OpenAI-compatible 方式接入，但developer role、strict 结构化输出、视觉输入限制等能力存在模型级差异。需要固定厂商能力时，请参考厂商兼容说明。

请求头

Header	必填	示例	说明
`Authorization`	是	`Bearer sk-swx-xxx`	Swarmix 签发的 API Key
`Content-Type`	是	`application/json`	请求体格式
`Accept`		`text/event-stream`	流式响应时建议带上

字段	类型	必填	说明
`model`	string	是	模型 ID，例如 `aliyun/qwen-max`、`aliyun/deepseek-r1`。当前公开 API 不承诺`@chat` 这类分组别名作为 `model` 参数。
`messages`	array	是	消息列表，每条为 `{role, content}`。平台接受 system / developer / user / assistant / tool / function；跨厂商生产流量建议优先使用 system / user / assistant / tool。
`stream`	boolean		`true` 返回 SSE 流，`false` 返回一次性 JSON。
`temperature`	number		0-2，默认 1。越高越发散，越低越确定。
`top_p`	number		0-1，核采样。通常与 temperature 二选一。
`max_tokens`	integer		响应最大 token 数。会影响预扣金额，建议按业务场景合理设置。
`tools`	array		Function Calling 定义。使用新版 tools 格式，非已废弃的 functions。
`tool_choice`	string \| object		`none` / `auto` / `{type:"function", function:{name:"..."}}`
`response_format`	object		`{type:"json_object"}` 强制 JSON 输出。
`stop`	string \| array		停止生成的序列，最多 4 个。
`seed`	integer		确定性采样种子，部分上游厂商不支持。
`stream_options`	object		`{include_usage:true}` 时最后一个 chunk 会带 token usage。

并非所有参数都适用所有厂商

例如 seed 部分厂商不支持；tools 通常在 qwen 2.5+、deepseek、hunyuan-turbo 等模型上支持。未支持的参数可能被上游忽略，实际效果以模型能力为准。

字段	类型	说明
`id`	string	本次补全对象 ID。
`model`	string	实际路由到的上游模型 ID。
`choices[].message.content`	string	生成的文本。
`choices[].message.tool_calls`	array	function calling 时的工具调用列表。
`choices[].finish_reason`	string	stop / length / tool_calls / content_filter。
`usage.prompt_tokens`	integer	输入 token 数。
`usage.completion_tokens`	integer	输出 token 数。
`usage.total_tokens`	integer	prompt + completion，用于计费。

当前 Router 会返回 x-request-id 响应头，用于和请求日志、工单排障关联。实际命中的 provider 和上游模型请在 Console 请求日志中查看。

完整的 HTTP 状态码与当前错误响应说明见错误码对照。常见错误包括：