API 参考¶

腾讯公益推理平台提供 OpenAI 兼容接口和 Anthropic 兼容接口，两者使用同一个 API Key、同一份模型目录。

基本信息¶

项目	值
OpenAI 兼容 Base URL	`https://freeinference.qq.com/v1`
Anthropic 兼容 Base URL	`https://freeinference.qq.com/anthropic`
请求与响应格式	JSON（UTF-8）；流式输出为 Server-Sent Events
鉴权	`Authorization: Bearer <API Key>`，或 `X-API-Key: <API Key>`

API Key 以 hyi- 开头，在控制台中创建，见快速开始。Bearer 区分大小写，写成 bearer 会被当作没有携带密钥。

接口只能从服务端或本地程序调用：浏览器中的网页不能跨域直接请求，否则会被浏览器拦截；这也避免了把 API Key 暴露在前端代码里。

接口一览¶

方法	路径	说明
`POST`	`/v1/chat/completions`	对话补全，兼容 OpenAI Chat Completions
`GET`	`/v1/models`	模型列表
`POST`	`/v1/responses`	兼容 OpenAI Responses 接口，服务端不保存对话
`POST`	`/v1/embeddings`	文本向量，仅适用于模型目录中的向量模型
`POST`	`/anthropic/v1/messages`	兼容 Anthropic Messages，供 Claude Code 等工具使用
`POST`	`/anthropic/v1/messages/count_tokens`	估算一次 Messages 请求的输入 token 数

路径均相对于服务地址 https://freeinference.qq.com。

对话补全¶

POST /v1/chat/completions，请求体与 OpenAI Chat Completions 相同，常用字段：

字段	说明
`model`	必填，模型 ID，见模型列表
`messages`	必填，对话消息列表
`stream`	为 `true` 时以流式返回，见下文
`max_tokens`	本次最多生成的 token 数；超过模型的最大输出时按最大输出处理
`temperature`、`top_p`、`stop`	采样参数，所有模型都接受
`tools`、`tool_choice`	工具调用，只对支持工具调用的模型生效
`response_format`	结构化输出，只对支持结构化输出的模型生效

平台对参数的处理方式：

模型不支持的参数会被直接忽略，不会报错。各模型额外接受哪些参数，见模型列表。
取值超出范围（例如 temperature 不在 0–2 之间），或缺少必填字段，返回 400。
向只接受文本的模型发送图片等内容，返回 400。

流式输出¶

设置 "stream": true 后，响应的 Content-Type 为 text/event-stream，每个数据块是一行 data: {JSON}，结束时发送 data: [DONE]：

curl -N --fail-with-body 'https://freeinference.qq.com/v1/chat/completions' \
  -H "Authorization: Bearer $TENCENT_INFERENCE_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "deepseek-v4.1-flash",
  "messages": [{"role": "user", "content": "用三句话介绍量子计算"}],
  "stream": true
}
JSON

自己解析流时请注意：

最后一个数据块带有 finish_reason 和本次请求的 usage（token 用量），不需要额外设置 stream_options。
长时间没有新内容时，平台会发送以冒号开头的保活行（: keepalive），解析时忽略即可。
生成中途出错时，流里会出现一个带 error 字段的数据块，随后连接关闭，不会发送 data: [DONE]。

生成较长的内容时建议使用流式输出：非流式请求超过平台的时长上限会返回 504。

模型列表¶

GET /v1/models 不强制鉴权：

携带有效的 API Key 时，返回你的账号可以调用的模型；
不携带或携带了无效的 API Key 时，返回对所有人公开的模型，不会返回 401。所以能拿到模型列表，并不说明 API Key 有效。

每个模型包含以下字段：

字段	说明
`id`	模型 ID，调用时填入 `model`
`name`	显示名称
`context_length`	上下文长度（token）
`max_output_length`	单次最大输出（token）
`input_modalities`、`output_modalities`	支持的输入、输出类型，如 `text`
`supported_sampling_parameters`	模型声明支持的请求参数
`supported_features`	支持的能力：`tools` 为工具调用，`structured_outputs`、`json_mode` 为结构化输出

Responses 接口¶

POST /v1/responses 兼容 OpenAI Responses 接口，支持流式输出。平台在内部把它转换为对话补全，因此：

服务端不保存对话，previous_response_id 会返回 404；多轮对话需要每次在 input 中带上完整上下文。
web_search、file_search、code_interpreter 等 OpenAI 托管工具不可用，会被忽略。

Anthropic 兼容接口¶

POST /anthropic/v1/messages 接受 Anthropic Messages 格式的请求，支持流式输出与工具调用。与 OpenAI 兼容接口相比：

max_tokens 为必填项。
model 必须是平台的模型 ID。平台不提供 Claude 模型，请求 claude-… 这样的模型名会返回 404。
thinking、top_k、cache_control 等 Anthropic 专有字段会被忽略。
/anthropic/v1/messages/count_tokens 返回的是平台按通用分词器估算的数值，与模型实际计费的 token 数可能略有出入。

在 Claude Code 中的配置方法见 Claude Code。

curl --fail-with-body 'https://freeinference.qq.com/anthropic/v1/messages' \
  -H "x-api-key: $TENCENT_INFERENCE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  --data-binary @- <<'JSON'
{
  "model": "deepseek-v4.1-flash",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "你好"}]
}
JSON

请求头¶

Authorization、X-API-Key: 携带 API Key，二选一：Authorization: Bearer <API Key> 或 X-API-Key: <API Key>。两者都带时以 Authorization 为准。
X-Request-ID: 可选。自定义的请求 ID，会在响应头 X-Request-ID 中原样返回；不传时平台自动生成一个。反馈问题时请附上这个 ID。
X-Session-ID: 可选。给同一会话的多个请求打上相同的标记（不超过 128 个字符），便于平台按会话关联请求。不影响鉴权和额度。
X-Reasoning-Passthrough: 可选，只对 /v1/chat/completions 生效。默认情况下，推理模型的思考过程会放在 reasoning_content 字段里一并返回；设为 false 时去掉该字段，适合只认标准 OpenAI 字段的客户端。
anthropic-version: 可选，Anthropic SDK 会自动发送，平台不校验它的取值。

错误码¶

出错时返回相应的 HTTP 状态码，请以状态码为准判断错误类型。OpenAI 兼容接口的错误体形如：

{"error": {"type": "unknown", "message": "Model 'no-such-model' not found", "code": 404}}

其中 type 只是粗略分类，不要依赖它。Anthropic 兼容接口的错误体遵循 Anthropic 格式：

{"type": "error", "error": {"type": "not_found_error", "message": "Model 'no-such-model' not found"}}

状态码	常见的 `message`	含义与处理
`400`	`Invalid JSON or schema in request body`	请求体不是合法 JSON、缺少必填字段或取值超出范围
`401`	`Missing API key. …`	没有携带 API Key，检查请求头
`401`	`Invalid or expired API key`	API Key 无效、已被删除或重新生成，或账号已停用
`403`	`Email not verified. …`	账号邮箱尚未验证，先在控制台完成验证
`404`	`Model '…' not found`	模型 ID 不存在，或未对你的账号开放；使用 `GET /v1/models` 返回的 ID
`429`	见调用限制与额度	并发数、每日额度或认证失败次数达到上限
`500`、`502`、`503`		上游模型服务暂时不可用，稍后重试
`504`	`Gateway Timeout`	请求超过平台的时长上限；长内容请使用流式输出

上游出错时，message 末尾通常带有 (request_id: …)。持续出错时，请把它和响应头里的 X-Request-ID 一起提供给平台，联系平台运营方。

调用限制与额度¶

为了让更多人用上公益推理资源，平台对每个账号有以下限制。具体数值以控制台 Dashboard 页面的显示为准，那里会显示剩余额度、每日上限、重置时间与并发上限。

并发请求数: 同一账号同时进行中的请求数有上限，流式请求在输出结束前一直占用一个名额。超出时立即返回 429（Too many concurrent requests），并带有 Retry-After: 1。Cline、Claude Code 等编程助手可能同时发出多个请求，遇到这个错误时减少同时运行的会话即可。
每日额度: 每个账号每天有用量上限，按 UTC 零点重置。用完后返回 429（Daily cost quota exceeded），响应头 Retry-After 与 X-RateLimit-Reset 给出重置时间。
认证失败: 短时间内来自同一 IP 的大量请求携带无效的 API Key 时，该 IP（IPv6 按 /64 网段计算）会被临时封禁，期间所有请求都返回 429（Too many authentication failures from this IP），即使 API Key 正确。更换或删除 API Key 后，请同步更新所有还在使用旧密钥的脚本和工具。