端点
https://vibetoken.cn/v1 并使用你的 VibeToken API key。
请求头
请求体
string
必填
模型 ID。接受的写法：VibeToken id（
deepseek/deepseek-v4-pro）、/v1/models 中 official_name 给出的厂商官方名（claude-opus-4-8、gpt-5.4、gemini-2.5-flash，不区分大小写），或该模型的 aliases 之一（改名前的旧 id、预览期拼法）。除此之外不做推断：claude-sonnet-4-5-20250929 这类厂商快照 id 是另一个模型版本，除非正好提供该快照，否则返回 404。规则见模型 ID，主推对话模型见模型总览，完整列表可用实时的模型 API。响应中的 model 字段回显你发送的写法。array
必填
OpenAI 消息数组：
[{role: "user", content: "..."}]。支持具备视觉能力的模型使用多模态内容片段。number
采样温度，0–2。默认值取决于具体模型。
number
核采样概率，0–1。
boolean
若为
true，响应将是一个 Server-Sent Events 流，由 data: {chunk}\n\n 形式的数据块组成，并以 data: [DONE] 结束。string | array
停止序列。
integer
用于可复现输出的采样随机种子。
object
例如
{ "type": "json_object" }，用于支持 JSON 模式的模型。number
根据 token 是否已在文本中出现过对新 token 进行惩罚，取值 -2 到 2。
number
根据 token 在文本中出现的频率对新 token 进行惩罚，取值 -2 到 2。
array
针对支持工具调用的模型的工具/函数定义。
string
可选的 OpenAI 风格缓存分区键。共享同一个键的请求会路由到
同一个提示缓存。VibeToken 会自动设置一个按终端用户区分的键
（参见提示缓存）；仅在需要覆盖时才传入你自己的键——
例如在某个工作区内跨用户共享缓存。
示例
响应
usage.prompt_tokens_details.cached_tokens 始终返回，
因此缓存命中率可以直接用 cached_tokens / prompt_tokens 计算，
不必额外处理字段缺失的情况。命中缓存时，该对象还会带上别名字段：
cached_tokens— OpenAI 标准的从缓存中提供的 token 计数 （缓存读取），按该模型折扣后的缓存读取（Cache Read）费率计费。cache_read_input_tokens— 同一数值的别名，为保持一致性而一并给出。cache_creation_input_tokens— 本次请求写入缓存的 token 数（仅在该模型定义了缓存写入费率时出现）。
cached_tokens 始终返回，为零时也会返回；另外两个别名字段在为零时省略。
相同的明细也会出现在流式输出最后一个数据块的 usage 中。
只有当 prompt 超过各家厂商的最小可缓存前缀长度后才会产生缓存，
因此较短的 prompt 无论重复多少次，cached_tokens 都是 0。
推理模型
推理模型（DeepSeek、GLM、Kimi、Qwen、MiniMax、GPT-5、Gemini 3 等）会产生两类输出 token：- 推理 token —— 模型给出答案之前的思考过程。单独放在
choices[].message.reasoning_content（流式为delta.reasoning_content），不会出现在content里。 - 正文 token —— 最终回答本身，放在
content里。
usage.completion_tokens 是两者之和。
即使只回答一句话，也可能产生上千 token 的费用。
max_tokens 通常能限制推理，但最终由上游决定。 绝大多数模型会把推理计入 max_tokens，
额度用完就在思考中途停下——所以给推理模型设一个很小的 max_tokens，得到的是被截断的思考过程，
而不是一个简短的回答。少数上游模型不把推理计入上限，会一直思考到自然结束，
实际输出可能比你传的数值高出一个数量级。请把 max_tokens 当作一个请求，而不是费用上限；
实际花费以 usage.completion_tokens 为准。
正文的第一个字会来得较晚。 推理先流式返回，所以第一个 content token 之前的等待时间
基本等于整个思考阶段。建议边流式展示 reasoning_content，或显示进度状态，而不是干等 content。
include_reasoning: false 可以让响应中不返回 reasoning_content。
模型仍然会生成这些 token 并照常计费，这个开关只控制是否返回。
提示缓存
对于上游支持提示缓存的模型，VibeToken 会自动缓存—— 无需任何标志。命中缓存的输入 token 按该模型折扣后的 缓存读取（Cache Read）费率计费；若该模型定义了缓存写入（Cache Write） 费率，则创建缓存条目的首次请求按该费率计费。这两种费率（若已定义）均显示在各模型的定价页面上。按用户隔离
缓存是按终端用户隔离的：你的客户缓存的前缀 绝不会与其他客户共享，也无法被其读取——即便他们通过 同一个 VibeToken 账户发送完全相同的提示词。VibeToken 会派生出 一个稳定、不透明的按用户 token，并将其接入 上游所遵循的缓存原语。对于接受 OpenAI 风格prompt_cache_key 的模型，
仅当你想覆盖 VibeToken 的按用户分区时，才需要传入你自己的键
（例如在某个工作区内跨用户共享缓存）。
无需启用任何东西——它在每次对话请求中都自动生效。该机制
在 design/18_cache-architecture.md 中有详细描述。
阈值与 TTL
上游缓存通常需要**≥1024 个输入 token** 才会生效，具体阈值以各模型的 上游文档为准。 缓存前缀在其最后一次使用后存活约 5 分钟。缓存对 长且稳定的系统提示词和工具定义有益；请将静态 内容放在提示词开头，把可变内容放在末尾。流式输出
设置"stream": true 即可接收 SSE 数据块。每个数据块都是一个 chat.completion.chunk 对象，其 delta 中包含增量内容。数据流以 data: [DONE] 结束。
delta.reasoning_content 数据块流式返回，随后是 delta.content 中的最终回答。传入 include_reasoning: false 可不返回推理数据块（推理仍会生成并计费，该参数只控制是否返回）。使用 OpenAI SDK 时，可通过 getattr(chunk.choices[0].delta, "reasoning_content", None) 读取。
最后一个数据块携带 finish_reason 和本次请求的 usage（含上文的缓存明细），之后是 data: [DONE]。
错误。 流开始前发生的错误以普通 JSON 错误返回，并带有对应的 HTTP 状态码。流开始后状态码已是 200，之后的错误会以一个数据块返回：顶层 error 对象（message / type / code 与 HTTP 错误体相同），且 finish_reason: "error"，随后是 data: [DONE]。OpenAI SDK 会将其作为 APIError 抛出。