接口说明
POST /v1/chat/completions：除 Claude 外全部对话模型共用的 OpenAI Chat Completions 兼容协议，同步或 SSE 流式，按 token 计费
POST/v1/chat/completions
请求体、响应体与 OpenAI 官方 Chat Completions 一致，支持非流式和流式（SSE）。各系列模型页只写与本页的差异。
| 项 | 值 |
|---|---|
| 模型 | 除 Claude 外的全部对话模型（deepseek、gpt、gemini 等系列；Claude 见 Claude 系列），可用模型见模型列表 |
| 模式 | 同步；stream: true 时为 SSE 流式 |
| 计费 | 按 token，输入与输出分别计价，价格以定价页为准 |
各系列差异：
| 系列 | 差异 |
|---|---|
| Claude | 不走本协议，使用 Anthropic 原生 POST /v1/messages；用本接口请求 claude-* 返回 400 |
| GPT | 上游为 OpenAI 官方实现，支持完整 OpenAI 参数集（多模态输入、结构化输出、工具调用等） |
| Gemini | 部分 OpenAI 参数不属于稳定兼容范围；gemini-3.1-pro-preview 支持视频输入 |
快速开始
curl https://api.vibelab.me/v1/chat/completions \
-H "Authorization: Bearer $LOOPTOKEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "deepseek-v4-flash",
"messages": [{"role": "user", "content": "什么是人工智能?"}]
}'上面的 curl 是非流式请求，响应如下：
{
"id": "chatcmpl-abc123",
"object": "chat.completion",
"created": 1779964861,
"model": "deepseek-v4-flash",
"choices": [
{
"index": 0,
"message": {
"role": "assistant",
"content": "人工智能(AI)是计算机科学的一个分支,致力于创建能够模拟人类智能行为的系统。"
},
"finish_reason": "stop"
}
],
"usage": {"prompt_tokens": 15, "completion_tokens": 42, "total_tokens": 57}
}模式选择
| 模式 | 怎么传参 | 说明 |
|---|---|---|
| 非流式 | 省略 stream 或传 false | 一次返回完整响应 |
| 流式 | stream: true（curl 加 -N） | SSE，见流式响应 |
| 多模态（图片） | messages[].content 用内容块数组 | 见图片内容块，各模型支持范围以模型页为准 |
请求参数
平台处理的字段
以下字段会被平台读取或改写：
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
model | string | 是 | - | 缺失或为空 → 400 invalid_request；不在该 key 的模型白名单内 → 403 model_not_allowed；平台没有该模型 → 404 model_not_found |
messages | array | 是 | - | 必须为非空数组；content 支持字符串或多模态数组（平台取其中的 text 块估算用量）；缺失或不合法 → 400 invalid_request |
stream | boolean | 否 | false | true 时走 SSE 流式响应；传 null 或省略都按 false 处理 |
max_tokens | integer | 否 | - | 参与请求发起前的费用预扣估算，见计费 |
stream_options | object | 否 | - | 仅 stream: true 时生效：平台自动注入 include_usage: true（与你传入的值合并），流末尾必定返回 usage |
透传参数
上游网关已适配，平台原样透传；是否生效、取值边界以所选模型实际行为为准。本表未列出的其他参数同样原样透传，平台不做额外处理。
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
temperature | float | 否 | - | 采样温度，取值 [0, 2) |
top_p | float | 否 | - | 核采样概率阈值，取值 (0, 1] |
max_completion_tokens | int | 否 | - | 生成最大 Token 数（含推理 Token），上游优先于 max_tokens 读取；平台预扣估算只读 max_tokens |
n | int | 否 | - | 生成候选回复数量 |
stop | array | 否 | - | 停止生成的字符串列表 |
seed | int | 否 | - | 随机种子，提升可复现性 |
presence_penalty | float | 否 | - | 存在惩罚，取值 [-2, 2] |
tools | array | 否 | - | 可调用的工具列表 |
tool_choice | string/object | 否 | - | 工具调用策略："auto" / "none" 等 |
response_format | object | 否 | - | 输出格式约束，如 {"type": "json_object"} |
messages 结构
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
messages[].role | string | 是 | - | system / developer / user / assistant / tool |
messages[].content | string/array | 是 | - | 消息文本，或模型支持的多模态内容对象数组 |
| 角色 | 说明 |
|---|---|
system | 系统指令，设定模型行为（人格、约束、输出格式） |
user | 用户输入 |
assistant | 模型回复（多轮对话历史） |
tool | 工具执行结果（需配合 tool_call_id） |
图片内容块
支持视觉理解的模型可在 user 消息中使用内容对象数组。各模型支持范围以对应模型文档为准。
| 参数 | 类型 | 必填 | 默认 | 说明 |
|---|---|---|---|---|
content[].type | string | 是 | - | 文本为 text，图片为 image_url |
content[].text | string | type=text 时是 | - | 文本内容 |
content[].image_url.url | string | type=image_url 时是 | - | 公网图片 URL 或 Base64 Data URL |
content[].image_url.detail | string | 否 | - | 图片精度：low、high 或 auto |
Base64 图片必须使用 data:image/...;base64,... Data URL。gemini-3.1-pro-preview 为兼容其视频理解链路，也接受 data:video/mp4;base64,...；其他模型把视频、PDF 等非图片 MIME 放入 image_url 时，平台在扣费前返回 HTTP 400 invalid_image_url。
请求示例
多轮对话：
{
"model": "deepseek-v4-flash",
"messages": [
{"role": "system", "content": "你是一个有帮助的 AI 助手"},
{"role": "user", "content": "什么是量子计算?"},
{"role": "assistant", "content": "量子计算是利用量子力学原理进行信息处理的计算方式..."},
{"role": "user", "content": "它和经典计算有什么区别?"}
],
"temperature": 0.7,
"max_tokens": 2048
}响应
| 字段 | 类型 | 说明 |
|---|---|---|
id | string | 请求唯一标识 |
object | string | 非流式 "chat.completion"，流式 "chat.completion.chunk" |
created | int64 | 创建时间戳（Unix 秒） |
model | string | 平台尽力改写为你请求时使用的平台模型名 |
choices[].index | int | 选项索引 |
choices[].message | object | 回复消息（非流式）；role 固定为 "assistant"，content 为回复文本 |
choices[].delta | object | 增量消息（流式，字段同 message） |
choices[].finish_reason | string | "stop" / "length" / "tool_calls" |
usage.prompt_tokens | int | 输入 Token 数 |
usage.completion_tokens | int | 输出 Token 数 |
usage.total_tokens | int | 总 Token 数 |
流式响应
stream: true 时为标准 SSE：每个事件以 data: 开头，内容为一个 JSON chunk；末尾以 data: [DONE] 结束。平台强制注入 stream_options.include_usage: true，最后一个 chunk（choices 为空数组）携带完整 usage。平台尽力将 model 改写为你请求时的平台模型名；个别数据块不含该字段时原样透传。
data: {"id":"chatcmpl-ghi789","object":"chat.completion.chunk","created":1779964861,"model":"deepseek-v4-flash","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
data: {"id":"chatcmpl-ghi789","object":"chat.completion.chunk","created":1779964861,"model":"deepseek-v4-flash","choices":[{"index":0,"delta":{"content":"春"},"finish_reason":null}]}
...
data: {"id":"chatcmpl-ghi789","object":"chat.completion.chunk","created":1779964861,"model":"deepseek-v4-flash","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: {"id":"chatcmpl-ghi789","object":"chat.completion.chunk","created":1779964861,"model":"deepseek-v4-flash","choices":[],"usage":{"prompt_tokens":12,"completion_tokens":86,"total_tokens":98}}
data: [DONE]计费
- 按 token 计费，输入（prompt）与输出（completion）分别计价，价格见定价页。流式与非流式均在响应中返回
usage（流式在末尾 chunk）。 - 请求发起前按估算用量预扣：输入按消息文本估算，输出取
min(模型最大输出, max_tokens)；未传max_tokens时受平台冻结上限约束。响应完成后按实际usage结算，多退少补。 - 上游失败、渠道耗尽时预扣全额退回。
错误
错误体为 {"error": {"message", "type", "code", "request_id"}}，type 与 code 相同，完整格式见错误码。
| HTTP | code | 触发场景 | 处理 |
|---|---|---|---|
| 400 | invalid_request | 请求体不是合法 JSON，model 缺失或为空，messages 缺失、不合法或为空数组 | 按 message（如 missing model、messages required）修正请求 |
| 400 | invalid_image_url | Data URL 格式不合法或不是图片 MIME（gemini-3.1-pro-preview 例外接受 video/mp4） | 改用合法的 data:image/...;base64,...，见图片内容块 |
| 400 | context_length_exceeded | 上游判定输入超出模型上下文窗口 | 缩短 messages 或换用更长上下文的模型 |
| 400 | 上游 code（缺省 invalid_request_error） | 上游返回 400，表示请求本身有问题（违规内容、非法参数值等） | 按 message 修改请求，重试不会改变结果 |
| 402 | insufficient_credits | 账户余额不足以覆盖预扣费用 | 充值后重试 |
| 403 | model_not_allowed | model 不在该 API Key 的模型白名单内 | 调整 Key 的模型白名单或换模型 |
| 404 | model_not_found | 平台没有该模型 | 对照模型列表 |
| 502 | upstream_error | 上游返回错误，或最多 3 个渠道均失败 | 指数退避重试 |
| 503 | no_available_channel | 该模型当前没有可用渠道 | 稍后重试 |
| 504 | upstream_timeout | 非流式请求上游 5 分钟内未完成（不换渠道重试）；流式请求上游 1 分钟内未返回响应头且各渠道均超时 | 长输出改用流式 |
更多错误码见错误码。
注意事项
- 请求体超过 128 MiB → 读取被截断，按非法 JSON 返回 400
invalid_request。 - 同时传
max_tokens和max_completion_tokens→ 上游优先读max_completion_tokens，平台预扣只读max_tokens。 - 流式请求首字节写出后上游失败 → 不再换渠道重试。
- 响应中的
model→ 平台改写为你请求的模型名，不暴露上游模型名。