> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vibetoken.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 对话补全

> 兼容 OpenAI 的对话补全端点。同步调用，可选流式输出。

## 端点

```
POST https://vibetoken.cn/v1/chat/completions
```

与 OpenAI 的 [Chat Completions API](https://platform.openai.com/docs/api-reference/chat) 完全兼容，可直接替换使用。只需将你现有的 OpenAI 客户端指向 `https://vibetoken.cn/v1` 并使用你的 VibeToken API key。

## 请求头

| Header          | Value                       |
| --------------- | --------------------------- |
| `Authorization` | `Bearer sk-rb-xxxxxxxxxxxx` |
| `Content-Type`  | `application/json`          |

## 请求体

<ParamField body="model" type="string" required>
  模型 ID。当前主推的对话模型集合见[模型总览](/overview)，完整列表可使用实时的[模型 API](/api-reference/models)。
</ParamField>

<ParamField body="messages" type="array" required>
  OpenAI 消息数组：`[{role: "user", content: "..."}]`。支持具备视觉能力的模型使用多模态内容片段。
</ParamField>

<ParamField body="temperature" type="number">
  采样温度，0–2。默认值取决于具体模型。
</ParamField>

<ParamField body="max_tokens" type="integer">
  生成的最大 token 数。
</ParamField>

<ParamField body="top_p" type="number">
  核采样概率，0–1。
</ParamField>

<ParamField body="stream" type="boolean">
  若为 `true`，响应将是一个 Server-Sent Events 流，由 `data: {chunk}\n\n` 形式的数据块组成，并以 `data: [DONE]` 结束。
</ParamField>

<ParamField body="stop" type="string | array">
  停止序列。
</ParamField>

<ParamField body="seed" type="integer">
  用于可复现输出的采样随机种子。
</ParamField>

<ParamField body="response_format" type="object">
  例如 `{ "type": "json_object" }`，用于支持 JSON 模式的模型。
</ParamField>

<ParamField body="presence_penalty" type="number">
  根据 token 是否已在文本中出现过对新 token 进行惩罚，取值 -2 到 2。
</ParamField>

<ParamField body="frequency_penalty" type="number">
  根据 token 在文本中出现的频率对新 token 进行惩罚，取值 -2 到 2。
</ParamField>

<ParamField body="tools" type="array">
  针对支持工具调用的模型的工具/函数定义。
</ParamField>

<ParamField body="prompt_cache_key" type="string">
  可选的 OpenAI 风格缓存分区键。共享同一个键的请求会路由到
  同一个提示缓存。VibeToken 会自动设置一个**按终端用户区分**的键
  （参见[提示缓存](#prompt-caching)）；仅在需要覆盖时才传入你自己的键——
  例如在某个工作区内跨用户共享缓存。
  Anthropic 和 Gemini 模型会忽略该字段，转而使用它们自己的缓存
  原语（VibeToken 也会自动处理这些）。
</ParamField>

## 示例

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://vibetoken.cn/v1/chat/completions \
    -H "Authorization: Bearer sk-rb-xxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "deepseek/deepseek-v4-pro",
      "messages": [{"role": "user", "content": "What is 2+2?"}]
    }'
  ```

  ```python Python theme={null}
  from openai import OpenAI

  client = OpenAI(
      api_key="sk-rb-xxxxxxxxxxxx",
      base_url="https://vibetoken.cn/v1",
  )

  resp = client.chat.completions.create(
      model="google/gemini-2.5-flash",
      messages=[{"role": "user", "content": "What is 2+2?"}],
  )
  print(resp.choices[0].message.content)
  ```

  ```javascript JavaScript theme={null}
  import OpenAI from "openai";

  const client = new OpenAI({
    apiKey: "sk-rb-xxxxxxxxxxxx",
    baseURL: "https://vibetoken.cn/v1",
  });

  const resp = await client.chat.completions.create({
    model: "google/gemini-2.5-flash",
    messages: [{ role: "user", content: "What is 2+2?" }],
  });
  console.log(resp.choices[0].message.content);
  ```
</CodeGroup>

## 响应

```json theme={null}
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1776245700,
  "model": "deepseek/deepseek-v4-pro",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "4" },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 9,
    "completion_tokens": 1,
    "total_tokens": 10
  }
}
```

命中缓存时，`usage` 会包含一个 `prompt_tokens_details` 对象：

```json theme={null}
"prompt_tokens_details": {
  "cached_tokens": 3968,
  "cache_read_input_tokens": 3968
}
```

* `cached_tokens` — OpenAI 标准的从缓存中提供的 token 计数
  （缓存*读取*），按该模型折扣后的缓存读取（Cache Read）费率计费。
* `cache_read_input_tokens` — 同一数值的 Anthropic 风格别名，
  为保持一致性而一并给出。
* `cache_creation_input_tokens` — 本次请求*写入*缓存的
  token 数（仅限 Anthropic；OpenAI/Gemini 无写入溢价）。

这三个字段在为零时都会被省略。相同的明细也会出现在
流式输出最后一个数据块的 `usage` 中。

## 提示缓存

对于上游支持提示缓存的模型，VibeToken 会自动缓存——
无需任何标志。命中缓存的输入 token 按该模型折扣后的
**缓存读取（Cache Read）**费率计费；对于 Anthropic 模型，缓存*写入*（创建缓存条目的
首次请求）按约 1.25× 的**缓存写入（Cache Write）**
溢价计费。这两种费率（若已定义）均显示在各模型的定价页面上。

### 按用户隔离

缓存是**按终端用户隔离**的：你的客户缓存的前缀
绝不会与其他客户共享，也无法被其读取——即便他们通过
同一个 VibeToken 账户发送完全相同的提示词。VibeToken 会派生出
一个稳定、不透明的按用户 token，并将其接入
上游所遵循的相应缓存原语：

* **OpenAI / GPT-5** — 标准的 `prompt_cache_key` 字段。仅当你想覆盖 VibeToken 的按用户
  分区时才传入你自己的 `prompt_cache_key`（例如在某个工作区内跨用户共享缓存）。
* **Anthropic / Claude** — 通过 `session-id` 头进行分区，并在系统块上
  设置一个 `cache_control: ephemeral` 断点（Claude 只有在显式断点
  存在时才缓存，并会忽略 `prompt_cache_key`）。
* **Google / Gemini** — Gemini 的隐式缓存没有按请求的键，
  因此 VibeToken 会在缓存前缀前面加上一个按用户的盐值注释。
  每个用户会得到不同的内容哈希 → 不同的缓存分区。

无需启用任何东西——它在每次对话请求中都自动生效。该机制
在 [design/18\_cache-architecture.md](https://github.com/VibeToken/VibeToken/blob/main/design/18_cache-architecture.md) 中有详细描述。

### 阈值与 TTL

上游缓存通常需要\*\*≥1024 个输入 token\*\* 才会生效。
各模型的例外情况：

* Anthropic Haiku 4.5、Opus 4.5 / 4.6 / 4.7 → ≥4096 个 token
* Anthropic Sonnet 4.6 → ≥2048 个 token
* Gemini 2.5 Pro → ≥4096 个 token

缓存前缀在其最后一次使用后存活约 5 分钟。缓存对
长且稳定的系统提示词和工具定义有益；请将静态
内容放在提示词开头，把可变内容放在末尾。

## 流式输出

设置 `"stream": true` 即可接收 SSE 数据块。每个数据块都是一个 `chat.completion.chunk` 对象，其 `delta` 中包含增量内容。数据流以 `data: [DONE]` 结束。

```python theme={null}
stream = client.chat.completions.create(
    model="google/gemini-2.5-flash",
    messages=[{"role": "user", "content": "Write a haiku"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")
```

## 视觉（多模态）

对于接受图像的模型，请使用 OpenAI 的内容片段结构：

```json theme={null}
{
  "model": "deepseek/deepseek-v4-pro",
  "messages": [{
    "role": "user",
    "content": [
      { "type": "text", "text": "What's in this image?" },
      { "type": "image_url", "image_url": { "url": "https://..." } }
    ]
  }]
}
```