# OpenAI Chat Completions

<HeroVideo src="https://studio.vibevibe.cn/docs/260915/docs-intro/video/chat.mp4" poster="https://studio.vibevibe.cn/docs/260915/docs-intro/poster/chat.webp" model="wan3.0-video-720p" />

`POST /v1/chat/completions`

覆盖面最广的入口——网关上几乎每个文本模型都能从这里调。开源项目、老框架、只认
「OpenAI 兼容」四个字的客户端，填这个准没错。

代价是它把所有模型压成同一套形状：Claude 的 thinking 块、Gemini 的 `imageConfig`、
Responses 的跨轮推理状态，走到这里都会被抹平。**模型有原生入口就优先用原生的**，
对照表见[模型与入口](https://docs.vibeapi.cn/zh/docs/models)。

## 基本调用

**建议用官方 SDK 而不是自己拼 HTTP**——SSE 解析、工具参数分片拼接、超时与重试都由它处理，能避开大部分常见问题。安装与环境变量配置见[快速开始](https://docs.vibeapi.cn/zh/docs/quickstart)。

<Tabs items={['curl', 'Python', 'Node.js']}>
  <Tab value="curl">
    ```bash
    curl -N -X POST "https://www.vibeapi.cn/v1/chat/completions" \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "gpt-6-astra",
        "messages": [
          {"role": "system", "content": "你是一个简洁的助手。"},
          {"role": "user", "content": "用一句话解释什么是幂等。"}
        ],
        "stream": true
      }'
    ```
  </Tab>

  <Tab value="Python">
    ```python
    from openai import OpenAI

    client = OpenAI(base_url="https://www.vibeapi.cn/v1", api_key="YOUR_API_KEY")

    stream = client.chat.completions.create(
        model="gpt-6-astra",
        messages=[
            {"role": "system", "content": "你是一个简洁的助手。"},
            {"role": "user", "content": "用一句话解释什么是幂等。"},
        ],
        stream=True,
    )

    for chunk in stream:
        delta = chunk.choices[0].delta.content
        if delta:
            print(delta, end="", flush=True)
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    import OpenAI from "openai";

    const client = new OpenAI({
      baseURL: "https://www.vibeapi.cn/v1",
      apiKey: "YOUR_API_KEY",
    });

    const stream = await client.chat.completions.create({
      model: "gpt-6-astra",
      messages: [
        { role: "system", content: "你是一个简洁的助手。" },
        { role: "user", content: "用一句话解释什么是幂等。" },
      ],
      stream: true,
    });

    for await (const chunk of stream) {
      const delta = chunk.choices[0]?.delta?.content;
      if (delta) process.stdout.write(delta);
    }
    ```
  </Tab>
</Tabs>

## 认证

`Authorization: Bearer <API_KEY>`，`base_url` 为 `https://www.vibeapi.cn/v1`。
OpenAI 官方 SDK 只需要换这一个值。

## 流式要求

请求超时上限 **120 秒**。非流式请求在生成完成前没有数据下行，单次生成超过这个时间就会
被中断，表现为「调用超时」。**这是本网关最常见的报错原因。**

短输出的非流式请求正常可用；长输出与推理型模型容易触发上限。**耗时无法预判，生产
环境建议默认开启流式**，需要完整文本时在客户端拼接 `delta`。

## 请求参数

参数名、类型与语义对齐 [OpenAI Chat Completions API](https://developers.openai.com/api/reference/resources/chat)。每个参数先给官方定义，再以「网关」标注本网关的实测行为。
GPT 系模型的请求体不经改写，整个参数面照单转发；标注含义：**支持**＝有可观测证据生效；**接受**＝正常受理、效果取决于模型本身；**实测不生效**＝返回 200 但没有对应效果；**无效**＝本网关不提供这项能力。

### 必填

<Fields>
  <Field name="model" type="string" required>
    用于生成响应的模型 ID。可用模型见[模型与入口](https://docs.vibeapi.cn/zh/docs/models)，或调 `GET /v1/models` 取当前 key 能用的那份。
  </Field>

  <Field name="messages" type="array" required>
    到目前为止的对话消息列表。每项含 `role`（`developer` / `system` / `user` / `assistant` / `tool`）与 `content`；
    支持的模态取决于模型，多模态模型的 `content` 可为数组，混排 `{"type": "text"}` 与 `{"type": "image_url"}`。
  </Field>
</Fields>

### 输出控制

<Fields>
  <Field name="stream" type="boolean" default="false">
    为 `true` 时以 server-sent events 边生成边返回。

    **网关。** 单次请求上限 120 秒，推理模型建议设为 `true`，见[流式要求](#流式要求)。
  </Field>

  <Field name="stream_options" type="object">
    流式选项，仅在 `stream: true` 时设置。`{"include_usage": true}` 让最后一个 chunk 带上 `usage`，否则流式模式下拿不到 token 统计。
  </Field>

  <Field name="max_completion_tokens" type="integer">
    本次补全可生成的 token 上限，**包含可见输出与不可见的推理 token**。推理模型请用它而不是 `max_tokens`。

    **网关。** 设得很小时 `finish_reason` 仍可能是 `stop` 而不是 `length`，不要用 `finish_reason` 判断是否被截断，以实际内容为准。
  </Field>

  <Field name="max_tokens" type="integer">
    可生成的 token 上限。官方已弃用，由 `max_completion_tokens` 取代，且与推理模型不兼容；保留仅为兼容旧客户端。
  </Field>

  <Field name="n" type="integer" default="1">
    为每条输入生成多少个候选回复；按所有候选的总 token 计费。

    **网关 · 实测不生效。** 需要多个结果请并发多次调用。
  </Field>

  <Field name="stop" type="string | array">
    最多 4 个停止序列，命中即停止生成，返回文本不含该序列。最新的推理模型不支持。**接受。**
  </Field>

  <Field name="response_format" type="object">
    指定模型必须输出的格式。`{"type": "json_schema", "json_schema": {...}}` 启用结构化输出，保证输出符合你给的 JSON Schema；`{"type": "json_object"}` 只保证是合法 JSON，需在提示里要求模型输出 JSON。

    **网关 · 支持。** 两种写法都实测可用。
  </Field>

  <Field name="verbosity" type="string" default="medium">
    约束回复的详略：`low` / `medium` / `high`。较新的模型才支持。**接受。**
  </Field>

  <Field name="prediction" type="object">
    预测输出（Predicted Outputs）：把已知的大部分内容作为静态预测传入，命中时降低延迟。**接受。**
  </Field>
</Fields>

### 采样

<Fields>
  <Field name="temperature" type="number" default="1">
    采样温度，`0`–`2`。越高越随机，越低越集中；一般只调它或 `top_p` 之一。

    **网关。** 部分推理模型忽略它或只接受默认值，取决于模型。
  </Field>

  <Field name="top_p" type="number" default="1">
    核采样，替代温度：只考虑累计概率达到 `top_p` 的那部分 token，`0.1` 即只看前 10% 概率质量。
  </Field>

  <Field name="frequency_penalty" type="number" default="0">
    `-2.0`–`2.0`。正值按 token 已出现的频次惩罚，降低逐字重复的概率。**接受。**
  </Field>

  <Field name="presence_penalty" type="number" default="0">
    `-2.0`–`2.0`。正值按 token 是否已出现惩罚，提高谈论新话题的概率。**接受。**
  </Field>

  <Field name="logit_bias" type="object">
    按 token ID 调整其出现概率，取值 `-100`–`100`，在采样前加到 logits 上。**接受**，效果取决于模型。
  </Field>

  <Field name="logprobs" type="boolean">
    是否返回输出 token 的对数概率。

    **网关 · 实测不生效。** 返回 200 但响应里没有 `logprobs` 字段。
  </Field>

  <Field name="top_logprobs" type="integer">
    每个位置返回最可能的 `0`–`20` 个 token 及其对数概率，需同时开 `logprobs`。

    **网关 · 实测不生效。** 同 `logprobs`。
  </Field>

  <Field name="seed" type="integer">
    指定后系统尽力确定性采样，相同 `seed` 与参数的重复请求应返回相同结果；不保证确定性，可用响应里的 `system_fingerprint` 监控后端变化。

    **网关 · 支持。** 同一种子连续两次请求输出完全一致；模型版本变化后不保证跨时间一致。
  </Field>

  <Field name="reasoning_effort" type="string">
    约束推理模型的推理投入：`none` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`。降低投入可加快响应、减少推理 token；不是每个推理模型都支持全部取值，默认值随模型而异。
  </Field>
</Fields>

### 工具调用

<Fields>
  <Field name="tools" type="array">
    模型可以调用的工具列表，可以是函数工具或自定义工具。

    **网关。** GPT 系工具调用语义完整；从本端点调 Claude / Gemini 属于协议转换，只保证基本的函数调用。
  </Field>

  <Field name="tool_choice" type="string | object">
    控制模型是否调用工具：`none` 不调用只生成消息；`auto` 由模型决定；`required` 必须调用至少一个；`{"type": "function", "function": {"name": "..."}}` 指定某个函数。
  </Field>

  <Field name="parallel_tool_calls" type="boolean" default="true">
    是否允许一轮内并行调用多个工具。**接受。**
  </Field>

  <Field name="functions" type="array">
    已弃用，由 `tools` 取代。仅为兼容旧客户端保留。
  </Field>

  <Field name="function_call" type="string | object">
    已弃用，由 `tool_choice` 取代。
  </Field>

  <Field name="web_search_options" type="object">
    内置联网搜索工具的选项：`search_context_size`（`low` / `medium` / `high`）与 `user_location`。

    **网关。** 取决于该模型当前是否开放该能力，不保证可用。
  </Field>
</Fields>

### 缓存、标识与其他

<Fields>
  <Field name="prompt_cache_key" type="string">
    用于把相似请求路由到同一缓存，提高提示缓存命中率；取代 `user` 字段的缓存用途。

    **网关 · 支持。** 相同前缀的第二次请求 `usage` 里能读到命中的缓存 token，`auto` 与官方满血两类 key 都可用。相同前缀带同一个 key 更容易命中，直接影响成本。
  </Field>

  <Field name="prompt_cache_options" type="object">
    提示缓存选项，`gpt-5.6` 及以后支持：`mode: "explicit"` 关闭隐式缓存断点，`ttl` 目前只支持 `30m`。**接受。**
  </Field>

  <Field name="prompt_cache_retention" type="string">
    已弃用，改用 `prompt_cache_options.ttl`。设为 `24h` 延长缓存保留。**接受。**
  </Field>

  <Field name="store" type="boolean" default="false">
    是否在服务端保存本次对话，供蒸馏与评测产品使用。**接受。**
  </Field>

  <Field name="metadata" type="object">
    最多 16 对键值，键 ≤ 64 字符、值 ≤ 512 字符，随对象存储、可供查询。**接受。**
  </Field>

  <Field name="user" type="string">
    终端用户的稳定标识，正被 `safety_identifier` 与 `prompt_cache_key` 取代。**接受。**
  </Field>

  <Field name="safety_identifier" type="string">
    帮助识别可能违反使用政策的终端用户的稳定标识，≤ 64 字符，建议用用户名或邮箱的哈希。**接受。**
  </Field>

  <Field name="service_tier" type="string">
    处理类型：`auto` / `default` / `flex` / `priority` 等。

    **网关。** 由网关自行路由，该字段无意义。
  </Field>

  <Field name="moderation" type="object">
    对输入与输出运行内容审核的配置（`model`、`policy`）。**接受。**
  </Field>

  <Field name="modalities" type="array" default="[&#x22;text&#x22;]">
    期望的输出类型，如 `["text"]` 或 `["text", "audio"]`。**接受。**
  </Field>

  <Field name="audio" type="object">
    音频输出参数，`modalities` 含 `audio` 时必填。

    **网关 · 无效。** 不提供音频输出模型。
  </Field>
</Fields>

## 响应字段

非流式返回一个 `chat.completion` 对象：

```json
{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "created": 1788960000,
  "model": "gpt-6-astra",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "同一个操作执行多次和执行一次效果相同。", "tool_calls": null },
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "usage": {
    "prompt_tokens": 32,
    "completion_tokens": 18,
    "total_tokens": 50,
    "completion_tokens_details": { "reasoning_tokens": 0 }
  }
}
```

<Fields>
  <Field name="id" type="string">
    本次补全的 id。
  </Field>

  <Field name="choices[].message.content" type="string">
    正文。工具调用时可能为 `null`，内容在 `tool_calls` 里。
  </Field>

  <Field name="choices[].message.tool_calls" type="array">
    模型请求调用的工具及其参数（参数是 JSON 字符串，需自行解析）。
  </Field>

  <Field name="choices[].finish_reason" type="string">
    `stop` 正常结束 · `length` 撞到输出上限 · `tool_calls` 等待工具结果 ·
    `content_filter` 被审核拦截。
  </Field>

  <Field name="usage.completion_tokens_details.reasoning_tokens" type="integer">
    不可见的推理 token 数。**它计费但不出现在正文里**，推理模型上对账要看这个。
  </Field>
</Fields>

## 流式事件

SSE，每个事件是一个 `chat.completion.chunk`，增量在 `choices[0].delta`，
以 `data: [DONE]` 收尾：

```
data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant"}}]}

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"同一个"}}]}

data: {"object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}

data: [DONE]
```

只有一种 chunk 类型，按 `delta` 里出现的字段分辨内容：`content` 是正文增量，
`tool_calls` 是工具调用参数的增量片段（要按 `index` 累积拼接）。
带了 `stream_options.include_usage` 时，最后一个 chunk 会额外带 `usage`。

## 参数改写规则

| 模型       | 触发条件                            | 网关的动作                                                                           |
| -------- | ------------------------------- | ------------------------------------------------------------------------------- |
| `grok-*` | `tools` 里含 `web_search` 类型的内置工具 | 移除该工具，其余工具保留（xAI 的 Chat 接口不支持内置搜索，带上会 422；联网请用 [Responses](https://docs.vibeapi.cn/zh/docs/grok#联网搜索)） |
| `grok-*` | `reasoning.effort` 为 `none`     | 改写为 `low`                                                                       |

Claude 系模型也有一组改写规则（`thinking`、`temperature`、`top_p`），见
[Messages](https://docs.vibeapi.cn/zh/docs/messages) 页——从本页调用 Claude 时同样适用。

## 分组差异

key 分两类：**`auto`**（可调用除 `claude-opus-5-5`、`claude-fable-5`、`claude-fable-5-1` 外的全部模型）和 **`Claude 官方满血版`**。
**对 GPT 系模型，两类 key 实测没有差异**——提示缓存与内置工具在两边都可用。
差异只出现在 Claude 系模型上，见 [Messages](https://docs.vibeapi.cn/zh/docs/messages) 页。

## 国产模型兼容度

网关上的国产模型（glm / kimi / qwen / deepseek / MiniMax）两套协议都能调通，
工具调用也都可用，但对 `max_tokens`、停止序列、结构化输出的遵循程度**逐个模型不同**，
同一模型在 Chat 协议和另一套协议上还可能表现不同。逐项实测结果见
[模型与入口](https://docs.vibeapi.cn/zh/docs/models)。

其中 `deepseek-v4-pro` 与 `kimi-k3` 不执行 `max_tokens`，且仍将结束原因报为已截断。
使用这两个模型时，以 `usage` 中的实际 token 数对账。

## 真实响应示例

下面是从生产网关真实抓取、脱敏后的请求与响应，可以直接对照你自己的返回体。

<Example id="chat-basic" />

模型决定调用工具时，`content` 为 `null`，内容在 `tool_calls` 里：

<Example id="chat-tool" />

流式的 SSE 增量（中间事件已省略）：

<Example id="chat-stream" />

### 国产模型的真实响应

以下为各国产模型在 Chat 协议上的真实调用与响应，逐条折叠。

<Examples group="cn-chat" open="cn-chat-glm" />

## 能力边界

* **不等价于原生协议。** Claude 模型从这里调 thinking 块会丢，Gemini 的生图参数会丢。
  调用成功不代表功能完整。
* **`n` 不保证生效。** 需要多个结果请并发多次调用。
* **不提供音频模型**，`audio` / `modalities: ["audio"]` 无效。
* **不是所有官方端点都有。** `/v1/assistants`、`/v1/batches`、`/v1/fine_tuning` 不在提供范围内。

## 在线调试

填入你自己的 API Key 即可直接发起请求，参数表与响应结构由接口定义生成。

<APIPage document={"openapi/generated/ai-model/聊天（Chat）/原生OpenAI格式/post-v1-chat-completions-createchatcompletion-383826473.json"} operations={[{"path":"/v1/chat/completions","method":"post"}]} />

## 官方文档

本页只写与本网关有关的部分，参数语义的权威定义以官方为准：

* [OpenAI · Chat Completions](https://developers.openai.com/api/reference/chat-completions/overview)
* [OpenAI · 文本生成指南](https://developers.openai.com/api/docs/guides/text)


# Gemini 图像生成

`POST /v1beta/models/{model}:generateContent`

Gemini 系图像模型走 Gemini 原生协议。**生图请务必用这个端点**——走 Chat 兼容协议也能出图，
但 `imageConfig`（`aspectRatio` 画幅、`imageSize` 分辨率）会在协议转换中整个丢掉，只能拿到默认尺寸。
文本对话见 [Gemini generateContent](https://docs.vibeapi.cn/zh/docs/gemini)；GPT 生图见 [GPT 图像 · Image API](https://docs.vibeapi.cn/zh/docs/images) 与 [GPT 图像 · Responses](https://docs.vibeapi.cn/zh/docs/images-responses)，Grok 见 [Grok 图像](https://docs.vibeapi.cn/zh/docs/grok-images)。

## 基本调用

**建议用官方 SDK**（Python `google-genai`、Node.js `@google/genai`），`base_url` 填不带 `/v1` 的根地址。

<Tabs items={['curl', 'Python', 'Node.js']}>
  <Tab value="curl">
    ```bash
    curl -s -X POST \
      "https://www.vibeapi.cn/v1beta/models/gemini-3.1-flash-image:generateContent" \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "contents": [{"parts": [{"text": "一只可爱的猫咪在阳光下打盹"}]}],
        "generationConfig": {
          "responseModalities": ["IMAGE"],
          "imageConfig": {"aspectRatio": "16:9", "imageSize": "1K"}
        }
      }' -o response.json

    # 提取图片
    jq -r '.candidates[0].content.parts[0].inlineData.data' response.json | base64 -d > output.png
    ```
  </Tab>

  <Tab value="Python">
    ```python
    from google import genai
    from google.genai import types

    client = genai.Client(
        api_key="YOUR_API_KEY",
        http_options=types.HttpOptions(base_url="https://www.vibeapi.cn"),
    )

    response = client.models.generate_content(
        model="gemini-3.1-flash-image",
        contents="一只可爱的猫咪在阳光下打盹",
        config=types.GenerateContentConfig(
            response_modalities=["IMAGE"],
            image_config=types.ImageConfig(aspect_ratio="16:9", image_size="1K"),
        ),
    )

    for part in response.parts:
        if part.inline_data is not None:
            part.as_image().save("cat.png")
            break
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    import { GoogleGenAI } from "@google/genai";
    import fs from "fs";

    const ai = new GoogleGenAI({
      apiKey: "YOUR_API_KEY",
      httpOptions: { baseUrl: "https://www.vibeapi.cn" },
    });

    const response = await ai.models.generateContent({
      model: "gemini-3.1-flash-image",
      contents: "一只可爱的猫咪在阳光下打盹",
      config: {
        responseModalities: ["IMAGE"],
        imageConfig: { aspectRatio: "16:9", imageSize: "1K" },
      },
    });

    for (const part of response.candidates[0].content.parts) {
      if (part.inlineData) {
        fs.writeFileSync("cat.png", Buffer.from(part.inlineData.data, "base64"));
        break;
      }
    }
    ```
  </Tab>
</Tabs>

以下内容均来自对本网关的真实调用，最后验证：2026-08-10。

## 可用模型

超时建议：512px / 1K 约 80 秒，2K 约 200 秒，4K 约 350 秒。

| 模型                           | 适用场景      | 特点                             |
| ---------------------------- | --------- | ------------------------------ |
| `gemini-3-pro-image-preview` | 专业素材、复杂指令 | 高级推理、搜索接地、最高 4K、最多 14 张参考图     |
| `gemini-3.1-flash-image`     | 日常生成、批量任务 | 性价比高、支持 512px-4K、思考等级控制、图片搜索接地 |

## 请求格式

```json
{
  "contents": [
    {
      "parts": [
        { "text": "你的提示词" }
      ]
    }
  ],
  "generationConfig": {
    "responseModalities": ["IMAGE"],
    "imageConfig": {
      "aspectRatio": "16:9",
      "imageSize": "1K"
    }
  }
}
```

### generationConfig 参数

| 参数                        | 类型         | 说明                                               |
| ------------------------- | ---------- | ------------------------------------------------ |
| `responseModalities`      | `string[]` | `["IMAGE"]` 仅图片；`["TEXT", "IMAGE"]` 图文混合（默认）     |
| `imageConfig.aspectRatio` | `string`   | 宽高比，见下方支持列表                                      |
| `imageConfig.imageSize`   | `string`   | 分辨率档位：`512px`（仅 flash）、`1K`、`2K`、`4K`。**必须大写 K** |

### 支持的宽高比

全部 14 种，两个模型均已验证通过：

`1:1` `1:4` `1:8` `2:3` `3:2` `3:4` `4:1` `4:3` `4:5` `5:4` `8:1` `9:16` `16:9` `21:9`

## 响应格式

```json
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "inlineData": {
              "mimeType": "image/png",
              "data": "<BASE64_IMAGE_DATA>"
            }
          }
        ]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 10,
    "candidatesTokenCount": 1120,
    "totalTokenCount": 1130
  }
}
```

图片在 `candidates[0].content.parts[].inlineData` 中，base64 编码。

当 `responseModalities` 包含 `"TEXT"` 时，parts 中可能同时包含 `text` 和 `inlineData`。

## 分辨率参考表

### gemini-3.1-flash-image

| 宽高比  | 512px    | 1K        | 2K        | 4K         |
| ---- | -------- | --------- | --------- | ---------- |
| 1:1  | 512×512  | 1024×1024 | 2048×2048 | 4096×4096  |
| 1:4  | 256×1024 | 512×2064  | 1024×4128 | 2048×8256  |
| 1:8  | 176×1456 | 352×2928  | 704×5856  | 1408×11712 |
| 2:3  | 416×624  | 848×1264  | 1696×2528 | 3392×5056  |
| 3:2  | 624×416  | 1264×848  | 2528×1696 | 5056×3392  |
| 3:4  | 448×592  | 896×1200  | 1792×2400 | 3584×4800  |
| 4:1  | 1024×256 | 2064×512  | 4128×1024 | 8256×2048  |
| 4:3  | 592×448  | 1200×896  | 2400×1792 | 4800×3584  |
| 4:5  | 464×576  | 928×1152  | 1856×2304 | 3712×4608  |
| 5:4  | 576×464  | 1152×928  | 2304×1856 | 4608×3712  |
| 8:1  | 1456×176 | 2928×352  | 5856×704  | 11712×1408 |
| 9:16 | 384×688  | 768×1376  | 1536×2752 | 3072×5504  |
| 16:9 | 688×384  | 1376×768  | 2752×1536 | 5504×3072  |
| 21:9 | 784×336  | 1584×672  | 3168×1344 | 6336×2688  |

> 512px 档位仅 flash 模型支持。

### gemini-3-pro-image-preview

支持 `1K`、`2K`、`4K`，不支持 `512px`。分辨率与 flash 的 1K/2K/4K 一致。

### 耗时参考

| 档位    | 典型耗时     |
| ----- | -------- |
| 512px | 10-17s   |
| 1K    | 13-40s   |
| 2K    | 40-170s  |
| 4K    | 120-310s |

## 图片编辑

原图与文字指令一起放进 `contents`，即为编辑；SDK 直接传 PIL Image，REST 用 `inline_data` 传 base64。
只改局部时，在指令里明确说清保留什么：

```python
from PIL import Image

response = client.models.generate_content(
    model="gemini-3.1-flash-image",
    contents=[Image.open("cat.png"), "给这只猫戴上一顶圣诞帽"],
    config=types.GenerateContentConfig(
        response_modalities=["IMAGE"],
        image_config=types.ImageConfig(aspect_ratio="1:1", image_size="1K"),
    ),
)
for part in response.parts:
    if part.inline_data is not None:
        part.as_image().save("cat_hat.png")
        break
```

同一写法覆盖三类常见任务，只换指令：

| 任务         | 指令示例                                                                                                                                            |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| 局部重绘（语义遮盖） | `Change only the background to a snowy winter scene. Keep the cat exactly the same.`                                                            |
| 风格迁移       | `Transform this photograph into the style of Van Gogh's Starry Night. Preserve the composition but render with swirling, impasto brushstrokes.` |
| 多图合成       | `contents` 里放多张图 + 指令：`让第二张图中的人穿上第一张图中的蓝色连衣裙，生成一张专业电商照片`                                                                                        |

REST 写法（多图合成）：

```bash
curl -s -X POST \
  "https://www.vibeapi.cn/v1beta/models/gemini-3.1-flash-image:generateContent" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contents": [{"parts": [
      {"text": "让第二张图中的人穿上第一张图中的蓝色连衣裙，生成一张专业电商照片"},
      {"inline_data": {"mime_type": "image/png", "data": "<DRESS_BASE64>"}},
      {"inline_data": {"mime_type": "image/png", "data": "<MODEL_BASE64>"}}
    ]}],
    "generationConfig": {
      "responseModalities": ["IMAGE"],
      "imageConfig": {"aspectRatio": "3:4", "imageSize": "2K"}
    }
  }'
```

## 多轮迭代

把上一轮模型返回的完整 `parts`（含 `inlineData` 与 `thoughtSignature`）以 `role: "model"` 原样放回 `contents`，再追加新指令：

```python
history = [{"role": "user", "parts": [{"text": "画一只橘猫坐在窗台上"}]}]
r1 = client.models.generate_content(model="gemini-3.1-flash-image", contents=history,
        config=types.GenerateContentConfig(response_modalities=["TEXT", "IMAGE"]))

history.append(r1.candidates[0].content)                       # 模型回复原样入史
history.append({"role": "user", "parts": [{"text": "把背景改成下雨天"}]})
r2 = client.models.generate_content(model="gemini-3.1-flash-image", contents=history,
        config=types.GenerateContentConfig(response_modalities=["TEXT", "IMAGE"]))
```

## 高级功能

### Google 搜索接地

基于实时搜索数据生成图片（如天气、新闻、股票）。在请求中添加 `tools` 字段：

```json
{
  "contents": [{"parts": [{"text": "可视化旧金山今天的天气预报"}]}],
  "tools": [{"google_search": {}}],
  "generationConfig": {
    "responseModalities": ["TEXT", "IMAGE"],
    "imageConfig": {"aspectRatio": "16:9"}
  }
}
```

响应中会额外返回 `groundingMetadata`，包含 `webSearchQueries`（搜索词）和 `groundingChunks`（来源链接）。

Flash 还额外支持图片搜索接地，可用网络图片作为视觉参考：

```json
"tools": [{"google_search": {"search_types": {"web_search": {}, "image_search": {}}}}]
```

### 思考模式

Pro 模型默认启用思考模式，会先生成构思草图再输出最终图片。响应中 `part.thought == true` 的为思考过程，可跳过。

Flash 模型支持控制思考等级（`minimal` 默认 或 `high`），通过 `generationConfig.thinkingConfig` 设置：

```json
{
  "contents": [{"parts": [{"text": "A futuristic city inside a glass bottle floating in space"}]}],
  "generationConfig": {
    "responseModalities": ["IMAGE"],
    "imageConfig": {"aspectRatio": "1:1", "imageSize": "1K"},
    "thinkingConfig": {
      "thinkingLevel": "high",
      "includeThoughts": true
    }
  }
}
```

`high` 模式下响应 parts 会包含多种类型：

| part 类型                          | 说明         |
| -------------------------------- | ---------- |
| `thought == true` + `text`       | 思考文本（推理过程） |
| `thought == true` + `inlineData` | 构思草图（临时图片） |
| `inlineData`（无 thought）          | 最终输出图片     |

提取最终图片时跳过 thought parts：

```python
for part in response.candidates[0].content.parts:
    if getattr(part, "thought", False):
        continue  # 跳过思考过程
    if part.get("inlineData"):
        # 这是最终图片
        save(part["inlineData"])
```

> 无论 `includeThoughts` 设为 true 还是 false，思考 token 都会计费。`high` 模式会消耗更多 token 但图片质量更高。

### 多张参考图片

Pro 支持最多 6 张对象图 + 5 张人物图（共 14 张）；Flash 支持最多 10 张对象图 + 4 张人物图。

## 能力边界

1. **imageSize 大小写**：必须用大写 `K`（`1K`、`2K`、`4K`），小写 `1k` 会被拒绝
2. **512px 仅 flash**：Pro 模型不支持 512px 档位
3. **超时**：4K 分辨率生成可能需要 2-5 分钟，务必设置足够的超时
4. **Token 消耗**：512px 约 747 token，1K 约 1120 token，4K 约 2000 token
5. **默认行为**：不传 `imageConfig` 时，默认输出约 1408×768（接近 16:9 的 1K）
6. **图片格式**：响应中 `mimeType` 通常为 `image/png`，偶尔为 `image/jpeg`
7. **SynthID 水印**：所有生成图片均包含 SynthID 数字水印
8. **推荐语言**：英语、中文、日语、韩语、法语、德语、西班牙语等

## 在线调试

填入你自己的 API Key 即可直接发起请求，参数表与响应结构由接口定义生成。

<APIPage document={"openapi/generated/ai-model/图像（Images）/原生Gemini格式/post-v1beta-models-model-generatecontent-geminirelayv1beta-383837589-383837589.json"} operations={[{"path":"/v1beta/models/{model}:generateContent/","method":"post"}]} />

## 官方文档

* [Gemini API · 图像生成](https://ai.google.dev/gemini-api/docs/image-generation)
* [Gemini API · generateContent](https://ai.google.dev/api/generate-content)


# Gemini generateContent

<HeroVideo src="https://studio.vibevibe.cn/docs/260915/docs-intro/video/gemini.mp4" poster="https://studio.vibevibe.cn/docs/260915/docs-intro/poster/gemini.webp" model="MiniMax-H3" />

`POST /v1beta/models/{model}:generateContent`
· 流式 `POST /v1beta/models/{model}:streamGenerateContent`

Gemini 系模型的原生协议。**Gemini 模型请优先用这个端点**——它是唯一能拿到
`thinkingConfig`（思考）与 `imageConfig`（生图的比例与分辨率）的路径。从
[Chat Completions](https://docs.vibeapi.cn/zh/docs/chat) 调 Gemini 也能通，但那是网关做的协议转换，这两组参数
都会在转换中丢失。

注意模型名出现在**路径里**，不在请求体里。

## 基本调用

**建议用官方 SDK**（Python `google-genai`、Node.js `@google/genai`），SSE 解析与重试由它处理。

<Tabs items={['curl', 'Python', 'Node.js']}>
  <Tab value="curl">
    ```bash
    curl -N -X POST "https://www.vibeapi.cn/v1beta/models/gemini-3.8-flash:streamGenerateContent" \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "contents": [{"role": "user", "parts": [{"text": "用一句话解释什么是幂等。"}]}],
        "generationConfig": {"maxOutputTokens": 512}
      }'
    ```
  </Tab>

  <Tab value="Python">
    ```python
    from google import genai
    from google.genai import types

    client = genai.Client(
        api_key="YOUR_API_KEY",
        http_options=types.HttpOptions(base_url="https://www.vibeapi.cn"),
    )

    for chunk in client.models.generate_content_stream(
        model="gemini-3.8-flash",
        contents="用一句话解释什么是幂等。",
        config=types.GenerateContentConfig(max_output_tokens=512),
    ):
        if chunk.text:
            print(chunk.text, end="", flush=True)
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    import { GoogleGenAI } from "@google/genai";

    const ai = new GoogleGenAI({
      apiKey: "YOUR_API_KEY",
      httpOptions: { baseUrl: "https://www.vibeapi.cn" },
    });

    const stream = await ai.models.generateContentStream({
      model: "gemini-3.8-flash",
      contents: "用一句话解释什么是幂等。",
      config: { maxOutputTokens: 512 },
    });

    for await (const chunk of stream) {
      if (chunk.text) process.stdout.write(chunk.text);
    }
    ```
  </Tab>
</Tabs>

## 认证

`Authorization: Bearer <API_KEY>`，base 是 `https://www.vibeapi.cn`（**不带 `/v1`**，
Gemini 的路径前缀是 `/v1beta`）。

## 流式要求

请求超时上限 **120 秒**。`:generateContent` 在生成完成前没有数据下行，单次生成超过这个
时间会被中断。短输出不受影响；开启 thinking 的型号要等整段思考结束才返回，容易触发
上限。**建议默认用 `:streamGenerateContent`**，将各 chunk 的
`candidates[0].content.parts[].text` 拼接成完整文本。

## 与另外两套协议的差异

Gemini 的请求结构与 OpenAI / Anthropic 均不同，以下三处差异最大：

**模型名在 URL 路径里**，请求体里没有 `model` 字段。换模型要换 URL。

**对话叫 `contents` 不叫 `messages`**，角色是 `user` 和 **`model`**（不是 `assistant`），
每条消息的内容是 `parts` 数组（文本、图片、函数调用各是一个 part）。

**采样参数包在 `generationConfig` 里**，不是顶层字段；而 `tools`、`safetySettings`、
`systemInstruction` 是顶层的。

|       | Chat Completions        | Messages         | generateContent                    |
| ----- | ----------------------- | ---------------- | ---------------------------------- |
| 模型名   | 请求体 `model`             | 请求体 `model`      | **URL 路径**                         |
| 对话    | `messages`              | `messages`       | `contents`                         |
| 助手角色名 | `assistant`             | `assistant`      | **`model`**                        |
| 系统提示  | `system` 角色             | 顶层 `system`      | 顶层 `systemInstruction`             |
| 输出上限  | `max_completion_tokens` | `max_tokens`（必填） | `generationConfig.maxOutputTokens` |
| 流式    | `stream: true`          | `stream: true`   | **换端点** `:streamGenerateContent`   |

## 请求体顶层字段

<Fields>
  <Field name="contents" type="array" required>
    对话数组。每项含 `role`（`user` / `model`）与 `parts` 数组。`parts` 里可以混排
    `{"text": ...}`、`{"inlineData": {"mimeType", "data"}}`（内联 base64 图片）、
    `{"functionCall": ...}`、`{"functionResponse": ...}`。
  </Field>

  <Field name="systemInstruction" type="object">
    系统指引，形状与一条 `contents` 相同（含 `parts`）。
  </Field>

  <Field name="tools" type="array">
    工具定义。既包括你自己的 `functionDeclarations`，也包括内置工具（如
    `googleSearch`、`codeExecution`）。**内置工具不保证可用**，也不保证与官方一致。
  </Field>

  <Field name="toolConfig" type="object">
    工具调用模式，`functionCallingConfig.mode` 取 `AUTO` / `ANY` / `NONE` / `VALIDATED`。
  </Field>

  <Field name="safetySettings" type="array">
    按类别设置安全阈值。**接受**，实际拦截强度取决于模型。
  </Field>

  <Field name="cachedContent" type="string">
    引用服务端缓存的内容。**依赖服务端存储，本网关不保证可用。**
  </Field>

  <Field name="labels" type="object">
    自定义标签。**接受**。
  </Field>
</Fields>

## generationConfig

<Fields>
  <Field name="maxOutputTokens" type="integer">
    输出上限。**思考 token 也算在内**，带 thinking 的型号要留足空间。
  </Field>

  <Field name="temperature" type="number">
    随机度。
  </Field>

  <Field name="topP" type="number">
    核采样阈值。
  </Field>

  <Field name="topK" type="integer">
    只从概率最高的 K 个 token 里采样。
  </Field>

  <Field name="candidateCount" type="integer">
    生成几个候选。**实测只能为 1**——传 2 会被 400 拒绝，提示当前模型只允许一个候选。
    需要多个结果请并发多次调用。生图同样不支持这个参数。
  </Field>

  <Field name="stopSequences" type="array">
    停止序列。**支持**——实测命中后正常截断，`finishReason` 为 `STOP`。
  </Field>

  <Field name="seed" type="integer">
    采样种子。**实测不生效**——固定种子 + `temperature: 0` 连续三次请求输出仍不相同；
    不带种子的对照组同样不确定。需要可复现结果时，请改用 OpenAI 系模型
    （[Chat](https://docs.vibeapi.cn/zh/docs/chat) 页的 `seed` 实测可复现）。
  </Field>

  <Field name="presencePenalty" type="number">
    按是否出现过惩罚重复。**接受**。
  </Field>

  <Field name="frequencyPenalty" type="number">
    按出现频次惩罚重复。**接受**。
  </Field>

  <Field name="logprobs" type="integer">
    返回多少个候选 token 的概率。**实测不可用**，见下面的 `responseLogprobs`。
  </Field>

  <Field name="responseLogprobs" type="boolean">
    是否返回对数概率。**实测不可用**——本网关会以 400 拒绝，提示对数概率不支持流式模式。
  </Field>

  <Field name="responseMimeType" type="string">
    响应 MIME 类型，如 `application/json`。配合 `responseSchema` 做结构化输出。
  </Field>

  <Field name="responseSchema" type="object">
    用 Gemini 自己的 schema 方言约束输出结构，需配合
    `responseMimeType: "application/json"`。**支持**——实测返回符合 schema 的纯 JSON。

    注意 `maxOutputTokens` 要给足：部分型号（实测 `gemini-3-pro`）会在 JSON 前先输出一句
    前言，前言同样计入输出预算。预算不足时只会拿到那句前言，并以
    `finishReason: "MAX_TOKENS"` 结束——**看起来像 schema 没生效，实际是被截断了**。
    解析前检查 `finishReason` 比直接 `JSON.parse` 更可靠。
  </Field>

  <Field name="responseJsonSchema" type="object">
    用标准 JSON Schema 约束输出结构，与 `responseSchema` 二选一。
  </Field>

  <Field name="responseModalities" type="array">
    期望的输出模态，如 `["TEXT"]`、`["TEXT","IMAGE"]`。**生图模型必须带 `IMAGE`。**
  </Field>

  <Field name="thinkingConfig" type="object">
    思考配置。`thinkingLevel` 控制思考深度，`includeThoughts: true` 让思考内容随响应返回。
    **本网关实测可用**：返回的 `parts` 里带 `thought: true` 标记的就是思考内容，
    `usageMetadata.thoughtsTokenCount` 是思考消耗的 token。
  </Field>

  <Field name="imageConfig" type="object">
    生图配置，`aspectRatio` 比例、`imageSize` 分辨率（`1K` / `2K` / `4K` 等，**每个模型支持
    的档位不同**）。**这组参数只在原生端点有**，走 Chat 兼容协议会整个丢掉。
  </Field>

  <Field name="mediaResolution" type="string">
    输入媒体的处理分辨率，影响图片/视频输入的 token 消耗。**接受**。
  </Field>

  <Field name="speechConfig" type="object">
    语音合成配置。**本网关不提供语音模型**，无效。
  </Field>

  <Field name="audioTimestamp" type="boolean">
    音频输入的时间戳。**本网关不提供音频输入**，无效。
  </Field>

  <Field name="audioTranscriptionConfig" type="object">
    音频转写配置。同上，无效。
  </Field>

  <Field name="routingConfig" type="object">
    Google 侧的模型路由配置。**本网关自行路由，这个字段没有意义。**
  </Field>

  <Field name="modelSelectionConfig" type="object">
    模型选择配置。同上，没有意义。
  </Field>

  <Field name="enableEnhancedCivicAnswers" type="boolean">
    公民类问题的增强回答。**接受**。
  </Field>

  <Field name="modelArmorConfig" type="object">
    Model Armor 防护配置，属于 Vertex 侧能力。**接受**，多数情况无效。
  </Field>
</Fields>

SDK 里还有 `httpOptions`、`abortSignal`、`automaticFunctionCalling` 等字段，
它们是**客户端行为**，不会出现在 HTTP 请求体里。

## 响应字段

```json
{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [{ "text": "同一个操作执行多次和执行一次效果相同。" }]
      },
      "finishReason": "STOP"
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 12,
    "candidatesTokenCount": 18,
    "thoughtsTokenCount": 0,
    "totalTokenCount": 30
  }
}
```

<Fields>
  <Field name="candidates[].content.parts" type="array">
    产出的 part 数组，**类型是混排的**。带 `thought: true` 的是思考内容，带
    `inlineData` 的是生成的图片，带 `functionCall` 的是工具调用。
    **取正文要过滤掉 `thought` 的那些**，直接拼所有 `text` 会把思考内容混进正文。
  </Field>

  <Field name="candidates[].finishReason" type="string">
    `STOP` 正常结束 · `MAX_TOKENS` 撞到上限 · `SAFETY` 被安全策略拦截 ·
    `RECITATION` 疑似复述。
  </Field>

  <Field name="usageMetadata.thoughtsTokenCount" type="integer">
    思考消耗的 token。**计费但不出现在正文里**，对账要看这个。
  </Field>

  <Field name="promptFeedback" type="object">
    输入被安全策略拦截时的说明。此时 `candidates` 可能为空——**要处理这种情况**，
    否则会在取 `candidates[0]` 时崩掉。
  </Field>
</Fields>

## 流式

流式换端点，不是加参数：`:streamGenerateContent`。返回 SSE，每个 chunk 的形状与
非流式响应相同，只是 `parts` 里是增量文本，`usageMetadata` 在最后的 chunk 上。

## 真实响应示例

以下为真实调用与响应，逐条折叠。带 `thought: true` 的 part 是思考内容；
最后两条分别是结构化输出与不受支持参数的实际返回，可用于对照你自己的解析与错误处理。

<Example id="gemini-thought" />

<Examples group="gemini" open="gm-basic" />

## 能力边界

* **只保证文本与图像**。语音合成、音频输入、实时（Live）接口不在提供范围内，
  对应参数无效。
* **服务端缓存（`cachedContent`）不保证可用。**
* **内置工具不保证可用**，也不保证与官方一致。
* **走 Chat 兼容协议会丢掉 `thinkingConfig` 与 `imageConfig`**，生图务必用原生端点。

## 在线调试

填入你自己的 API Key 即可直接发起请求，参数表与响应结构由接口定义生成。

<APIPage document={"openapi/generated/ai-model/聊天（Chat）/原生Gemini格式/post-v1beta-models-model-generatecontent-geminirelayv1beta-383826489.json"} operations={[{"path":"/v1beta/models/{model}:generateContent","method":"post"}]} />

## 官方文档

本页只写与本网关有关的部分，参数语义的权威定义以官方为准：

* [Gemini API · 生成内容](https://ai.google.dev/gemini-api/docs/text-generation)
* [Gemini API · 思考](https://ai.google.dev/gemini-api/docs/thinking)
* [Gemini API · 图像生成](https://ai.google.dev/gemini-api/docs/image-generation)


# 在 Claude Code 里用 Grok（旧方法，已归档）









<Callout type="warn" title="这一页已归档，请改用新方法">
  现在不需要 CC Switch 和本地路由了。运行一条命令，Claude Code 的 `/model` 菜单里就会出现这把 key 能用的 Grok 模型，直接选就行：

  ```bash
  npx --registry=https://registry.npmmirror.com @vibeapi/cli@latest setup --key sk-xxx
  ```

  详见 [Claude Code（VibeCLI）](https://docs.vibeapi.cn/zh/docs/coding-tools/claude-code)。下面的旧方法只留给已经按它配好、暂时不想换的用户参考。
</Callout>

Claude Code 只认 Anthropic 协议，而 Grok 走的是 OpenAI 兼容协议，
两边对不上——所以要用 \*\*CC Switch 的「本地路由」\*\*在本机做一次协议转换。
配置一次即可，之后在 Claude Code 里就是直接用 `grok-4.6`。
下面四步照着截图填即可，标注的红框和序号就是要动的地方。

**「本地路由」是必开项，不是可选项。**
API 格式选了 `OpenAI Chat Completions` 的供应商，卡片上会挂一个
\*\*「需要路由」\*\*标记；只要路由没开，这个供应商就是不可用状态——
这是最常见的「配好了却用不了」的原因。

## 新增供应商

打开 CC Switch，顶部先切到 **Claude 那一栏**（① 处的图标），
再点右上角的 **＋**（②）新增一个供应商。

<img alt="CC Switch 主界面：切到 Claude 栏，点右上角加号新增供应商" src={__img0} placeholder="blur" />

① 顶部切到 Claude 图标那一栏　② 右上角 ＋ 新增供应商。配好后卡片长这样，注意名称旁边的「需要路由」标记

## 填写供应商信息

按下图逐项填，五个红框是关键：

| 字段        | 填什么                                                |
| --------- | -------------------------------------------------- |
| 供应商名称     | 自己认得就行，例如 `VibeAPI Grok`                           |
| 官网链接      | `https://www.vibeapi.cn`                           |
| ① API Key | 在 VibeAPI 用 **`auto` 或 `default` 令牌分组**生成的 key     |
| ② 请求地址    | `https://www.vibeapi.cn/v1`　**结尾不要带斜杠**            |
| ③ API 格式  | **OpenAI Chat Completions（需开启路由）**                 |
| 认证字段      | `ANTHROPIC_AUTH_TOKEN`（默认，不用改）                     |
| ④ 模型映射    | Sonnet / Opus / Fable / Haiku **四行全部填 `grok-4.6`** |
| ⑤ 默认兜底模型  | 同样填 `grok-4.6`                                     |

<img alt="CC Switch 编辑供应商表单：API Key、请求地址、API 格式、模型映射、默认兜底模型" src={__img1} placeholder="blur" />

编辑供应商页面。①API Key　②请求地址填到 `/v1`　③API 格式选「需开启路由」那项　④四个模型角色全填 grok-4.6　⑤默认兜底模型也填 grok-4.6，填完点右下角保存

**为什么四行都填 `grok-4.6`。**
Claude Code 会按 Sonnet / Opus / Haiku 这些角色分别发请求（后台小任务通常走 Haiku）。
映射不填满的话，这些请求会把原始 Claude 模型名透传给上游，
上游没有这个模型就直接报错。**默认兜底模型同理，别留空。**

## 打开本地路由

回到主界面，进 **设置 → 路由**，第一项就是**本地路由**，点开它。

<img alt="CC Switch 设置页的路由标签页，第一项是本地路由" src={__img2} placeholder="blur" />

设置 → 路由 → 本地路由（控制路由服务开关、查看状态与端口信息）

## 打开总开关和 Claude 开关

展开后有两个开关要打开：**路由总开关**，以及「路由启用」里的
**Claude**。状态显示**运行中**就算好了。

<img alt="本地路由展开后的开关：路由总开关与 Claude 路由开关均已打开" src={__img3} placeholder="blur" />

两个红箭头就是要打开的：右上「路由总开关」、下方「路由启用 · Claude」。服务地址默认 `http://127.0.0.1:15721`，改地址或端口后要重启路由服务才生效

**最后一步**：回主界面把这个供应商切成「使用中」，
**重开一个 Claude Code 会话**（旧会话读的还是旧配置），
`/model` 菜单里就能看到 `grok-4.6` 了。

还是不通，按顺序查三样：路由是不是「运行中」、请求地址是不是
`https://www.vibeapi.cn/v1`（无尾斜杠）、令牌分组是不是
`auto` / `default`。


# Grok 图像

`POST /v1/images/generations` · `POST /v1/images/edits`

模型 `grok-imagine-image-2.0`，按张计费；上一代 `grok-imagine-image-quality` 同端点、同价、仍在线（官方定于 2026-11-02 退役）。
图生图不换模型：把生图模型送到 `/v1/images/edits` 就是改图。最后验证：2026-09-12。

## 基本调用

<Tabs items={['curl', 'Python', 'Node.js']}>
  <Tab value="curl">
    ```bash
    curl https://www.vibeapi.cn/v1/images/generations \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "grok-imagine-image-2.0",
        "prompt": "a red apple on a wooden table, photo",
        "n": 1
      }'
    ```
  </Tab>

  <Tab value="Python">
    ```python
    from openai import OpenAI

    client = OpenAI(base_url="https://www.vibeapi.cn/v1", api_key="YOUR_API_KEY")

    result = client.images.generate(
        model="grok-imagine-image-2.0",
        prompt="a red apple on a wooden table, photo",
        n=1,
    )
    item = result.data[0]
    print(item.url or "b64_json")   # 临时链接，生成后立即下载落盘
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    import OpenAI from "openai";

    const client = new OpenAI({ baseURL: "https://www.vibeapi.cn/v1", apiKey: "YOUR_API_KEY" });

    const result = await client.images.generate({
      model: "grok-imagine-image-2.0",
      prompt: "a red apple on a wooden table, photo",
      n: 1,
    });
    const item = result.data[0];
    console.log(item.url ?? "b64_json");   // 临时链接，生成后立即下载落盘
    ```
  </Tab>
</Tabs>

响应：

```json
{
  "data": [{"url": "https://.../....jpeg", "mime_type": "image/jpeg"}],
  "usage": {"cost_in_usd_ticks": 600000000}
}
```

图片 URL 是临时地址，请在生成后立即下载落盘，不要直接交给终端用户或作为长期地址存储。

## 请求参数

| 参数                | 支持 | 取值 / 说明                                                                                                                                                        |
| ----------------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`          | ✅  | 必填                                                                                                                                                             |
| `n`               | ✅  | `1`–`10`，超出返回 400；按张计费                                                                                                                                         |
| `aspect_ratio`    | ⚠️ | 官方取值 `1:1`、`16:9` / `9:16`、`4:3` / `3:4`、`3:2` / `2:3`、`2:1` / `1:2`、`19.5:9` / `9:19.5`、`20:9` / `9:20`、`21:9`、`5:2`、`auto`。**2.0 在本网关不生效**，固定 1248×832；上一代生效 |
| `resolution`      | ⚠️ | 官方 `1k`（默认）/ `2k`。**2.0 在本网关不生效**                                                                                                                              |
| `quality`         | ⚠️ | 官方仅 2.0 支持，`low` / `medium` / `auto`（默认；生成按 `low`、编辑按 `medium` 服务，按实际档计费）。本网关传 `medium` 或 `high` 都返回 200，尺寸不变，是否影响计费未验证                                        |
| `response_format` | ✅  | `url`（默认）或 `b64_json`                                                                                                                                          |
| `seed`            | ✅  | 固定随机种子                                                                                                                                                         |
| `size`            | ⚠️ | 不报错但无效，改用 `aspect_ratio`                                                                                                                                       |

## 画幅

`grok-imagine-image-2.0` 在本网关上**只出 1248 × 832 一种尺寸**：`aspect_ratio` 七种取值、`resolution: 2k`、`quality` 逐一试过，
既不报错也不生效。这与 xAI 官方文档（2.0 支持全部画幅与 2K）不一致，属本网关当前表现。

| `aspect_ratio`         | `grok-imagine-image-2.0` | `grok-imagine-image-quality` |
| ---------------------- | ------------------------ | ---------------------------- |
| `1:1`                  | 1248 × 832               | 1024 × 1024                  |
| `16:9`                 | 1248 × 832               | 1280 × 720                   |
| `9:16`                 | 1248 × 832               | 864 × 1152                   |
| `4:3`                  | 1248 × 832               | 1152 × 864                   |
| `3:2`                  | 1248 × 832               | 1248 × 832                   |
| `2:3` / `3:4` / `21:9` | 1248 × 832               | —                            |

需要竖图、方图或任何非 3:2 画幅，用 `grok-imagine-image-quality`。它退役后由 2.0 以 `quality: low` 接管——如果届时 2.0 仍不认画幅，竖图就没有替代方案了。
上一代的尺寸口径也会变（`9:16` 曾返回 720 × 1280，现为 864 × 1152），**不要把尺寸写死在代码里**，以返回图片的实际宽高为准。

## 出图耗时

同一句提示词、同样单张：`grok-imagine-image-2.0` **36–64 秒**，`grok-imagine-image-quality` 约 **5 秒**。
批量出图、或接在用户交互链路上的场景，按这个差距估算超时与并发。

## 图生图

```bash
curl https://www.vibeapi.cn/v1/images/edits \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0",
    "prompt": "change the apple color to bright green, keep everything else identical",
    "image": {"type": "image_url", "url": "https://example.com/apple.jpg"}
  }'
```

**只收 JSON body。** OpenAI SDK 的 `images.edit()` 走 multipart 表单上传，打到本网关会 502
（`分组 auto 下模型 grok-imagine-image-2.0 的可用渠道不存在`）。改图请自行 POST JSON，图片走 URL 或 base64 内联。

`image` 字段接受四种写法，都能正常出图、计费一致：

```json
"image": {"type": "image_url", "url": "https://example.com/apple.jpg"}   // 文档写法
"image": {"url": "https://example.com/apple.jpg"}                       // 省略 type
"image": "https://example.com/apple.jpg"                                // 直接给字符串
"image": {"type": "image_url", "url": "data:image/jpeg;base64,...."}     // base64 内联
```

官方还支持一次最多 5 张源图（输出画幅默认跟随第一张，可用 `aspect_ratio` 覆盖）和 Files API 的 `file_id`；本网关输出仍固定 1248 × 832。
计费与文生图同档，按张；耗时 2.0 约 36–58 秒，上一代约 5 秒。

### 一致性

当前的改图更像「重画」而不是「编辑」：同一张红苹果原图、`keep everything else identical`，两代模型六次输出全部是按提示词重新绘制的新场景——
苹果确实变绿了，但桌面、背景、道具、构图都换了。

对一致性有硬要求的链路（换色、局部替换、批量套版），**先用自己的图跑一遍再上线**。
把必须保留的元素直接写进提示词（背景、材质、机位、光线）比只写「保留其余部分」更有效；如果目标是「同一主体动起来」，
[视频](https://docs.vibeapi.cn/zh/docs/grok-videos)接口的 `image`（锁首帧）与 `reference_images` 反而更接近「保留原图」的语义。

## 在线调试

填入你自己的 API Key 即可直接发起请求，参数表与响应结构由接口定义生成。

模型填 `grok-imagine-image-2.0`，`aspect_ratio` 等 Grok 专有参数可在请求体里手动加。改图接口只收 JSON，通用调试器走 multipart，不适用，请直接用上文的 curl。

<APIPage document={"openapi/generated/ai-model/图像（Images）/原生OpenAI格式/post-v1-images-generations-post-v1-images-generations-385320132.json"} operations={[{"path":"/v1/images/generations/","method":"post"}]} />

## 官方文档

* [xAI · Image Generation](https://docs.x.ai/developers/model-capabilities/images/generation) · [Image Editing](https://docs.x.ai/developers/model-capabilities/images/editing) · [Multi-Image Editing](https://docs.x.ai/developers/model-capabilities/images/multi-image-editing)


# Grok 视频

`POST /v1/videos/generations` · `POST /v1/videos/edits` · `POST /v1/videos/extensions`

异步两段式：提交拿到任务 ID → 轮询状态 → 取片。生成用 `grok-imagine-video-1.5`，编辑与延长用不带版本号的 `grok-imagine-video`。
按秒计费，见 [Grok 对话](https://docs.vibeapi.cn/zh/docs/grok#计费方式)。最后验证：2026-09-12。

## 基本调用

<Tabs items={['curl', 'Python', 'Node.js']}>
  <Tab value="curl">
    ```bash
    # 1. 提交
    curl https://www.vibeapi.cn/v1/videos/generations \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "grok-imagine-video-1.5",
        "prompt": "a blue ball rolling slowly on a white floor",
        "duration": 6,
        "resolution": "720p",
        "aspect_ratio": "16:9"
      }'

    # 2. 轮询（每 5–6 秒一次）
    curl "https://www.vibeapi.cn/v1/videos/$TASK_ID" -H "Authorization: Bearer $API_KEY"

    # 3. 取片
    curl -L "https://www.vibeapi.cn/v1/videos/$TASK_ID/content" \
      -H "Authorization: Bearer $API_KEY" -o out.mp4
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import time, requests

    BASE = "https://www.vibeapi.cn/v1"
    H = {"Authorization": "Bearer YOUR_API_KEY"}

    task = requests.post(f"{BASE}/videos/generations", headers=H, json={
        "model": "grok-imagine-video-1.5",
        "prompt": "a blue ball rolling slowly on a white floor",
        "duration": 6,
        "resolution": "720p",
        "aspect_ratio": "16:9",
    }).json()

    while True:
        s = requests.get(f"{BASE}/videos/{task['id']}", headers=H).json()
        if s["status"] in ("completed", "failed"):
            break
        time.sleep(5)

    if s["status"] == "completed":
        mp4 = requests.get(f"{BASE}/videos/{task['id']}/content", headers=H).content
        open("out.mp4", "wb").write(mp4)   # 视频会被回收，生成后立即落盘
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    import fs from "fs";

    const BASE = "https://www.vibeapi.cn/v1";
    const H = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };
    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

    const task = await (await fetch(`${BASE}/videos/generations`, {
      method: "POST",
      headers: H,
      body: JSON.stringify({
        model: "grok-imagine-video-1.5",
        prompt: "a blue ball rolling slowly on a white floor",
        duration: 6,
        resolution: "720p",
        aspect_ratio: "16:9",
      }),
    })).json();

    let s;
    while (true) {
      s = await (await fetch(`${BASE}/videos/${task.id}`, { headers: H })).json();
      if (s.status === "completed" || s.status === "failed") break;
      await sleep(5000);
    }

    if (s.status === "completed") {
      const mp4 = Buffer.from(await (await fetch(`${BASE}/videos/${task.id}/content`, { headers: H })).arrayBuffer());
      fs.writeFileSync("out.mp4", mp4);   // 视频会被回收，生成后立即落盘
    }
    ```
  </Tab>
</Tabs>

## 提交、轮询与取片

提交返回任务对象：

```json
{"id": "task_xxx", "request_id": "task_xxx", "object": "video", "status": "queued"}
```

轮询 `GET /v1/videos/{id}`，`status` 取值 `queued` → `in_progress` → `completed` / `failed`
（本网关统一成这套；xAI 原生是 `pending` / `done` / `expired` / `failed`）。建议每 5–6 秒查一次，2 秒视频约 20–30 秒完成，6 秒约 40 秒。

```json
{
  "id": "task_xxx",
  "status": "completed",
  "progress": 100,
  "seconds": "6",
  "metadata": {"url": "https://www.vibeapi.cn/v1/videos/task_xxx/content"}
}
```

取片 `GET /v1/videos/{id}/content`，返回 `video/mp4` 文件流，需带同一个 `Authorization` 头。

**视频不长期保存，请务必下载落盘。** `/content` 是实时代理，每次请求都从上游拉取转发，平台只存任务元数据；
上游会回收文件，数小时后再取可能返回 `Video request not found`，此时任务状态仍是 `completed` 但内容已取不回。

## 请求参数

| 参数                 | 支持 | 取值 / 说明                                                                        |
| ------------------ | -- | ------------------------------------------------------------------------------ |
| `prompt`           | ✅  | 文生视频必填；带 `image` / `reference_images` / `last_frame` 时可省略                      |
| `duration`         | ✅  | `1`–`15` 秒，超出返回 400；`seconds` 是等价别名                                            |
| `resolution`       | ✅  | `480p`（默认）/ `720p` / `1080p`（1.5 的文生、图生支持 1080p；参考图生视频上限 720p）                 |
| `aspect_ratio`     | ✅  | `1:1`、`16:9`（默认）/ `9:16`、`4:3` / `3:4`、`3:2` / `2:3`；图生视频默认跟随输入图               |
| `image`            | ✅  | 图生视频：`{"url": "..."}`，锁定首帧                                                     |
| `reference_images` | ✅  | 参考图，支持多张，见下文                                                                   |
| `last_frame`       | —  | 仅 1.5：锁定末帧；与 `image` 同传即首尾帧插值。未实测                                              |
| `generate_audio`   | —  | 默认 `true`（成片带音轨），`false` 出静音视频。未实测                                             |
| `reference_audios` | ⚠️ | 官方已开放预置音色，最多 3 个 `{"voice_id": "eve"}`，提示词用 `<AUDIO_0>` 引用；自定义音频仍限受信任伙伴。本网关未验证 |
| `size`             | ⚠️ | 无效，静默忽略；改用 `resolution`                                                        |

费用 = 每秒单价 × 实际输出秒数 × 分组倍率。按实际产出秒数结算，生成失败或超时全额退款；分辨率不影响单价。

## 多图生成视频

`image` 与 `reference_images` 都能传图，语义不同：

```text
// image：锁定首帧，视频从这张图开始运动
{"prompt": "make it spin", "image": {"url": "https://..."}}

// reference_images：引导内容与风格，不锁首帧，用 <IMAGE_n> 引用
{"prompt": "<IMAGE_1> slowly rotating", "reference_images": [{"url": "https://..."}]}
```

多图有三种写法，都能正常出片；提示词里用 `<IMAGE_1>` `<IMAGE_2>` 指代对应图片：

```json
// 写法一 · reference_images（推荐，与单图一致）
{
  "model": "grok-imagine-video-1.5",
  "prompt": "<IMAGE_1> and <IMAGE_2> together, slow pan",
  "reference_images": [{"url": "https://..."}, {"url": "https://..."}],
  "duration": 4
}

// 写法二 · image_urls（字符串数组）
{"prompt": "...", "image_urls": ["https://...", "https://..."]}

// 写法三 · frame_images（按帧引导）
{"prompt": "...", "frame_images": ["https://...", "https://..."]}
```

**每张图必须可公网直接获取。** 许多站点禁止外链引用，会失败并返回
`Failed to download the provided image ... the image host returned HTTP status 400`；用自有对象存储，或用生图接口返回的图片 URL。

## 视频编辑与延长

与生成共用同一套异步流程。**模型都用不带版本号的 `grok-imagine-video`**，`-1.5` 在这两个接口上返回 400。

| 写法                                                     | 模型                                     | 结果                                                       |
| ------------------------------------------------------ | -------------------------------------- | -------------------------------------------------------- |
| `POST /v1/videos/edits` + `video`                      | `grok-imagine-video`                   | ✅ 成片与源片等长（官方端点）                                          |
| `POST /v1/videos/edits` + `video`                      | `grok-imagine-video-1.5`               | ❌ 400 `Video editing is not supported for this model.`   |
| `POST /v1/videos/generations` + `video`（旧写法）           | `grok-imagine-video-1.5`，不传 `duration` | ✅ 但成片时长翻倍（4 秒变 8 秒）                                      |
| `POST /v1/videos/extensions` + `video` + `duration: 3` | `grok-imagine-video`                   | ✅ 成片 7 秒 = 4 + 3                                         |
| `POST /v1/videos/extensions`                           | `grok-imagine-video-1.5`               | ❌ 400 `Video extension is not supported for this model.` |

### 编辑

```bash
curl https://www.vibeapi.cn/v1/videos/edits \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "Add a small blue ribbon tied around the apple",
    "video": {"url": "https://.../source.mp4"}
  }'
```

编辑不接受 `duration` / `aspect_ratio` / `resolution`，输出继承源片，分辨率上限 720p、时长上限 8.7 秒。
`video.url` 可以是公网直链、`data:video/mp4;base64,...` 或 Files API 的 `file_id`。
旧写法 `/v1/videos/generations` + `video` 仍能提交，但用 1.5 且不传 `duration` 时成片翻倍、计费也翻倍；不建议再用。

### 延长

```bash
curl https://www.vibeapi.cn/v1/videos/extensions \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-video",
    "prompt": "The camera slowly zooms out revealing the whole table",
    "duration": 4,
    "video": {"url": "https://.../source.mp4"}
  }'
```

`duration` **只是延长部分的秒数**：4 秒源片 + `duration: 3` = 7 秒成片，轮询响应里的 `seconds` 也只报延长部分。
编辑、延长各自产出的视频重新按秒计费。

## 已知限制（截至 2026-09-21）

| 限制                                 | 说明                                                                    | 怎么办                                     |
| ---------------------------------- | --------------------------------------------------------------------- | --------------------------------------- |
| **10 秒以上不稳定**                      | `grok-imagine-video-1.5` 请求 15 秒时经常丢件或 400 / 404，失败全额退款               | 对外按 **≤ 10 秒** 设计；要更长先出 10 秒再走[延长](#延长) |
| **大文件取片**                          | 720p 10 秒约 15–20 MB，上游回源只有几十 KB/s，早期版本曾在 60 秒处截断成残片（2026-09-15 已修）    | 下载超时按 3 分钟设，校验文件能完整播放再入库                |
| **视频不长期保存**                        | 上游数小时后回收，`/content` 返回 `Video request not found`，任务状态仍是 `completed`   | 完成后立即下载                                 |
| **编辑 / 延长只认 `grok-imagine-video`** | `-1.5` 在 `/edits`、`/extensions` 上 400；旧写法不传 `duration` 成片与计费翻倍        | 见[视频编辑与延长](#视频编辑与延长)                    |
| **参数错误返回慢**                        | 上游拒绝的参数（如不支持的组合）网关会换线重试，可能十几秒后才收到 500                                 | 先按本页参数表自检，`size` 一类无效参数直接别传             |
| **未实测项**                           | `generate_audio` / `last_frame` / `reference_audios` 预置音色官方已开放，本网关未验证 | 用之前先小样本试                                |

## 商业方向样片

所有底图都是用 `gpt-image-2.5-sunburst` 出的（横版 2560×1440、竖版 1440×2560），
再作为首帧 / 参考图交给本页模型，提示词只写运镜与动态。成片保留原始音轨。

Grok 出片最快（1–2 分钟），8–10 秒最稳，适合竖版信息流广告快速出多版；15 秒目前不稳定。

<SampleVideos items={[{"src": "https://studio.vibevibe.cn/docs/260915/biz/video/fashion.mp4", "poster": "https://studio.vibevibe.cn/docs/260915/biz/poster/fashion.webp", "caption": "服装 · 沙丘长裙 · grok-imagine-video-1.5 · 8 s", "portrait": true}, {"src": "https://studio.vibevibe.cn/docs/260915/biz/video/ev-car-grok.mp4", "poster": "https://studio.vibevibe.cn/docs/260915/biz/poster/ev-car-grok.webp", "caption": "汽车 · 海岸公路 · grok-imagine-video-1.5 · 8 s", "portrait": false}]} />

## 官方文档

* [xAI · Video Generation](https://docs.x.ai/developers/model-capabilities/video/generation) · [Image-to-Video](https://docs.x.ai/developers/model-capabilities/video/image-to-video) · [Reference-to-Video](https://docs.x.ai/developers/model-capabilities/video/reference-to-video) · [Video Editing](https://docs.x.ai/developers/model-capabilities/video/editing) · [Video Extension](https://docs.x.ai/developers/model-capabilities/video/extension)


# Grok 对话

<HeroVideo src="https://studio.vibevibe.cn/docs/260915/docs-intro/video/grok.mp4" poster="https://studio.vibevibe.cn/docs/260915/docs-intro/poster/grok.webp" model="wan3.0-video-prime-720p" />

`POST /v1/chat/completions` · `POST /v1/responses`

xAI 的 Grok 系列在本网关上覆盖对话、图像、视频三类能力，共 7 个模型 ID，全部走 OpenAI 兼容协议：
`base_url` 填 `https://www.vibeapi.cn/v1`，`openai` SDK 直接用。**它的参数支持与 OpenAI 系差别不小**：
`stop`、`presence_penalty`、`frequency_penalty`、`n`、`logprobs` 传了都返回 200，但都不生效。本页讲对话与全系列共用的模型、计费、错误；
生图见 [Grok 图像](https://docs.vibeapi.cn/zh/docs/grok-images)，视频见 [Grok 视频](https://docs.vibeapi.cn/zh/docs/grok-videos)，在 Claude Code 里使用，用 [VibeCLI 一条命令配好](https://docs.vibeapi.cn/zh/docs/coding-tools/claude-code)，`/model` 里直接选 Grok。

本页结论来自对本网关的真实调用，并对照 [docs.x.ai](https://docs.x.ai) 逐条核对；与官方口径不一致之处均标注「实测」。最后验证：2026-10-13（联网搜索）、2026-09-23（其余）。

## 基本调用

<Tabs items={['curl', 'Python', 'Node.js']}>
  <Tab value="curl">
    ```bash
    curl -N https://www.vibeapi.cn/v1/chat/completions \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "grok-4.7",
        "messages": [{"role": "user", "content": "用一句话解释量子纠缠"}],
        "stream": true
      }'
    ```
  </Tab>

  <Tab value="Python">
    ```python
    from openai import OpenAI

    client = OpenAI(base_url="https://www.vibeapi.cn/v1", api_key="YOUR_API_KEY")

    stream = client.chat.completions.create(
        model="grok-4.7",
        messages=[{"role": "user", "content": "用一句话解释量子纠缠"}],
        stream=True,
    )
    for chunk in stream:
        print(chunk.choices[0].delta.content or "", end="", flush=True)
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    import OpenAI from "openai";

    const client = new OpenAI({ baseURL: "https://www.vibeapi.cn/v1", apiKey: "YOUR_API_KEY" });

    const stream = await client.chat.completions.create({
      model: "grok-4.7",
      messages: [{ role: "user", content: "用一句话解释量子纠缠" }],
      stream: true,
    });
    for await (const chunk of stream) {
      process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
    }
    ```
  </Tab>
</Tabs>

## 模型

| 模型                           | 能力                             | 端点                                            | 计费                  |
| ---------------------------- | ------------------------------ | --------------------------------------------- | ------------------- |
| `grok-4.7`                   | 对话 / 推理，最新一代                   | `/v1/chat/completions` · `/v1/responses`      | 按 token，两档，与 4.6 同价 |
| `grok-4.6`                   | 对话 / 推理                        | 同上                                            | 按 token，两档          |
| `grok-4.5`                   | 对话 / 推理，上上代                    | 同上                                            | 按 token，两档，与 4.6 同价 |
| `grok-imagine-image-2.0`     | 文生图 + 图生图，当前主力                 | `/v1/images/generations` · `/v1/images/edits` | 按张                  |
| `grok-imagine-image-quality` | 文生图 + 图生图，上一代                  | 同上                                            | 按张                  |
| `grok-imagine-video-1.5`     | 文生 / 图生 / 参考图生视频               | `/v1/videos/generations`                      | **按秒**              |
| `grok-imagine-video`         | **视频编辑 + 视频延长**（这两个接口只接受这个模型名） | `/v1/videos/edits` · `/v1/videos/extensions`  | **按秒**              |

`grok-imagine-image-quality` 官方定于 **2026-11-02 退役**，之后这个模型名由 2.0 以 `quality: low` 接管，请求与响应形状不变。
它目前是唯一能指定画幅的 Grok 图像模型，依赖竖图 / 方图的链路要提前打算，见[图像](https://docs.vibeapi.cn/zh/docs/grok-images#画幅)。

## 计费方式

单价随分组倍率变动，一律以[价格页](https://www.vibeapi.cn/pricing)为准；这里只讲计费方式，也就是写代码时会影响费用的那几件事。

**对话按 token，分两档。** 单次请求的输入达到 **200K token** 时进入第二档，输入、输出、缓存读取单价全部翻倍。
`grok-4.7`、`grok-4.6`、`grok-4.5` 三个定价相同，包括这条分档规则。4.6 与 4.5 都能吃下超长上下文（实测 210K 输入正常返回），
越界的是费用档位，不是上下文长度——把长文档一次性塞进 prompt 之前先算一遍账，能拆到 200K 以内就拆。

**图像按张。** `n` 张就是 `n` 份费用。图生图复用生图模型，价格与文生图同档。

**联网搜索按次。** 走 Responses 入口时，`web_search` 按实际搜索次数计费，每千次 5 美元；`x_search` 按抓取的 X 帖子（每千条 5 美元）和用户资料（每千份 10 美元）计。都要乘分组倍率，调用日志里写明次数与费用。模型没有真的去搜就不收这部分。

**视频按秒，不是按次。** 价格页给的是每秒单价，一条 6 秒视频要乘 6；按实际产出秒数结算，生成失败或超时全额退款。
编辑、延长各自产出的视频重新计费。

## 新旧两代怎么选

| 场景          | 选谁                           | 原因                                                                                |
| ----------- | ---------------------------- | --------------------------------------------------------------------------------- |
| 长时 Agent、编码 | `grok-4.7`                   | 与 4.6 同价，参数支持一致（2026-09-23 逐项复测）；每次请求多带约 1,000 个隐藏输入 token，见[推理 token](#推理-token) |
| 短问答、高频小请求   | `grok-4.6`                   | 隐藏输入约 210 token，单次成本低于 4.7；与 4.5 同价同参数，没有留在 4.5 的理由                               |
| 横图、默认画幅     | `grok-imagine-image-2.0`     | 固定输出 1248×832                                                                     |
| 竖图、方图、指定画幅  | `grok-imagine-image-quality` | 2.0 在本网关不认 `aspect_ratio`，只有它能指定画幅；注意 11-02 退役                                    |
| 批量出图、对延迟敏感  | `grok-imagine-image-quality` | 单张约 5 秒；2.0 约 40–60 秒                                                             |

## 请求参数

| 参数                                       | 支持 | 说明                                                                                                                                                    |
| ---------------------------------------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messages`                               | ✅  | 必填                                                                                                                                                    |
| `max_tokens`                             | ✅  | 只约束可见回复，推理 token 另算：设 20 时实得 20 个可见 token + 96 个推理 token                                                                                              |
| `temperature` / `top_p`                  | ✅  |                                                                                                                                                       |
| `n`                                      | ⚠️ | 返回 200，但只回 1 个 choice（4.5 / 4.6 / 4.7 相同；2026-09-12 时 `n=2` 还能返回 2 个）。要多个候选请并发多次                                                                      |
| `seed`                                   | ✅  | 接受，但推理模型不保证复现，见下文                                                                                                                                     |
| `stream`                                 | ✅  | SSE 流式                                                                                                                                                |
| `tools` / `tool_choice`                  | ✅  | 标准 Function Calling。Chat 接口不支持 xAI 的内置搜索（带上 `web_search` / `x_search` 会返回 422），网关会移除 `web_search`；要联网请走 [Responses 入口](#联网搜索)                         |
| `response_format`                        | ✅  | `{"type": "json_object"}` 可用                                                                                                                          |
| `reasoning_effort`                       | ✅  | `low` / `medium` / `high`（默认）/ `xhigh`，四档均可用（4.6 实测 reasoning\_tokens 约 99 / 161 / 157 / 212）；`none` 返回 200 但推理照常（仍有约 200 个 reasoning\_tokens），推理不可关闭 |
| `logprobs` / `top_logprobs`              | ⚠️ | 返回 200 但字段为 null，**静默忽略**                                                                                                                             |
| `stop`                                   | ⚠️ | 返回 200，**静默忽略**：停止词照常出现在输出里                                                                                                                           |
| `presence_penalty` / `frequency_penalty` | ⚠️ | 返回 200，从响应上看不出是否生效，按不生效处理                                                                                                                             |

**`stop` 不再报错，但也不生效。** 2026-09-12 时这三个参数传了直接 400；2026-09-23 复测 4.5 / 4.6 / 4.7 都改成返回 200、
输出不受约束。依赖停止序列截断的逻辑，要改成在客户端截断。

多轮对话建议带上 `prompt_cache_key`（Responses）或请求头 `x-grok-conv-id`（Chat），把同一会话路由到同一台服务器以稳定命中缓存；
否则常按全价输入计费。

## Responses 入口

xAI 官方把 Responses API 列为首选入口，本网关可用：

```bash
curl https://www.vibeapi.cn/v1/responses \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": [{"role": "user", "content": "How do stars form?"}],
    "reasoning": {"effort": "high"}
  }'
```

|      | `/v1/chat/completions` | `/v1/responses`             |
| ---- | ---------------------- | --------------------------- |
| 会话状态 | 无状态，每次重发全部历史           | 官方支持服务端保存                   |
| 多轮   | 自行拼接 `messages`        | 官方支持 `previous_response_id` |
| 推理档位 | `reasoning_effort`     | `reasoning.effort`          |

本网关返回 `store: false`，即服务端留存未开启，多轮对话仍需自行携带历史（xAI 官方默认 `store: true` 保存 30 天，这是网关侧差异）。

### 联网搜索

Responses 入口支持 xAI 的两个服务端搜索工具，由 xAI 服务端执行，结果直接写进回答：

* `web_search`：网页搜索。回复的 `output` 里每搜一次有一个 `web_search_call` 条目。
* `x_search`：搜 X（Twitter）上的帖子和用户资料。

```bash
curl https://www.vibeapi.cn/v1/responses \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "input": "联网搜一条今天的科技新闻，一句话，带出处",
    "tools": [{"type": "web_search"}]
  }'
```

* OpenAI 规范里 `web_search` 的 `external_web_access`、`search_context_size` 两个字段 xAI 不支持，网关转发前会删掉，工具本身保留。Codex 默认会带 `external_web_access`，所以 Codex 接 Grok 可以直接联网。
* `user_location`、`filters`（如 `allowed_domains`）可用。
* 旧写法 `web_search_preview` 不报错，但不会真的执行搜索，请用 `web_search`。
* Chat 接口（`/v1/chat/completions`）不支持这两个工具。
* 费用见上文[计费方式](#计费方式)。

## 推理 token

三个对话模型都是推理模型，`usage` 里会有推理消耗：

```json
"usage": {
  "prompt_tokens": 212,
  "completion_tokens": 65,
  "completion_tokens_details": { "reasoning_tokens": 63 },
  "prompt_tokens_details": { "cached_tokens": 128 }
}
```

上例一句「回复 PONG」实际消耗 65 个输出 token，其中 **63 个是推理 token**，可见回复只占 2 个。
按可见回复长度估算成本会严重偏低，请以 `usage` 为准；`reasoning_effort: "low"` 能明显压低这部分开销。

固定 `seed` 与 `temperature=0` 连续调用，推理 token 数与措辞仍会波动（同一句提示词四次分别 282 / 286 / 311 / 294）。
推理模型不保证确定性复现，需要稳定输出的场景请在应用层处理。

**隐藏输入 token。** 上例只发了一句话，`prompt_tokens` 却是 212——每次请求都带着一段看不见的系统提示。
`grok-4.7` 的这部分更大：发一句 `hi`，`prompt_tokens` 是 1,243，其中 1,152 命中缓存（按缓存读取单价计费）。
估算成本时把这段固定开销算进去，高频短请求用 4.6 更省。

## 真实响应示例

最后一条是传了 `stop` 的真实响应：返回 200，回复末尾仍是停止词「。」。

<Examples group="grok" open="grok-chat" />

## 容量抖动

Grok 图片 / 视频的号池容量有限，突发并发会失败，而且失败表现与「参数不被支持」很像，容易误判：
同时提交 8 个视频任务，提交全部返回 200，生成阶段整批 `failed`；相同参数单发或并发 ≤ 2 时全部成功。
失败信息也很笼统（`upstream returned error` / `no eligible account`）。

视频提交并发控制在 2 以内，失败用指数退避重试 3–5 次，不要因单次失败就判定某参数不可用。

## 错误速查

| 现象                                                                                                        | 原因                                                  | 处理                                           |
| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------------- |
| 设了 `stop`，输出没在停止词处截断                                                                                      | Grok 静默忽略 `stop`                                    | 在客户端截断                                       |
| `n=2` 只拿到 1 个 choice                                                                                      | Grok 现在不执行 `n`                                      | 并发多次请求                                       |
| `reasoning_effort: none` 仍有 reasoning\_tokens                                                             | 推理不可关闭                                              | 用 `low` 压低开销                                 |
| 400 `seconds must be between 1 and 15`                                                                    | 视频时长越界                                              | 调整至 1–15                                     |
| 400 `The number of images to generate (n) must be between 1 and 10 inclusive`                             | 生图数量越界                                              | 调整至 1–10                                     |
| 非流式请求返回空的 `text/event-stream`，正文只有 `data: [DONE]`                                                         | 上游抖动，一次性空响应                                         | 直接重试                                         |
| 生图 `aspect_ratio` / `resolution` / `quality` 设了不生效                                                        | `grok-imagine-image-2.0` 在本网关不认这些参数                 | 指定画幅用 `grok-imagine-image-quality`（11-02 退役） |
| 视频 `failed` 但参数无误                                                                                         | 容量抖动                                                | 退避重试                                         |
| 视频 `failed` + `image_download_error`                                                                      | 参考图无法公网直接获取                                         | 换可直接引用的图床                                    |
| 改图 502 `可用渠道不存在`                                                                                          | 用了 multipart/form-data 上传图片                         | 改成 JSON body，图片走 URL 或 base64 内联             |
| `/content` 502 或 `Video request not found`，任务却是 `completed`                                               | 视频已被回收                                              | 无法找回，需重新生成；今后生成完立即下载落盘                       |
| 400 `Video editing is not supported for this model.` / `Video extension is not supported for this model.` | 编辑或延长接口传了 `grok-imagine-video-1.5`                  | 换成不带版本号的 `grok-imagine-video`                |
| 视频编辑后时长翻倍（4 秒变 8 秒）                                                                                       | 走了旧写法 `/generations` + `video` 且用 1.5 不传 `duration` | 改用 `/v1/videos/edits` + `grok-imagine-video` |

## 迁移 OpenAI 代码的检查清单

* `stop` / `presence_penalty` / `frequency_penalty` / `n` / `logprobs` 传了不报错也不生效，依赖它们的逻辑改到客户端
* `reasoning_effort` 用 `low` / `medium` / `high` / `xhigh`；`none` 不报错，但关不掉推理
* 预算按 `usage` 里的 `reasoning_tokens` 与 `prompt_tokens` 重新估算——推理 token 和隐藏系统提示都可能远超可见内容
* 生图把 `size` 换成 `aspect_ratio`；用 2.0 时不要依赖画幅，固定 1248×832
* 改图改成 JSON body，不要用 SDK 的 multipart `images.edit()`
* 视频把 `size` 换成 `resolution`，改成异步轮询，生成完立即下载
* 视频编辑走 `/v1/videos/edits`、延长走 `/v1/videos/extensions`，模型都写 `grok-imagine-video`

## 能力边界

* `stop`、`presence_penalty`、`frequency_penalty`、`n`、`logprobs` 返回 200 但不生效。
* 推理不可关闭，`reasoning_effort: none` 返回 200 但照常推理。
* Chat 接口不支持内置搜索，`web_search` 会被网关移除；联网请用 Responses 的 `web_search` / `x_search`（按次计费）。
* Responses 的服务端留存未开，`store` 恒为 `false`，多轮仍需自带历史。
* `grok-imagine-image-2.0` 不认 `aspect_ratio` / `resolution` / `quality`，只出 1248×832。
* `size` 在图像与视频接口里都被静默忽略，改用 `aspect_ratio` / `resolution`。
* 视频文件会被回收，生成完成后立即下载落盘，之后 `/content` 可能取不到。
* `grok-imagine-edit` 已下线，代码里还有这个模型名的请移除。

## 在线调试

填入你自己的 API Key 即可直接发起请求，参数表与响应结构由接口定义生成。

模型填 `grok-4.7` 或 `grok-4.6`。

### Chat Completions

<APIPage document={"openapi/generated/ai-model/聊天（Chat）/原生OpenAI格式/post-v1-chat-completions-createchatcompletion-383826473.json"} operations={[{"path":"/v1/chat/completions","method":"post"}]} />

### Responses

<APIPage document={"openapi/generated/ai-model/聊天（Chat）/原生OpenAI格式/post-v1-responses-createresponse-383826475.json"} operations={[{"path":"/v1/responses","method":"post"}]} />

## 官方文档

* [xAI · Grok 4.6](https://docs.x.ai/developers/grok-4-6) · [Reasoning](https://docs.x.ai/developers/model-capabilities/text/reasoning) · [Models](https://docs.x.ai/developers/models) · [Pricing](https://docs.x.ai/developers/pricing) · [Release Notes](https://docs.x.ai/developers/release-notes)


# 图像生成概览

<HeroVideo src="https://studio.vibevibe.cn/docs/260915/docs-intro/video/images.mp4" poster="https://studio.vibevibe.cn/docs/260915/docs-intro/poster/images.webp" model="grok-imagine-video-1.5" />

图像生成分散在三个端点上，先确认你要的模型走哪一个：

| 模型                                                                                            | 端点                                            | 页面                                              |
| --------------------------------------------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------- |
| `gpt-image-2` · `gpt-image-2.5-flare` · `gpt-image-2.5-sunburst`                              | `/v1/images/generations` · `/v1/images/edits` | [GPT 图像 · Image API](https://docs.vibeapi.cn/zh/docs/images)           |
| `gpt-6-astra` + `image_generation` 工具                                                         | `/v1/responses`                               | [GPT 图像 · Responses](https://docs.vibeapi.cn/zh/docs/images-responses) |
| `gemini-3-pro-image` · `gemini-3.1-flash-image` · `gemini-3.1-flash-lite-image`（含 `-preview`） | `/v1beta/models/{model}:generateContent`      | [Gemini 图像生成](https://docs.vibeapi.cn/zh/docs/gemini-images)           |
| `grok-imagine-image-2.0` · `grok-imagine-image-quality`                                       | `/v1/images/generations` · `/v1/images/edits` | [Grok 图像](https://docs.vibeapi.cn/zh/docs/grok-images)                 |
| `wan3.0-image-*`                                                                              | `/v1/videos`（图生视频，不是出图）                       | [万相 3.0](https://docs.vibeapi.cn/zh/docs/videos-wan)                   |

## GPT 的两套入口

|                    | Image API                              | Responses                         |
| ------------------ | -------------------------------------- | --------------------------------- |
| 调用模型               | `gpt-image-2` / `gpt-image-2.5-*`，直接指定 | `gpt-6-astra` 内部调度，无法指定           |
| `size` / `quality` | 按请求执行，4K + high 精确返回                   | 被改写：要 4K/high 实得 1536×1024/medium |
| 耗时                 | 4K + high 约 45–57 秒                    | 40–170 秒                          |
| 多轮编辑 / 自动优化提示词     | 无                                      | 有                                 |

**默认用 Image API**；只在需要对话式多轮编辑时用 Responses。Image API 上三个模型的差别（`n`、透明背景、耗时）见[怎么选](https://docs.vibeapi.cn/zh/docs/images#三个-gpt-图像模型怎么选)。

## 三条通用约束

* **图片返回有两种形态。** Image API 的 `data[0]` 可能是 `b64_json`（内联）也可能是 `url`（临时链接，尽快下载），`response_format` 不决定形态，两种都要处理。
* **Gemini 生图必须走原生端点。** 走 Chat 兼容协议能出图，但 `imageConfig`（画幅、分辨率）会在协议转换中丢掉。
* **Grok 2.0 画幅固定 1248×832。** 需要竖图用 `grok-imagine-image-quality`，它 2026-11-02 退役。

## 实测样图

各页附真实调用产出的样图：GPT 六主题 4K（东方水墨、仙侠、工笔重彩、空间站、巨构城市、戴森云）在 [Image API 页](https://docs.vibeapi.cn/zh/docs/images#实测4k-最高画质)，
Responses 降级对照在 [Responses 页](https://docs.vibeapi.cn/zh/docs/images-responses#与-image-api-的差异)。缩略图点击可放大。


# GPT 图像 · Responses

`POST /v1/responses`

GPT 图像的第二套入口：主线模型 `gpt-6-astra` 理解意图、自动优化提示词，再调度 `image_generation` 工具出图，SSE 流式回传、心跳保活。
它的价值在**对话式多轮编辑**和自动 `revised_prompt`；但它无法指定图像模型，`size` / `quality` 会被改写——要 4K/high 实得 1536×1024/medium。
**默认生图请用 [Image API](https://docs.vibeapi.cn/zh/docs/images)**，那边按请求精确返回 4K。

本页结论来自对本网关的真实调用，最后验证：2026-09-12。

## 基本调用

请求发出后约 3\~4 秒即开始回传事件，读流式响应时客户端超时建议设到 300 秒以上。

<Tabs items={['curl', 'Python', 'Node.js']}>
  <Tab value="curl">
    ```bash
    curl -N -sS "https://www.vibeapi.cn/v1/responses" \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "gpt-6-astra",
        "input": "一只灰色虎斑猫抱着戴橙色围巾的水獭，温暖的童书插画风格",
        "stream": true,
        "tools": [{"type": "image_generation"}]
      }'
    ```
  </Tab>

  <Tab value="Python">
    ```python
    from openai import OpenAI
    import base64

    client = OpenAI(base_url="https://www.vibeapi.cn/v1", api_key="YOUR_API_KEY")

    stream = client.responses.create(
        model="gpt-6-astra",
        input="一只灰色虎斑猫抱着戴橙色围巾的水獭，温暖的童书插画风格",
        tools=[{"type": "image_generation"}],
        stream=True,
    )

    for event in stream:
        if event.type == "response.image_generation_call.partial_image":
            with open("out.png", "wb") as f:
                f.write(base64.b64decode(event.partial_image_b64))
    print("已生成 out.png")
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    import OpenAI from "openai";
    import fs from "fs";

    const client = new OpenAI({
      baseURL: "https://www.vibeapi.cn/v1",
      apiKey: "YOUR_API_KEY",
    });

    const stream = await client.responses.create({
      model: "gpt-6-astra",
      input: "一只灰色虎斑猫抱着戴橙色围巾的水獭，温暖的童书插画风格",
      tools: [{ type: "image_generation" }],
      stream: true,
    });

    for await (const event of stream) {
      if (event.type === "response.image_generation_call.partial_image") {
        fs.writeFileSync("out.png", Buffer.from(event.partial_image_b64, "base64"));
      }
    }
    ```
  </Tab>
</Tabs>

图片数据位于 `response.image_generation_call.partial_image` 事件的 `partial_image_b64` 字段（base64 编码）。完整事件序列见[流式事件序列](#流式事件序列)。

实测输出（约 30 秒）：

<ImageGrid cols={1} items={[{"src": "/img/gpt-image/cat-otter.jpg", "alt": "cat-otter", "caption": "灰色虎斑猫抱着戴橙色围巾的水獭"}]} />

## 与 Image API 的差异

|                    | Responses（本页）                          | Image API                              |
| ------------------ | -------------------------------------- | -------------------------------------- |
| 调用模型               | `gpt-6-astra`，内部调度图像模型，无法指定            | `gpt-image-2` / `gpt-image-2.5-*`，直接指定 |
| `size` / `quality` | 被改写：要 4K/high 实得 1536×1024/medium      | 按请求执行                                  |
| 耗时                 | 40–170 秒                               | 4K + high 约 45–57 秒                    |
| 提示词优化              | 自动，返回 `revised_prompt`                 | 无                                      |
| 多轮编辑               | 支持，上下文携带图片                             | 不支持                                    |
| 参考图                | URL / base64 / `file_id`；URL 由上游主动下载   | multipart 文件上传                         |
| 返回                 | SSE 事件里的 base64；非流式在 `output[].result` | `data[0].b64_json` 或 `url`             |
| 流式                 | 支持，心跳保活，大图不中断                          | 同步返回                                   |

实测：同样请求 `3840x2160` + `high`，三个主题都被降到 1536×1024 / medium：

| 主题   | 耗时      | 实返 size / quality      |
| ---- | ------- | ---------------------- |
| 东方水墨 | 40.2 s  | `1536x1024` / `medium` |
| 工笔重彩 | 166.7 s | `1536x1024` / `medium` |
| 仙侠   | 171.4 s | `1536x1024` / `medium` |

<ImageGrid cols={3} items={[{"src": "/img/gpt-image/ink-mountains-responses.jpg", "alt": "Responses · 要 3840×2160/high，实得 1536×1024/medium · 40 s", "caption": "Responses · 要 3840×2160/high，实得 1536×1024/medium · 40 s"}, {"src": "/img/gpt-image/xianxia-sword-responses.jpg", "alt": "Responses · 同上 · 171 s", "caption": "Responses · 同上 · 171 s"}, {"src": "/img/gpt-image/guofeng-palace-responses.jpg", "alt": "Responses · 同上 · 167 s", "caption": "Responses · 同上 · 167 s"}]} />

## 请求结构

```
POST https://www.vibeapi.cn/v1/responses
Authorization: Bearer <API_KEY>
Content-Type: application/json
```

顶层请求字段：

| 字段                     | 类型              | 必填    | 默认      | 说明                                                                                               |
| ---------------------- | --------------- | ----- | ------- | ------------------------------------------------------------------------------------------------ |
| `model`                | string          | 是     | —       | 主线模型，生成图片固定使用 `gpt-6-astra`                                                                      |
| `input`                | string \| array | 是     | —       | 用户输入。字符串表示纯文本；数组表示多模态（文本 + 图片）。详见 [input 字段详解](#input-字段)                                        |
| `tools`                | array           | 是（生图） | —       | 内置工具列表，生成图片须包含 `{"type":"image_generation"}`。详见 [image\_generation 工具参数](#image_generation-工具参数) |
| `stream`               | boolean         | 否     | `false` | `true` 启用 SSE 流式（推荐）；`false` 一次性返回完整 JSON                                                        |
| `instructions`         | string          | 否     | —       | 系统级指令。可选，不传也能正常生成                                                                                |
| `previous_response_id` | string          | 否     | —       | 关联上一次响应以实现多轮。本网关不支持，见[多轮编辑](#多轮编辑与参考图输入)                                                         |

最小请求（字符串形式的 `input`）：

```json
{
  "model": "gpt-6-astra",
  "input": "a red apple on a wooden table",
  "stream": true,
  "tools": [{ "type": "image_generation" }]
}
```

完整请求（数组形式的 `input` + 全参数工具）：

```json
{
  "model": "gpt-6-astra",
  "instructions": "You are a helpful image generation assistant.",
  "input": [
    { "role": "user", "content": [{ "type": "input_text", "text": "Draw a watercolor winter landscape" }] }
  ],
  "stream": true,
  "tools": [
    {
      "type": "image_generation",
      "quality": "high",
      "size": "1536x1024",
      "output_format": "webp",
      "output_compression": 50,
      "moderation": "low",
      "partial_images": 2
    }
  ]
}
```

### `input` 字段

`input` 有两种写法，本网关均已对齐 OpenAI 协议：

写法一，字符串（最简，纯文本生成）：

```json
"input": "a red apple on a wooden table"
```

写法二，数组（多模态，文本 + 参考图，编辑与 Vision 必用）：

```json
"input": [
  {
    "role": "user",
    "content": [
      { "type": "input_text",  "text": "把这张图改成水彩风格" },
      { "type": "input_image", "image_url": "https://.../photo.jpg" }
    ]
  }
]
```

`content` 数组中每个 part 的类型：

| part 类型       | 字段                  | 说明                                                |
| ------------- | ------------------- | ------------------------------------------------- |
| `input_text`  | `text`（string）      | 文本指令                                              |
| `input_image` | `image_url`（string） | 参考图：公网 URL，或 `data:image/...;base64,...` data URI |
| `input_image` | `file_id`（string）   | 参考图：经 Files API 上传后得到的文件 ID                       |
| `input_image` | `detail`（string）    | 仅图片理解时使用，控制理解精度，见 [Vision 图片理解](#vision-图片理解)     |

一个 `content` 数组可包含多个 `input_image`（多参考图）。三种参考图写法的完整示例见 [多轮编辑与参考图输入](#多轮编辑与参考图输入)。

### `image_generation` 工具参数

生成能力通过 `tools` 数组中的 `image_generation` 对象配置。逐字段说明如下：

| 字段                   | 类型     | 取值                                        | 默认     | 说明                                           |
| -------------------- | ------ | ----------------------------------------- | ------ | -------------------------------------------- |
| `type`               | string | `"image_generation"`                      | —      | 必填，固定值，声明启用生成工具                              |
| `quality`            | string | `low` / `medium` / `high` / `auto`        | `auto` | 渲染质量。`low` 最快（草稿、缩略图），`high` 最精细（耗时最长）       |
| `size`               | string | 同 [Image API](https://docs.vibeapi.cn/zh/docs/images#输出定制) 的尺寸约束 | `auto` | 期望尺寸；本网关会改写，以响应实际尺寸为准                        |
| `output_format`      | string | `png` / `jpeg` / `webp`                   | `png`  | 输出格式。Responses 工具遵循该参数（实测 `webp` 返回真正的 WebP） |
| `output_compression` | number | `0`–`100`                                 | —      | 压缩级别（仅 `jpeg` / `webp`）。`50` 表示压缩 50%        |
| `moderation`         | string | `auto` / `low`                            | `auto` | 内容审核强度，`low` 更宽松                             |
| `action`             | string | `auto` / `generate` / `edit`              | `auto` | 强制生成或编辑，详见下文与 [多轮编辑与参考图输入](#多轮编辑与参考图输入)      |
| `partial_images`     | number | `0`–`3`                                   | —      | 流式过程中下发的中间预览帧数。`0` 表示只下发最终图                  |
| `input_image_mask`   | object | `{"file_id": "..."}`                      | —      | 蒙版编辑，蒙版区域被重绘，详见 [多轮编辑与参考图输入](#多轮编辑与参考图输入)    |

逐字段示例：

`quality`——三档质量（其余参数固定）：

```json
{ "type": "image_generation", "quality": "low" }     // 快，草稿
{ "type": "image_generation", "quality": "high" }    // 慢，成片
```

`output_format` + `output_compression`——输出 WebP 并压缩 50%：

```json
{ "type": "image_generation", "output_format": "webp", "output_compression": 50 }
```

`moderation`——放宽审核：

```json
{ "type": "image_generation", "moderation": "low" }
```

`action`——强制行为（默认 `auto` 由模型自行决定生成还是编辑）：

```json
{ "type": "image_generation", "action": "generate" }  // 总是新建图片
{ "type": "image_generation", "action": "edit" }      // 强制编辑上下文中的图片；无图则报错
```

`partial_images`——流式下发 2 帧中间预览：

```json
{ "type": "image_generation", "partial_images": 2 }
```

全参数组合的真实请求与响应见[流式事件序列](#流式事件序列)；`size` / `quality` 在本页会被改写，见[与 Image API 的差异](#与-image-api-的差异)。

## 流式与非流式

|           | 流式 `stream:true`（推荐）                    | 非流式 `stream:false`                          |
| --------- | --------------------------------------- | ------------------------------------------- |
| 返回        | SSE 事件流，逐帧回传                            | 一次性完整 JSON                                  |
| 取图        | `partial_image` 事件的 `partial_image_b64` | `output[]` 中 `image_generation_call.result` |
| 首字节       | 3\~4 秒                                  | 渲染完成后才返回                                    |
| 大图 / high | 心跳保活，不中断                                | 存在 `504` 风险                                 |
| 实测耗时      | —                                       | 约 80\~140 秒（medium 1K）                      |

> 读流式响应时，客户端超时建议设到 300 秒以上：大图渲染常要好几分钟，默认的短超时（比如 60 秒）会把请求自己掐断，反而拿不到图。

非流式真实响应结构（`gpt-6-astra` + medium，`result` 已截断）：

```json
{
  "id": "resp_0bb33694b11513cf016a3d4bb1d4a0819b918d29bc82aa4358",
  "object": "response",
  "status": "completed",
  "model": "gpt-6-astra",
  "output": [
    {
      "id": "ig_0bb33694b11513cf016a3d4bbb4b54819b9ba7731790d4d87d",
      "type": "image_generation_call",
      "status": "generating",
      "action": "generate",
      "background": "opaque",
      "output_format": "png",
      "quality": "medium",
      "result": "iVBORw0KGgoAAAANSU...<3493728 字节 base64>",
      "revised_prompt": "Oil painting still life...<407 字符>",
      "size": "1400x1123"
    },
    { "type": "message", "role": "assistant", "content": [{ "type": "output_text", "text": "" }] }
  ],
  "reasoning": { "effort": "medium" },
  "service_tier": "default",
  "store": false
}
```

非流式取图代码：

```python
resp = client.responses.create(
    model="gpt-6-astra",
    input="An oil painting still life of fruit and wine, Rembrandt lighting",
    tools=[{"type": "image_generation", "quality": "medium"}],
)
for item in resp.output:
    if item.type == "image_generation_call":
        with open("out.png", "wb") as f:
            f.write(base64.b64decode(item.result))
        print("revised_prompt:", item.revised_prompt)
        print("实际尺寸:", item.size)   # 实际尺寸由上游裁定，与请求不同
```

<ImageGrid cols={1} items={[{"src": "/img/gpt-image/oil-still-life.jpg", "alt": "oil-still-life", "caption": "非流式实测：油画静物（约 140 秒）"}]} />

### 流式事件序列

完整 SSE 事件类型（实测自全参数流式请求）：

| 事件 `type`                                                                | 关键字段                                                                                  | 含义                           |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- | ---------------------------- |
| `response.created`                                                       | `response.id`                                                                         | 请求创建，获得 response id          |
| `response.in_progress`                                                   | —                                                                                     | 开始处理                         |
| `response.output_item.added`                                             | `item.id`（`ig_…`）、`output_index`                                                      | 新建一个 image\_generation\_call |
| `response.image_generation_call.in_progress`                             | `item_id`                                                                             | 图片生成中                        |
| `response.image_generation_call.generating`                              | `item_id`                                                                             | 正在渲染                         |
| `response.image_generation_call.partial_image`                           | `partial_image_b64`、`partial_image_index`、`output_index`、`background`、`output_format` | 图片数据（中间帧或最终帧）                |
| `keepalive`                                                              | `sequence_number`                                                                     | 心跳，长时间渲染时出现，用于保持连接           |
| `response.output_item.done`                                              | `item.revised_prompt`                                                                 | image\_generation\_call 完成   |
| `response.content_part.added` / `output_text.done` / `content_part.done` | —                                                                                     | 附带的文本消息（生成图片时通常为空串）          |
| `response.completed`                                                     | `response.output[]`                                                                   | 完成，包含最终 output 数组            |

真实事件流（`partial_image_b64` 已截断）：

```
data: {"type":"response.created","response":{"id":"resp_04a3…","status":"in_progress"}}
data: {"type":"response.in_progress","response":{...}}
data: {"type":"response.output_item.added","item":{"id":"ig_04a3…","type":"image_generation_call","status":"in_progress"},"output_index":0,"sequence_number":2}
data: {"type":"response.image_generation_call.in_progress","item_id":"ig_04a3…","output_index":0,"sequence_number":3}
data: {"type":"response.image_generation_call.generating","item_id":"ig_04a3…","output_index":0,"sequence_number":4}
data: {"type":"response.image_generation_call.partial_image","background":"opaque","item_id":"ig_04a3…","output_format":"webp","output_index":0,"partial_image_b64":"iVBORw0KGgo…<460KB>"}
data: {"type":"keepalive","sequence_number":6}
data: {"type":"response.image_generation_call.partial_image","background":"opaque","output_format":"webp","output_index":0,"partial_image_b64":"UklGRpzTAwB…<380KB>"}
data: {"type":"response.output_item.done","item":{"id":"ig_04a3…","type":"image_generation_call","status":"generating","action":"generate","output_format":"webp","quality":"high","revised_prompt":"…","size":"1024x1536"}}
data: {"type":"response.output_item.added","item":{"id":"msg_04a3…","type":"message","role":"assistant","content":[]},"output_index":1}
data: {"type":"response.content_part.added", ...}
data: {"type":"response.output_text.done","text":""}
data: {"type":"response.content_part.done", ...}
data: {"type":"response.output_item.done","item":{"id":"msg_04a3…","type":"message","status":"completed"}}
data: {"type":"response.completed","response":{"id":"resp_04a3…","status":"completed","output":[…]}}
```

要点：

* 图片数据位于 `partial_image` 事件的 `partial_image_b64`；`partial_image_index` 标记第几帧（从 0 起），`output_index` 标记第几张图（多图时用于区分，见 [一次生成多张](#一次生成多张)）。
* 最终图为最后一个 `partial_image`，或 `response.completed` 中 `response.output[].result`。
* `partial_image` 事件附带 `background` 与 `output_format`（实测 `webp` 生效）。

## revised\_prompt

用 Responses 生成图片时，`gpt-6-astra` 会自动优化提示词以提升出图质量，优化后的文本在 `revised_prompt`：

* 流式：`response.output_item.done` 事件的 `item.revised_prompt`
* 非流式：`output[].revised_prompt`

实测：输入 `"Draw a serene winter landscape with a river made entirely of white owl feathers winding through snow-dusted pines..."`，被优化为：

```text
A serene winter landscape in delicate watercolor style: a winding river made entirely of
overlapping white owl feathers flowing through snow-dusted pine trees, under a pale dawn sky
with soft pink and blue washes. Fine ink linework defines the pines, feather barbs, snowy banks,
and distant hills. Peaceful, airy composition, gentle mist, subtle shadows on snow, elegant
natural fantasy illustration.
```

<ImageGrid cols={1} items={[{"src": "/img/gpt-image/owl-feather-river.jpg", "alt": "watercolor-river", "caption": "上述 revised_prompt 生成的实测图（流式，水彩冬日羽毛河）"}]} />

## 多轮编辑与参考图输入

把参考图通过 `input_image` 传进去，即可编辑或参考生成。共三种写法：

写法一，URL（公网可直接下载）：

```json
{ "type": "input_image", "image_url": "https://your-bucket.example.com/photo.jpg" }
```

写法二，base64 data URI：

```python
import base64
b64 = base64.b64encode(open("photo.jpg", "rb").read).decode
part = {"type": "input_image", "image_url": f"data:image/jpeg;base64,{b64}"}
```

写法三，file\_id（经 Files API 上传）：

```python
def create_file(path):
    return client.files.create(file=open(path, "rb"), purpose="vision").id

fid = create_file("photo.jpg")
part = {"type": "input_image", "file_id": fid}
```

注意：用 URL 时，模型服务器会主动去拉这个地址，所以它必须对**上游取图网络**可达。浏览器或 VibeAPI 网关本机能得到 HTTP 200，并不代表模型服务器一定能下载。

参考图 URL 可达性实测：

| 参考图输入                 | 结果          | 耗时 / 现象                                                          |
| --------------------- | ----------- | ---------------------------------------------------------------- |
| 腾讯 COS 公网 URL         | 失败          | 约 20 秒返回 `400 Unable to download content ... before the timeout` |
| 同对象的 EdgeOne CDN URL  | 失败          | 约 20 秒返回相同 `400`                                                 |
| GitHub 公共图片 URL       | 成功          | 约 24 秒完成                                                         |
| 图片内联为 base64 data URI | 通过 URL 下载阶段 | 不再出现下载超时；后续仍可能遇到独立的上游负载错误                                        |

因此，腾讯 COS / EdgeOne CDN、带鉴权或可达性不确定的参考图不要直接传 URL，优先使用 base64 data URI 或 `file_id`。这类 `400` 表示上游取图失败，不能据此判断 COS 对象本身损坏或未公开。

`action` 参数控制生成还是编辑：`auto`（默认，模型自行决定）、`generate`（强制新建）、`edit`（强制编辑，上下文无图则报错）。

蒙版编辑（`input_image_mask`）：原图作为 `input_image`、蒙版作为 `input_image_mask`，蒙版的透明区域会被重绘。

```python
img_id  = create_file("sunlit_lounge.png")
mask_id = create_file("mask.png")   # 透明区即重绘区，须包含 alpha 通道

resp = client.responses.create(
    model="gpt-6-astra",
    input=[{"role": "user", "content": [
        {"type": "input_text",  "text": "在泳池里加一只火烈鸟"},
        {"type": "input_image", "file_id": img_id},
    ]}],
    tools=[{"type": "image_generation", "quality": "high",
            "input_image_mask": {"file_id": mask_id}}],
)
```

参考图编辑实测：

<ImageGrid cols={2} items={[{"src": "/img/gpt-image/product-rebackground.jpg", "alt": "url-edit", "caption": "URL 编辑（中文提示词：换樱花庭院背景）"}, {"src": "/img/gpt-image/ukiyoe-style.jpg", "alt": "base64-edit", "caption": "base64 编辑（英文提示词：转浮世绘风格）"}]} />

### 多轮：把上一轮的图传进下一轮

OpenAI 官方 Responses API 支持用 `previous_response_id` 关联多轮编辑，本网关不支持：传入后流式连接被中断，客户端报 `ChunkedEncodingError: Response ended prematurely`。

替代方案：将上一轮的图片作为 `input_image` 显式传入下一轮，即可实现多轮编辑：

```python
# 第一轮：生成
r1_b64 = generate_and_get_b64("一只灰色虎斑猫抱着戴橙色围巾的水獭，童书插画风格")

# 第二轮：将第一轮的图作为参考图传入，继续编辑
stream = client.responses.create(
    model="gpt-6-astra",
    input=[{"role": "user", "content": [
        {"type": "input_text",  "text": "现在把它变成写实摄影风格，浅景深"},
        {"type": "input_image", "image_url": f"data:image/png;base64,{r1_b64}"},
    ]}],
    tools=[{"type": "image_generation"}],
    stream=True,
)
```

## 一次生成多张

`n` 在 Responses 工具中无效。如需多张，请在提示词中写明「生成 N 张」，模型会多次调用 `image_generation` 工具，每张对应一个递增的 `output_index`。

```python
stream = client.responses.create(
    model="gpt-6-astra",
    instructions="You are a helpful image generation assistant. Generate ALL images the user requests.",
    input="Generate 3 separate images: 1) a solid purple star, 2) a solid blue square, 3) a solid green triangle, each centered on white.",
    tools=[{"type": "image_generation", "quality": "low"}],
    stream=True,
)

finals = {}
for event in stream:
    if event.type == "response.image_generation_call.partial_image":
        finals[event.output_index] = event.partial_image_b64   # 按 output_index 分组
for idx, b64 in finals.items:
    with open(f"out_{idx}.png", "wb") as f:
        f.write(base64.b64decode(b64))
print(f"共 {len(finals)} 张")   # 实测 3 张
```

实测（3 张，事件流中出现 3 个 `image_generation_call`，`output_index` 为 0 / 1 / 2）：

<ImageGrid cols={3} items={[{"src": "/img/gpt-image/geo-star.jpg", "alt": "star", "caption": "output_index 0"}, {"src": "/img/gpt-image/geo-square.jpg", "alt": "square", "caption": "output_index 1"}, {"src": "/img/gpt-image/geo-triangle.jpg", "alt": "triangle", "caption": "output_index 2"}]} />

## Vision 图片理解

`gpt-6-astra` 能理解图片：识别物体、颜色、纹理，也能读出图里的文字。做图片理解只需传 `input_image`、不带 `image_generation` 工具即可。两个入口：

| 入口               | 端点                     | 输出                              |
| ---------------- | ---------------------- | ------------------------------- |
| Responses        | `/v1/responses`        | 文本（`output_text`），可同时生成图片       |
| Chat Completions | `/v1/chat/completions` | 文本（`choices[].message.content`） |

### Responses 方式

```python
resp = client.responses.create(
    model="gpt-6-astra",
    input=[{"role": "user", "content": [
        {"type": "input_text",  "text": "请用中文详细描述这张图片：主要物体、颜色、风格、氛围。"},
        {"type": "input_image", "image_url": "https://your-bucket.example.com/product.png", "detail": "high"},
    ]}],
)
print(resp.output_text)
```

实测输出（护目镜产品图，`detail=high`，节选）：

> 这张图片展示的是一副运动防护眼镜 / 护目镜式眼镜……镜框前部为方形圆角设计，左右两侧带有透明的防护结构……右侧镜片上可见 "YUANMU" 字样。颜色以黑色、透明白、灰色为主……风格偏向产品摄影 / 电商展示图……

模型准确识别了产品类型、结构、配色、镜片上的英文字样与拍摄风格（`usage` 约为输入 930、输出 624 token）。

### Chat Completions 方式

```python
resp = client.chat.completions.create(
    model="gpt-6-astra",
    messages=[{"role": "user", "content": [
        {"type": "text", "text": "Describe this image: main objects, color palette, mood."},
        {"type": "image_url", "image_url": {"url": "https://.../photo.jpg", "detail": "low"}},
    ]}],
)
print(resp.choices[0].message.content)
```

两个入口的图片字段写法不同：Responses 使用 `input_image` 加 `image_url`（字符串）；Chat 使用 `image_url` 加 `image_url.url`（对象）。

### 参考图的三种写法

和生成一样，图片理解也支持 URL、base64、file\_id 三种写法（见 [多轮编辑与参考图输入](#多轮编辑与参考图输入)）。一个请求可包含多张图片（`content` 数组中放置多个 `input_image`）。

### detail 精度参数

| `detail`   | 说明                                                  |
| ---------- | --------------------------------------------------- |
| `low`      | 模型仅接收 512×512 低清版本，速度快、成本低，适用于细节不重要的场景              |
| `high`     | 标准高保真，最多 2500 个图块或 2048px 长边                        |
| `original` | 适用于大图、密集或空间敏感场景（`gpt-5.4` 及以后），最多 10000 个图块或 6000px |
| `auto`     | 自动选择；在 `gpt-6-astra` 上等价于 `original`（不传时也是该行为）      |

### 输入图要求与局限

* 支持格式：PNG、JPEG、WEBP、非动画 GIF
* 限制：单次请求不超过 512MB、最多 1500 张图片；无水印或 logo、无 NSFW 内容、清晰可辨；CAPTCHA 会被系统拦截
* 已知局限：对非拉丁文字（如日文、韩文）的理解可能不佳；小字、旋转或倒置、精确空间定位、物体计数等场景容易出错；不适用于医学影像判读

## 多语言文字渲染

`gpt-image-2` 的一项突出能力是在图片中渲染多语言文字（中、英、日、韩等），错字率低，而这正是许多其它图像模型的短板。

下例用一条提示词要求四种语言同框，并明确列出每种语言的确切文字：

```text
A festive vertical New Year greeting poster. Render the SAME greeting in four languages
on four separate, clearly legible lines:
Chinese '新年快乐', English 'Happy New Year',
Japanese 'あけましておめでとう', Korean '새해 복 많이 받으세요'.
Warm red and gold palette, hanging paper lanterns, gold foil accents, elegant typography.
```

两条路径均成功，四种语言的文字全部正确无误：

<ImageGrid cols={2} items={[{"src": "/img/gpt-image/newyear-poster-stream.jpg", "alt": "poster-stream", "caption": "Responses 流式（gpt-6-astra）"}, {"src": "/img/gpt-image/newyear-poster-sync.jpg", "alt": "poster-sync", "caption": "Image 同步（gpt-image-2）"}]} />

提示词建议：

* 逐语言写出确切文字并用引号括住（如 `Chinese '新年快乐'`），避免让模型自行翻译
* 加入 `clearly legible` 或 `separate lines` 等要求，提升可读性与排版
* 文字不宜过多过密，大段文字或极小字号仍可能出错

## 错误处理

| 状态 / code                                               | 场景                        | 应对                                                   |
| ------------------------------------------------------- | ------------------------- | ---------------------------------------------------- |
| `400 Unable to download content ... before the timeout` | 上游无法下载参考图 URL             | 改用 base64 data URI 或 `file_id`；不要只以本机 HTTP 200 判断可达性 |
| `ChunkedEncodingError` / 连接中断                           | 传了 `previous_response_id` | 改用「带图进入下一轮」                                          |
| `moderation_blocked`                                    | 提示词或图片被内容审核拦截             | 修改提示词或输入图后重试                                         |
| `429`                                                   | 触发限流                      | 指数退避后重试                                              |
| `401` / `403`                                           | 鉴权失败或无模型权限                | 检查 `API_KEY` 与 `gpt-6-astra` 权限                      |

### 内容审核拦截（moderation\_blocked）

所有提示词与生成图片都会经过内容审核。被拦截时返回如下结构（可能包含 `moderation_details`）：

```json
{
  "error": {
    "type": "image_generation_user_error",
    "code": "moderation_blocked",
    "moderation_details": {
      "moderation_stage": "input",
      "categories": ["harassment"]
    }
  }
}
```

* `moderation_stage`：`input`（提示词或输入图被拦）、`output`（生成图被拦）、`unknown`
* `categories`：粗粒度标签，例如 `harassment`、`self-harm`、`sexual`、`violence`
* 可通过 `moderation:"low"`（见 [image\_generation 工具参数](#image_generation-工具参数) / [输出定制](https://docs.vibeapi.cn/zh/docs/images#输出定制)）放宽审核

```python
import openai
try:
    client.images.generate(model="gpt-image-2", prompt="...")
except openai.BadRequestError as e:
    if e.code == "moderation_blocked":
        details = (e.body or {}).get("moderation_details", {})
        print("拦截阶段:", details.get("moderation_stage"), "类别:", details.get("categories"))
        # 提示用户修改后重试；此类用户错误不应自动重试
    else:
        raise
```

### 重试策略

* 可重试：`429`、`5xx`（瞬时故障），建议指数退避
* 不可重试：`moderation_blocked` 等用户错误，必须修改提示词或输入后再发，重复发送无意义

## 与 OpenAI 官方的差异

| 能力                                   | OpenAI 官方       | 本网关                                    |     |
| ------------------------------------ | --------------- | -------------------------------------- | :-: |
| 流式 / 非流式生成                           | 支持              | 事件序列完整                                 |  √  |
| 多图（提示词触发）                            | 支持              | 返回多个 `image_generation_call`           |  √  |
| 参考图编辑（base64 / `file_id`）            | 支持              | 成功                                     |  √  |
| 参考图编辑（URL）                           | 支持公网 URL        | GitHub 等直链成功；腾讯 COS / EdgeOne URL 下载超时 |  ✗  |
| `revised_prompt`                     | 有               | 一致返回                                   |  √  |
| 工具 `output_format`                   | 遵循              | `webp` 生效                              |  √  |
| `size` / `quality`                   | 视为约束            | 被改写，要 4K/high 实得 1536×1024/medium      |  ✗  |
| 指定图像模型                               | 工具 `model` 字段   | 被忽略，不存在的模型名照样出图                        |  ✗  |
| `previous_response_id`               | 支持              | 不支持，连接中断                               |  ✗  |
| Vision 理解（Responses + Chat，`detail`） | 支持              | 成功                                     |  √  |
| `background:transparent`             | gpt-image-2 不支持 | 忽略并输出不透明                               |  √  |

## 参数速查

```
type*               "image_generation"
quality             low | medium | high | auto     （本网关会改写，以响应为准）
size                1024x1024 | 1536x1024 | 1024x1536 | … | auto （同上）
output_format       png | jpeg | webp
output_compression  0–100                          （jpeg / webp）
moderation          auto | low
action              auto | generate | edit
partial_images      0–3
input_image_mask    { "file_id": "..." }
```

## 在线调试

填入你自己的 API Key 即可直接发起请求，参数表与响应结构由接口定义生成。

模型填 `gpt-6-astra`，`tools` 里加 `{"type": "image_generation"}`。

<APIPage document={"openapi/generated/ai-model/聊天（Chat）/原生OpenAI格式/post-v1-responses-createresponse-383826475.json"} operations={[{"path":"/v1/responses","method":"post"}]} />

## 官方文档

* [OpenAI · 图像生成](https://developers.openai.com/api/docs/guides/image-generation)
* [OpenAI · Responses](https://developers.openai.com/api/reference/resources/responses/methods/create)


# GPT 图像 · Image API

`POST /v1/images/generations` · `POST /v1/images/edits`

GPT 图像有两套入口，**这一套是默认入口**：直接指定图像模型一次性生成或编辑，`size` / `quality` 按请求执行，
4K + `high` 约 1–2 分钟返回。另一套是 [Responses](https://docs.vibeapi.cn/zh/docs/images-responses)——`gpt-6-astra` 调度 `image_generation` 工具做对话式多轮编辑，
但它拿不到高分辨率与高质量档位，只在需要多轮对话时使用。

协议与 OpenAI Image API 兼容，`openai` SDK 把 `base_url` 换成 `https://www.vibeapi.cn/v1` 即可。
本页结论来自对本网关的真实调用，最后验证 2026-10-13（实测记录小节标注各自的日期）。

## 基本调用

<Tabs items={['curl', 'Python', 'Node.js']}>
  <Tab value="curl">
    ```bash
    curl -X POST "https://www.vibeapi.cn/v1/images/generations" \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "gpt-image-2",
        "prompt": "a red apple on a wooden table, studio lighting",
        "quality": "medium",
        "size": "1024x1024",
        "response_format": "b64_json"
      }'
    ```
  </Tab>

  <Tab value="Python">
    ```python
    from openai import OpenAI
    import base64, urllib.request

    client = OpenAI(base_url="https://www.vibeapi.cn/v1", api_key="YOUR_API_KEY")

    result = client.images.generate(
        model="gpt-image-2",
        prompt="a red apple on a wooden table, studio lighting",
        quality="medium",
        size="1024x1024",
    )

    item = result.data[0]
    if item.b64_json:
        image_bytes = base64.b64decode(item.b64_json)
    else:
        image_bytes = urllib.request.urlopen(item.url, timeout=60).read()
    open("apple.png", "wb").write(image_bytes)
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    import OpenAI from "openai";
    import fs from "fs";

    const client = new OpenAI({ baseURL: "https://www.vibeapi.cn/v1", apiKey: "YOUR_API_KEY" });

    const result = await client.images.generate({
      model: "gpt-image-2",
      prompt: "a red apple on a wooden table, studio lighting",
      quality: "medium",
      size: "1024x1024",
    });

    const item = result.data[0];
    const imageBytes = item.b64_json
      ? Buffer.from(item.b64_json, "base64")
      : Buffer.from(await (await fetch(item.url)).arrayBuffer());
    ```
  </Tab>
</Tabs>

## 网关上的图像模型

图像生成分散在三个端点上，先确认你要的模型走哪一个：

| 模型                                                                                            | 端点                                            | 文档                                    |
| --------------------------------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------- |
| `gpt-image-2` · `gpt-image-2.5-flare` · `gpt-image-2.5-sunburst`                              | `/v1/images/generations` · `/v1/images/edits` | 本页                                    |
| `gemini-3-pro-image` · `gemini-3.1-flash-image` · `gemini-3.1-flash-lite-image`（含 `-preview`） | `/v1beta/models/{model}:generateContent`      | [Gemini 图像生成](https://docs.vibeapi.cn/zh/docs/gemini-images) |
| `grok-imagine-image-2.0` · `grok-imagine-image-quality`                                       | `/v1/images/generations` · `/v1/images/edits` | [Grok 图像](https://docs.vibeapi.cn/zh/docs/grok-images)       |
| `wan3.0-image-*`                                                                              | `/v1/videos`（图生视频，不是出图）                       | [视频生成](https://docs.vibeapi.cn/zh/docs/videos)               |

Gemini 的生图必须走原生端点：走 Chat 兼容协议能出图，但 `imageConfig`（画幅、分辨率）会在协议转换中丢掉。
`wan3.0-image-*` 名字里带 image，指的是「图生视频」，它走视频接口。

## 三个 GPT 图像模型怎么选

`gpt-image-2`、`gpt-image-2.5-flare`、`gpt-image-2.5-sunburst` 的请求与响应格式完全相同，换 `model` 即可。
`gpt-image-2.5-1k` 已下线，代码里还有这个模型名的请换成 flare 或 sunburst。三者的差别（2.5 系列 2026-09-23 实测）：

|                             | `gpt-image-2`         | `gpt-image-2.5-flare`         | `gpt-image-2.5-sunburst` |
| --------------------------- | --------------------- | ----------------------------- | ------------------------ |
| `n`                         | 固定 1 张，按 1 张计费；要多张请并发 | **生效**，`n=2` 返回 2 张，按实际返回张数计费 | 同 flare                  |
| `background: "transparent"` | 不支持，忽略该参数，输出不透明图      | **生效**，PNG 带 alpha 通道         | 同 flare                  |
| 4K（`3840x2160`）+ `high` 耗时  | 约 1–2 分钟              | 约 40 秒                        | 约 40–55 秒                |
| `1024x1024` + `low` 耗时      | 约 20–50 秒             | 约 15–20 秒                     | 约 15–20 秒                |
| 计费                          | 按张                    | 按张，单价高于 `gpt-image-2`         | 与 flare 同价               |

本网关通过多种渠道提供 GPT 图像。张数、尺寸校验、透明背景、响应字段和错误格式由网关统一，与本页一致；
耗时和 `usage` 里的 token 数会随调度到的渠道不同而变化，计费按张，与 `usage` 无关。
响应顶层的 `quality` 是实际执行的档位，个别情况下可能低于请求的档位（例如请求 `high` 返回 `medium`），以响应为准。

三个模型都按请求的 `size` 精确返回（2.5 实测 `1024x1024`、`1024x1536`、`3840x2160`），`quality` 按档回显，
edits（multipart 参考图）同样可用，`low` 档约 18–25 秒。本轮 2.5 的 `data[0]` 都是 `url`，仍要按下文同时处理两种形态。
单价以[价格页](https://www.vibeapi.cn/pricing)为准。画质与文字渲染三者之间还没有做系统对比，同一提示词的样图见[实测](#实测gpt-image-25)。

要透明背景或一次多张，选 2.5；要和已有 `gpt-image-2` 产物保持一致，留在 2；2.5 两个里 flare 在这一轮更快。

## 与 Responses 怎么选

|                    | Image API（本页）                                 | Responses                               |
| ------------------ | --------------------------------------------- | --------------------------------------- |
| 端点                 | `/v1/images/generations`、`/v1/images/edits`   | `/v1/responses` + `image_generation` 工具 |
| 调用模型               | `gpt-image-2` / `gpt-image-2.5-*`，直接指定        | `gpt-6-astra`，内部调度图像模型，无法指定             |
| `size` / `quality` | 按请求执行，4K + high 精确返回                          | 被改写：要 4K/high 实得 1536×1024/medium       |
| 耗时                 | 4K + high 约 45–57 秒                           | 40–170 秒                                |
| 提示词优化              | 无                                             | 自动，返回 `revised_prompt`                  |
| 多轮编辑               | 不支持，每次独立                                      | 支持，上下文携带图片                              |
| 参考图                | multipart 文件上传                                | URL / base64 / `file_id`                |
| 返回                 | `data[0].b64_json` **或** `data[0].url`，两种都要处理 | SSE 事件里的 base64                         |

要高分辨率、高画质、准确尺寸，用本页；要对话式多轮，用 Responses。

## generations

全部请求字段：

| 字段                          | 类型      | 必填 | 默认       | 说明                                                                                     |
| --------------------------- | ------- | -- | -------- | -------------------------------------------------------------------------------------- |
| `model`                     | string  | 是  | —        | `gpt-image-2` / `gpt-image-2.5-flare` / `gpt-image-2.5-sunburst`                       |
| `prompt`                    | string  | 是  | —        | 图片描述文本                                                                                 |
| `size`                      | string  | 否  | `auto`   | 见[输出定制](#输出定制)；`3840x2160` / `2160x3840` 精确返回；不合规返回 400                                |
| `quality`                   | string  | 否  | `auto`   | `low` / `medium` / `high` / `auto`，按档执行                                                |
| `output_format`             | string  | 否  | `png`    | `png` / `jpeg` / `webp`；以响应顶层字段和文件 MIME 为准                                             |
| `output_compression`        | integer | 否  | —        | `0`–`100`，仅 `jpeg` / `webp`                                                            |
| `response_format`           | string  | 否  | —        | `b64_json` / `url`；**不决定响应形态**，见下文                                                     |
| `moderation`                | string  | 否  | `auto`   | `auto` / `low`                                                                         |
| `background`                | string  | 否  | `opaque` | `opaque` / `auto` / `transparent`；`transparent` 只有 2.5 系列生效，`gpt-image-2` 忽略该参数、输出不透明图 |
| `n`                         | integer | 否  | `1`      | 2.5 系列生效、按实际返回张数计费；`gpt-image-2` 固定 1 张，多张请并发                                          |
| `stream` / `partial_images` | —       | 否  | —        | 不要依赖；同步调用即可                                                                            |

### 响应有两种形态

同一个端点，`data[0]` 里可能是 `b64_json`（内联 base64），也可能是 `url`（临时下载链接，有时效，拿到后尽快下载）。
`response_format` 传了也不保证——generations 传 `b64_json` 通常拿到内联数据，edits 传相同值仍可能返回 `url`。**生产代码必须两种都处理：**

```python
import base64, urllib.request

item = result.data[0]
data = (base64.b64decode(item.b64_json) if item.b64_json
        else urllib.request.urlopen(item.url, timeout=60).read())
open(f"out.{result.output_format or 'png'}", "wb").write(data)
```

```bash
if jq -e '.data[0].b64_json' response.json >/dev/null; then
  jq -r '.data[0].b64_json' response.json | base64 --decode > out.png
else
  curl -L "$(jq -r '.data[0].url' response.json)" -o out.png
fi
```

响应顶层一定带 `size` / `quality` / `output_format`，它们是实际值，请读它们并校验下载后文件的真实 MIME：

```json
{
  "created": 1789190861,
  "data": [{ "url": "https://..." }],
  "output_format": "png",
  "quality": "high",
  "size": "3840x2160",
  "model": "gpt-image-2",
  "usage": { "input_tokens": 234, "output_tokens": 13342, "total_tokens": 13576 }
}
```

## edits

```
POST /v1/images/edits      （multipart/form-data）
```

两类场景：用一张或多张参考图生成新图；配合蒙版重绘指定区域。表单字段与 generations 相同，另加：

| 字段        | 类型       | 说明                                        |
| --------- | -------- | ----------------------------------------- |
| `image[]` | file，可多个 | 参考图。多张时重复 `image[]`                       |
| `mask`    | file     | 蒙版，可选。须含 alpha 通道，透明区即重绘区，与原图同尺寸、不超过 50MB |

多参考图：

```python
result = client.images.edit(
    model="gpt-image-2",
    image=[open("ref1.png", "rb"), open("ref2.jpg", "rb"), open("ref3.jpg", "rb")],
    prompt="Combine the subjects into a single flat-lay collage on white marble, studio lighting",
    quality="medium",
)
```

```bash
curl -X POST "https://www.vibeapi.cn/v1/images/edits" \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=gpt-image-2" \
  -F "image[]=@ref1.png" -F "image[]=@ref2.jpg" -F "image[]=@ref3.jpg" \
  -F "prompt=Combine the subjects into a single flat-lay collage on white marble" \
  -F "quality=high" -F "size=3840x2160" > response.json
```

蒙版编辑：

```python
result = client.images.edit(
    model="gpt-image-2",
    image=open("base.png", "rb"),
    mask=open("mask.png", "rb"),       # 透明区即要重绘的区域
    prompt="In the masked area, add a blooming cherry blossom tree",
    quality="low",
)
```

多张参考图时蒙版作用于第一张。蒙版是提示性的：模型以它为引导，不保证严格贴合形状。
edits 对整体风格和构图的保持很强，对局部小对象的加入偏保守——要求「加两只鹤」这类小元素可能不出现，先用自己的图试一次。

<ImageGrid cols={2} items={[{"src": "/img/gpt-image/product-collage.jpg", "alt": "collage", "caption": "多参考图合成"}, {"src": "/img/gpt-image/mask-cherry.jpg", "alt": "mask-edit", "caption": "蒙版编辑（中心区域重绘为樱花树）"}]} />

## 输出定制

**`size`** 官方约束：最大边不超过 `3840px`，两边均为 `16` 的倍数；长短边比不超过 `3:1`；总像素在 `655,360` \~ `8,294,400` 之间。
常用 `1024x1024`、`1536x1024`、`1024x1536`、`2048x2048`、`3840x2160`、`2160x3840`、`auto`。
`3840x2160` 与 `2160x3840` 均精确返回；仍建议读响应顶层的 `size` 做校验。
不符合上述规则的尺寸直接返回 400（`code` 为 `invalid_request`，消息里说明不满足哪一条，例如 `invalid size "4096x4096": the longer side must be at most 3840`），不会被改成别的尺寸出图。

**`quality`** `low` / `medium` / `high` / `auto`。以响应顶层的 `quality` 为准；`usage.output_tokens` 随渠道不同而不同，不要用它判断档位。

**`output_format`** `png` / `jpeg` / `webp`，配合 `output_compression`（`0`–`100`，仅 jpeg / webp）。始终以响应顶层 `output_format` 和下载文件的 MIME 为准。

**`background`** `gpt-image-2` 不支持透明背景，传 `transparent` 时网关会去掉这个参数、照常输出不透明图片（不报错）；2.5 系列会返回带 alpha 通道的 PNG
（下图用棋盘格垫底显示透明区域）：

<ImageGrid cols={3} items={[{"src": "/img/gpt-image/mountain-logo.jpg", "alt": "gpt-image-2 logo", "caption": "gpt-image-2：请求 transparent，实得不透明白底（无 alpha）"}, {"src": "/img/gpt-image/logo-transparent-2.5-flare.jpg", "alt": "flare logo", "caption": "gpt-image-2.5-flare：透明背景生效"}, {"src": "/img/gpt-image/logo-transparent-2.5-sunburst.jpg", "alt": "sunburst logo", "caption": "gpt-image-2.5-sunburst：透明背景生效"}]} />

**`n`** 2.5 系列生效，`n=2` 返回两张、按实际返回张数计费。`gpt-image-2` 固定 1 张，传多少都按 1 张执行和计费：多张请并发多次调用，
或用 [Responses](https://docs.vibeapi.cn/zh/docs/images-responses#一次生成多张) 在提示词里要求多张。

## 实测：4K 最高画质

以下是 2026-09-12 的实测记录，耗时与 `output_tokens` 会随调度到的渠道变化。`quality=high`，`size` 取官方上限 `3840x2160` / `2160x3840`，六个主题并发 6 路：

| 主题    | 请求 size     | 耗时     | 实返 size / quality    | `data[0]` | `output_tokens` |
| ----- | ----------- | ------ | -------------------- | --------- | --------------- |
| 东方水墨  | `3840x2160` | 52.0 s | `3840x2160` / `high` | `url`     | 13,342          |
| 仙侠    | `2160x3840` | 56.7 s | `2160x3840` / `high` | `url`     | 13,342          |
| 工笔重彩  | `3840x2160` | 54.1 s | `3840x2160` / `high` | `url`     | 13,342          |
| 环形空间站 | `2160x3840` | 47.6 s | `2160x3840` / `high` | `url`     | 13,342          |
| 巨构城市  | `3840x2160` | 54.1 s | `3840x2160` / `high` | `url`     | 13,342          |
| 戴森云   | `2160x3840` | 45.2 s | `2160x3840` / `high` | `url`     | 13,342          |

六张全部按请求尺寸返回真实 4K PNG（9–17 MB），无一超时。

<ImageGrid cols={3} ratio="1 / 1" items={[{"src": "/img/gpt-image/ink-mountains-4k.jpg", "alt": "东方水墨 · 3840×2160 · high · 52 s", "caption": "东方水墨 · 3840×2160 · high · 52 s"}, {"src": "/img/gpt-image/xianxia-sword-4k.jpg", "alt": "仙侠 · 2160×3840 · high · 57 s", "caption": "仙侠 · 2160×3840 · high · 57 s"}, {"src": "/img/gpt-image/guofeng-palace-4k.jpg", "alt": "工笔重彩 · 3840×2160 · high · 54 s", "caption": "工笔重彩 · 3840×2160 · high · 54 s"}, {"src": "/img/gpt-image/space-station-4k.jpg", "alt": "环形空间站 · 2160×3840 · high · 48 s", "caption": "环形空间站 · 2160×3840 · high · 48 s"}, {"src": "/img/gpt-image/megastructure-city-4k.jpg", "alt": "巨构城市 · 3840×2160 · high · 54 s", "caption": "巨构城市 · 3840×2160 · high · 54 s"}, {"src": "/img/gpt-image/dyson-swarm-4k.jpg", "alt": "戴森云 · 2160×3840 · high · 45 s", "caption": "戴森云 · 2160×3840 · high · 45 s"}]} />

同一批用 `edits` 做参考图编辑（把水墨图缩到 1920×1080 作为 `image[]`，`size=3840x2160`、`quality=high`）：50 秒返回精确 4K，构图与笔触完全保留。

<ImageGrid cols={2} items={[{"src": "/img/gpt-image/ink-mountains-4k.jpg", "alt": "原图（generations）", "caption": "原图（generations）"}, {"src": "/img/gpt-image/ink-mountains-edit-4k.jpg", "alt": "edits · 3840×2160 · high · 50 s", "caption": "edits · 3840×2160 · high · 50 s"}]} />

其他尺寸与质量档的耗时：`low` 小图约 20–25 秒，`medium` 1K 约 80–140 秒，参考图编辑约 50–100 秒。质量越高、图片越大，耗时越长。

<ImageGrid cols={2} items={[{"src": "/img/gpt-image/cyberpunk-city.jpg", "alt": "cyberpunk", "caption": "文本生成（quality=low，size=1536x1024，同步约 113 秒）"}, {"src": "/img/gpt-image/robot-turnaround.jpg", "alt": "robot", "caption": "n=2 请求（实际仅返回 1 张，见 §4.4）"}]} />

## 实测：gpt-image-2.5

以下是 2026-09-23 的实测记录。同一个水墨提示词，`size=3840x2160`、`quality=high`，两个模型各一张：

| 模型                       | 耗时     | 实返 size / quality    | `data[0]` | `output_tokens` | 文件          |
| ------------------------ | ------ | -------------------- | --------- | --------------- | ----------- |
| `gpt-image-2.5-flare`    | 38.4 s | `3840x2160` / `high` | `url`     | 3,336           | PNG 14.6 MB |
| `gpt-image-2.5-sunburst` | 54.2 s | `3840x2160` / `high` | `url`     | 3,336           | PNG 13.1 MB |

<ImageGrid cols={2} items={[{"src": "/img/gpt-image/ink-mountains-2.5-flare-4k.jpg", "alt": "flare 4K", "caption": "gpt-image-2.5-flare · 3840×2160 · high · 38 s"}, {"src": "/img/gpt-image/ink-mountains-2.5-sunburst-4k.jpg", "alt": "sunburst 4K", "caption": "gpt-image-2.5-sunburst · 3840×2160 · high · 54 s"}]} />

## 错误处理

| 状态 / code                    | 场景                          | 应对                        |
| ---------------------------- | --------------------------- | ------------------------- |
| `400` · `moderation_blocked` | 提示词或图片被内容审核拦截（各渠道统一为这个错误码）  | 修改提示词或输入图后重试；不要自动重试       |
| `400` · `invalid_request`    | `size` 不符合[输出定制](#输出定制)里的规则 | 按规则改尺寸                    |
| `504`                        | 同步渲染超时，极少见                  | 重试或降一档 `quality`          |
| `429`                        | 触发限流                        | 指数退避后重试                   |
| `401` / `403`                | 鉴权失败或无模型权限                  | 检查 `API_KEY` 与所用图像模型的分组权限 |

审核拦截的响应结构与处理代码见 [Responses 页](https://docs.vibeapi.cn/zh/docs/images-responses#内容审核拦截moderation_blocked)，两套入口相同。

## 参数速查

```
model*          gpt-image-2 | gpt-image-2.5-flare | gpt-image-2.5-sunburst
prompt*         文本描述
size            1024x1024 | 1536x1024 | 1024x1536 | 2048x2048 | 3840x2160 | 2160x3840 | auto （须符合输出定制里的规则，否则 400）
quality         low | medium | high | auto
output_format   png | jpeg | webp
output_compression  0–100                （jpeg / webp）
response_format b64_json | url            （不决定响应形态，两种都要处理）
moderation      auto | low
background      opaque | auto | transparent （transparent 仅 2.5 生效；gpt-image-2 忽略）
n               2.5 生效、按实际张数计费；gpt-image-2 固定 1 张
image[]         edits：一张或多张参考图（multipart）
mask            edits：alpha 蒙版，透明区即重绘区
```

## 在线调试

填入你自己的 API Key 即可直接发起请求，参数表与响应结构由接口定义生成。

### 生成图像（OpenAI 格式）

<APIPage document={"openapi/generated/ai-model/图像（Images）/原生OpenAI格式/post-v1-images-generations-post-v1-images-generations-385320132.json"} operations={[{"path":"/v1/images/generations/","method":"post"}]} />

### 编辑图像（OpenAI 格式）

<APIPage document={"openapi/generated/ai-model/图像（Images）/原生OpenAI格式/post-v1-images-edits-post-v1-images-edits-385320133.json"} operations={[{"path":"/v1/images/edits/","method":"post"}]} />

## 官方文档

* [OpenAI · 图像生成](https://developers.openai.com/api/docs/guides/image-generation)


# 文档

import { Card, Cards } from 'fumadocs-ui/components/card';

<HeroVideo src="https://studio.vibevibe.cn/docs/260915/docs-intro/video/home.mp4" poster="https://studio.vibevibe.cn/docs/260915/docs-intro/poster/home.webp" model="doubao-seedance-2-5-260628" />

网关地址 `https://www.vibeapi.cn/v1`，所有请求带 `Authorization: Bearer <API_KEY>`。一把 key 可调用 GPT、Claude、Gemini、Grok 与国产模型。

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/quickstart" title="快速开始" description="拿 key、装 SDK、发出第一个请求；把文档装进 Claude Code。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/coding-tools" title="编码工具（VibeCLI）" description="一条命令把 key 和模型配进 Claude Code、Codex、Claude Desktop 等工具；国内一键安装这些工具。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/models" title="模型与入口" description="每个模型该走哪个端点、要不要流式、哪些是网关转换出来的。" />
</Cards>

## 先读这一条

请求超时上限 **120 秒**。非流式请求在生成完成前没有任何数据下行，单次生成一旦超过这个时间，连接会被中断。
短输出不受影响；长输出与推理型模型容易触发。**生产环境建议默认开启流式**，这是本网关最常见的报错原因。

## 文本对话

按模型家族选它的原生协议，功能最全；跨协议调用是网关翻译的，只保证消息、流式和基本工具调用。总览见[文本对话概览](https://docs.vibeapi.cn/zh/docs/text)。

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/responses" title="OpenAI Responses" description="GPT 系推荐入口。多轮状态、推理摘要、内置工具、提示缓存。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/chat" title="OpenAI Chat Completions" description="兼容面最广。国产模型与大多数三方框架从这里接入。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/messages" title="Claude Messages" description="Claude 家族原生入口，唯一能完整拿到 thinking 块的路径；两类 key 的差异。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/gemini" title="Gemini generateContent" description="Gemini 原生协议，唯一能用 thinkingConfig 控制思考、用 imageConfig 定生图画幅与分辨率的路径。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/grok" title="Grok 对话" description="grok-4.7 / 4.6 的参数差异：stop / penalty / n 返回 200 但不生效，推理不可关闭。" />
</Cards>

## 图像生成

哪个模型走哪个端点、GPT 两套入口怎么选，见[图像生成概览](https://docs.vibeapi.cn/zh/docs/images-overview)。

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/images" title="GPT 图像 · Image API" description="默认入口。gpt-image-2 / 2.5 直接生成与编辑，4K + high 按请求精确返回。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/images-responses" title="GPT 图像 · Responses" description="对话式多轮编辑、自动 revised_prompt；分辨率与质量档会被改写。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/gemini-images" title="Gemini 图像生成" description="原生 generateContent 生图，14 种画幅、512px–4K 档位、编辑与多轮。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/grok-images" title="Grok 图像" description="grok-imagine-image-2.0 文生图与图生图，画幅固定 1248×832。" />
</Cards>

## 视频生成

异步接口：提交拿到 `task_id`，轮询到 `completed`，再取片；不受 120 秒约束。

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/videos" title="视频生成概览" description="三个接口、三个系列的计费口径、轮询与取片、错误与退款。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/videos-wan" title="万相 3.0" description="分辨率写在模型名里，首尾帧与参考视频，按秒计费。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/videos-seedance" title="Seedance" description="字节官方四个型号，最长 30 秒、到 1080p，图 / 视频 / 音频参考与首尾帧；按 token 计费。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/videos-minimax" title="MiniMax H3" description="图 / 视频 / 音频三类参考素材同时给，768P。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/grok-videos" title="Grok 视频" description="按秒计费，视频编辑与延长走 grok-imagine-video。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/videos-workflow" title="视频生成工作流" description="先出 4K 参考图再喂视频模型，首尾帧无缝循环。" />
</Cards>

## 其他

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/coding-tools/claude-code" title="在 Claude Code 里用 Grok" description="VibeCLI 一条命令，Claude Code 的 /model 里直接选 Grok。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api" title="账户接口" description="令牌、用量、日志、充值等用户可调用的管理接口，可在线调试。" />
</Cards>

## 不想写代码？直接用产品

同一套模型与网关，做成了两个开箱即用的应用，用 VibeAPI 账号登录即可：

<Cards>
  <Card href="https://hub.vibeapi.cn/" title="VibeHub · 在线聊天、生图、生视频" description="GPT / Claude / Gemini / Grok 对话，gpt-image 生图，wan3.0 / Seedance / MiniMax H3 / Grok 生视频，参考图、参考视频、参考音频都能直接上传。" />

  <Card href="https://www.vibeoa.com/" title="VibePPT · AI 做演示文稿" description="输入主题或大纲，AI 出结构、写内容、配图，导出 PPTX。" />
</Cards>

## 这份文档怎么写

* **官方 SDK，只换 base URL。** 参数名、类型与语义对齐三家官方参考，每个参数先给官方定义，再以「网关」标注本网关的实测行为。
* **写的都是实测。** 参数逐项标注「支持 / 接受 / 实测不生效 / 无效」，每个端点附真实抓取并脱敏的请求与响应，样图和样片都是真实调用产出。
* **返回 200 不等于参数生效。** 网关会为部分模型改写参数，`auto` 类 key 上的 Claude 会静默忽略一批约束；各页的「参数改写规则」「分组差异」写明了判断方法。


# Claude Messages

<HeroVideo src="https://studio.vibevibe.cn/docs/260915/docs-intro/video/messages.mp4" poster="https://studio.vibevibe.cn/docs/260915/docs-intro/poster/messages.webp" model="doubao-seedance-2-5-260628" />

`POST /v1/messages`

Claude 系模型的原生协议。**Claude 模型请优先用这个端点**——它是唯一能完整拿到
thinking 块的路径。从 [Chat Completions](https://docs.vibeapi.cn/zh/docs/chat) 调 Claude 也能通，但那是网关做的
协议转换，thinking 会在转换中丢失，工具调用只保核心字段。

网关上还有一批国产模型也走这个端点接入（glm、kimi、qwen、deepseek 等），
具体见[模型与入口](https://docs.vibeapi.cn/zh/docs/models)。

## 基本调用

**建议用官方 SDK 而不是自己拼 HTTP**——SSE 解析、工具参数分片拼接、超时与重试都由它处理，能避开大部分常见问题。安装与环境变量配置见[快速开始](https://docs.vibeapi.cn/zh/docs/quickstart)。

<Tabs items={['curl', 'Python', 'Node.js']}>
  <Tab value="curl">
    ```bash
    curl -N -X POST "https://www.vibeapi.cn/v1/messages" \
      -H "Authorization: Bearer $API_KEY" \
      -H "anthropic-version: 2023-06-01" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "claude-opus-5",
        "max_tokens": 1024,
        "system": "你是一个简洁的助手。",
        "messages": [
          {"role": "user", "content": "用一句话解释什么是幂等。"}
        ],
        "stream": true
      }'
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import anthropic

    client = anthropic.Anthropic(
        base_url="https://www.vibeapi.cn",
        api_key="YOUR_API_KEY",
    )

    with client.messages.stream(
        model="claude-opus-5",
        max_tokens=1024,
        system="你是一个简洁的助手。",
        messages=[{"role": "user", "content": "用一句话解释什么是幂等。"}],
    ) as stream:
        for text in stream.text_stream:
            print(text, end="", flush=True)
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    import Anthropic from "@anthropic-ai/sdk";

    const client = new Anthropic({
      baseURL: "https://www.vibeapi.cn",
      apiKey: "YOUR_API_KEY",
    });

    const stream = await client.messages.create({
      model: "claude-opus-5",
      max_tokens: 1024,
      system: "你是一个简洁的助手。",
      messages: [{ role: "user", content: "用一句话解释什么是幂等。" }],
      stream: true,
    });

    for await (const event of stream) {
      if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
        process.stdout.write(event.delta.text);
      }
    }
    ```
  </Tab>
</Tabs>

## 认证

```
Authorization: Bearer <API_KEY>
anthropic-version: 2023-06-01
Content-Type: application/json
```

`base_url` 是 `https://www.vibeapi.cn`——注意 Messages 的完整路径是 `/v1/messages`，
Anthropic 官方 SDK 填 base URL 时通常**不带** `/v1`。

## 流式要求

请求超时上限 **120 秒**。非流式请求在生成完成前没有数据下行，单次生成超过这个时间会被
中断。短输出不受影响；推理型号要等整段思考结束才返回首字节，容易触发上限。

官方 SDK 也有同类保护：`max_tokens` 给得很大时会要求走流式，以避免 HTTP 超时。
**建议默认开启流式**，需要完整文本时在客户端拼接 `text_delta`。

## 与 Chat 的差异

以下三处差异较大：

**`max_tokens` 是必填的**，不像 Chat 可以省略。忘了带直接 400。

**系统提示是顶层的 `system` 字段**，不是 `messages` 里的一个角色。`messages` 只放
`user` 和 `assistant`，而且需要交替出现。

**响应是内容块数组，不是一个字符串。** `content` 里每项有自己的 `type`——`text`、
`thinking`、`tool_use` 各是一种块。取正文要过滤 `type == "text"`。

|      | Chat Completions                 | Messages            |
| ---- | -------------------------------- | ------------------- |
| 系统提示 | `messages` 里的 `system` 角色        | 顶层 `system` 字段      |
| 输出上限 | `max_completion_tokens`，可省略      | `max_tokens`，**必填** |
| 产出位置 | `choices[0].message.content` 字符串 | `content` 内容块数组     |
| 结束原因 | `finish_reason`                  | `stop_reason`       |
| 停止序列 | `stop`                           | `stop_sequences`    |

## 请求参数

参数名、类型与语义对齐 [Anthropic Messages API](https://platform.claude.com/docs/en/api/messages)。每个参数先给官方定义，再以「网关」标注本网关的实测行为；
标了「分组敏感」的参数在 `auto` 类 key 上会被静默忽略（返回 200，不报错），详见[分组差异](#分组差异)。

### 必填

<Fields>
  <Field name="model" type="string" required>
    为提示词补全的模型。可用模型见[模型与入口](https://docs.vibeapi.cn/zh/docs/models)。
  </Field>

  <Field name="max_tokens" type="integer" required>
    停止生成前允许产出的最大 token 数。模型可能在达到上限之前就停止，该参数只规定绝对上限；不同模型的最大取值不同。
    设为 `0` 可只预热[提示缓存](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#pre-warming-the-cache)而不生成。
    思考模型的思考预算计入这个上限。

    **网关 · 分组敏感，影响费用。** 官方满血 key 精确执行（要 16 就返回 16，`stop_reason` 为 `max_tokens`）；
    `auto` key 不执行这个上限，要 16 实际产出 145\~159，`stop_reason` 仍为 `end_turn`。用 `auto` 时以 `usage.output_tokens` 对账。
  </Field>

  <Field name="messages" type="array" required>
    输入消息。模型按 `user` 与 `assistant` 轮次交替工作：请求里给出此前的轮次，模型生成下一条 `Message`；
    连续的同角色轮次会合并成一轮。每条消息是 `{role, content}`，`content` 可以是字符串，也可以是内容块数组（文本、图片、文档、工具结果混排）。
    若最后一条是 `assistant`，响应会直接从它的内容接着往下写，可用来约束回复的开头。
  </Field>
</Fields>

### 系统提示与输出

<Fields>
  <Field name="system" type="string | array">
    系统提示，用于给模型提供上下文与指令，例如设定目标或角色。给数组时每项是一个 `text` 块，可逐块附加 `cache_control`。
  </Field>

  <Field name="stream" type="boolean" default="false">
    是否以 server-sent events 增量返回响应。

    **网关。** 单次请求上限 120 秒，思考模型建议设为 `true`，见[流式要求](#流式要求)。
  </Field>

  <Field name="stop_sequences" type="array">
    自定义停止序列。模型正常结束时 `stop_reason` 为 `end_turn`；命中自定义序列时 `stop_reason` 为 `stop_sequence`，`stop_sequence` 字段回显命中的那一条。

    **网关 · 分组敏感。** 官方满血 key 生效；`auto` key 忽略它，输出照常跑完，`stop_reason` 仍是 `end_turn`。
  </Field>

  <Field name="output_config" type="object">
    输出配置。`effort` 取 `low` / `medium` / `high` / `xhigh` / `max`，控制模型投入的算力；`format` 为 `{"type": "json_schema", "schema": {...}}` 时约束输出为该结构，见[结构化输出](https://platform.claude.com/docs/en/build-with-claude/structured-outputs)。

    **网关 · 分组敏感。** 官方满血 key 返回纯 JSON；`auto` key 退化成普通文本，返回带 ` ``` ` 包裹的代码块，直接 `json.loads` 会失败。
    schema 里 `type: object` 须显式带 `additionalProperties`，否则 400——该校验只在官方满血 key 上执行。
  </Field>
</Fields>

### 思考

<Fields>
  <Field name="thinking" type="object">
    扩展思考配置。开启后响应里包含 `thinking` 内容块，展示模型给出最终答案前的思考过程。
    三种写法：`{"type": "adaptive"}` 由模型自行决定思考深度；`{"type": "enabled", "budget_tokens": N}` 指定思考预算，须 ≥ 1024 且小于 `max_tokens`；`{"type": "disabled"}` 关闭。
    `display` 可设 `omitted`，思考内容不返回但保留签名以维持多轮连续性。

    不同代次的模型接受的写法不同：Claude 4.7 及以后只接受 `adaptive`，显式 `enabled` + `budget_tokens` 会被拒绝；旧型号相反。
    跨型号的代码不要写死一种。

    **网关。** 对新型号传 `enabled` 会被改写为 `adaptive` 并删掉 `budget_tokens`，请求成功但预算不生效，见[参数改写规则](#参数改写规则)。
    `claude-opus-5-5` 上传 `disabled` 多数情况会 400，见同一节。`auto` key 上 `claude-sonnet-5` 不返回 thinking 块，见[分组差异](#分组差异)。
  </Field>
</Fields>

### 工具调用

<Fields>
  <Field name="tools" type="array">
    模型可以使用的工具定义。每个工具包含 `name`、`description` 和描述参数的 `input_schema`；模型决定调用时返回 `tool_use` 内容块，
    你执行后以 `tool_result` 内容块回传。也可以放服务端执行的内置工具（如 `web_search_20250305`）。

    **网关 · 分组敏感。** 自定义工具在两类 key 上都完整；服务端内置工具在 `auto` key 上不保证，见[分组差异](#分组差异)。
  </Field>

  <Field name="tool_choice" type="object">
    模型如何使用提供的工具：`{"type": "auto"}` 自行决定；`{"type": "any"}` 必须用某个工具；`{"type": "tool", "name": "..."}` 指定工具；`{"type": "none"}` 不用。
    `auto` / `any` 可加 `disable_parallel_tool_use: true`，让模型最多只发起一次工具调用。
    注意与 Chat Completions 不同，这里是对象不是字符串。
  </Field>
</Fields>

### 缓存

<Fields>
  <Field name="cache_control" type="object">
    提示缓存标记。顶层 `cache_control` 自动作用于请求里最后一个可缓存块；也可以在 `system`、`messages`、`tools` 的内容块上逐个设置 `{"type": "ephemeral"}`。
    把稳定不变的前缀（长系统提示、工具定义、文档）标为可缓存，后续命中时 `usage` 里出现 `cache_read_input_tokens`。

    **网关 · 分组敏感。** `auto` key 上不生效，`usage` 里不会出现缓存字段；官方满血 key 正常。
  </Field>
</Fields>

### 采样

三个采样参数官方已标记为弃用：晚于 Claude Opus 4.6 发布的模型只接受 `temperature: 1.0` 与 `top_p ≥ 0.99`，不接受 `top_k`，其他取值返回 400。

<Fields>
  <Field name="temperature" type="number" default="1.0">
    注入响应的随机程度，`0.0`–`1.0`。分析类、选择题类任务取值靠近 `0.0`，创作类靠近 `1.0`；即使为 `0.0` 结果也不完全确定。

    **网关。** 新型号上不等于 `1.0` 的值会被删除，见[参数改写规则](#参数改写规则)。
  </Field>

  <Field name="top_p" type="number">
    核采样：按概率降序累计，达到 `top_p` 即截断。仅建议高级用法使用，与 `temperature` 通常只调其一。

    **网关。** 新型号上小于 `0.99` 的值会被删除。
  </Field>

  <Field name="top_k" type="integer">
    每个 token 只从概率最高的 K 个候选里采样，用于去掉低概率的长尾。仅建议高级用法使用；Chat Completions 没有这个参数。

    **网关。** `claude-fable-5` / `claude-fable-5-1` 上会被删除。
  </Field>
</Fields>

### 标识与其他

<Fields>
  <Field name="metadata" type="object">
    请求元数据。`user_id` 为终端用户的外部标识，应是 uuid、哈希等不透明值，不要放姓名、邮箱、电话。
  </Field>

  <Field name="service_tier" type="string">
    `auto` / `standard_only`，选择优先容量还是标准容量。

    **网关。** 由网关自行路由，该字段无意义。
  </Field>

  <Field name="container" type="object">
    代码执行容器的复用标识。

    **网关。** 不提供代码执行工具，无效。
  </Field>

  <Field name="inference_geo" type="string">
    推理处理的地理区域。

    **网关。** 不保证生效。
  </Field>
</Fields>

## 响应字段

```json
{
  "id": "msg_...",
  "type": "message",
  "role": "assistant",
  "model": "claude-opus-5",
  "content": [
    { "type": "text", "text": "同一个操作执行多次和执行一次效果相同。" }
  ],
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": { "input_tokens": 24, "output_tokens": 17 }
}
```

<Fields>
  <Field name="content" type="array">
    内容块数组，**类型是混排的**。开了思考的模型会在前面多出 `{"type":"thinking"}` 块，
    用工具时会有 `{"type":"tool_use"}` 块。**直接取 `content[0]` 在这些情况下会拿到思考内容
    或工具调用，不是正文**——务必按 `type` 过滤。
  </Field>

  <Field name="stop_reason" type="string">
    `end_turn` 自然结束 · `max_tokens` 撞到输出上限 · `stop_sequence` 命中停止序列 ·
    `tool_use` 等待工具结果。
  </Field>

  <Field name="stop_sequence" type="string">
    命中的是哪一条停止序列，未命中为 `null`。
  </Field>

  <Field name="usage" type="object">
    `input_tokens` / `output_tokens`。用了提示缓存时还会有缓存读写的 token 统计，
    对账时要一并看。
  </Field>
</Fields>

## 流式事件

整体以 `message_start` 开始、`message_stop` 结束；中间每个内容块有自己的
`content_block_start` → 若干 `content_block_delta` → `content_block_stop`，
块之间用 `index` 区分。

```
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"同一个"}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"thinking_delta","thinking":"先确认定义…"}}
```

增量在 `delta` 里，`delta.type` 决定它属于哪种块：

<Fields>
  <Field name="text_delta" type="delta 类型">
    正文增量。**绝大多数情况只需要认这一种。**
  </Field>

  <Field name="thinking_delta" type="delta 类型">
    思考增量。
  </Field>

  <Field name="input_json_delta" type="delta 类型">
    工具调用参数的增量 JSON 片段，需自己累积拼接成完整 JSON 再解析。
  </Field>

  <Field name="message_delta" type="事件类型">
    顶层字段的变更，`stop_reason` 和最终的 `usage` 从这里来。
  </Field>
</Fields>

用工具时事件之间可能出现明显停顿，因为参数是攒够一组键值才发出来的，这是正常现象。

## 参数改写规则

这几个型号只接受自适应思考，显式思考预算在官方那里会直接 400。与其把这个错误丢给你，
网关在转发前将这类参数改写为等价的合法形式，请求因此成功，但原始取值不生效。
下表列出改写发生的条件。

| 触发条件                                                                                                        | 网关的动作                                       |
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `thinking.type` 为 `enabled`                                                                                 | 改写为 `adaptive`，并删除 `thinking.budget_tokens` |
| `temperature` **不等于** `1.0`                                                                                 | 删除该字段（`1.0` 保留）                             |
| `top_p` **小于** `0.99`                                                                                       | 删除该字段（`≥ 0.99` 保留）                          |
| `claude-fable-5` / `claude-fable-5-1`：总是                                                                    | 删除 `top_k`                                  |
| `claude-fable-5` / `claude-fable-5-1`：`thinking.type` 为 `disabled`                                          | 删除整个 `thinking`                             |
| `claude-opus-5` / `claude-opus-5-5`：`thinking.type` 为 `disabled` 且 `output_config.effort` 为 `xhigh` / `max` | 改写 `thinking.type` 为 `adaptive`             |

适用型号：`claude-opus-5-5`、`claude-opus-5`、`claude-sonnet-5`、`claude-opus-4-8`、`claude-opus-4-7`、
`claude-fable-5`、`claude-fable-5-1`。

**`claude-opus-5-5` 不接受关闭思考。** `thinking.type: "disabled"` 只有在 `effort` 为 `xhigh` / `max`
时会被改写，其余情况（不传 `effort`，或 `low` / `medium` / `high`）网关原样转发，返回 400：
`"***.***.disabled" is not supported for this model. Use "***.***.adaptive" and "output_config.effort" to control thinking behavior.`
（`***.***` 是网关对 `thinking.type` 的打码。）不想要思考就不传 `thinking`，把 `output_config.effort` 调到 `low`——
实测简单问题这样不返回 thinking 块。`claude-opus-5` 上 `disabled` 仍可直接用。2026-09-23 实测。

**最要紧的一条是 `thinking`。** 你传 `{"type": "enabled", "budget_tokens": 4096}`
会拿到 200，但 `budget_tokens` 已经被丢掉了，思考长度由模型自己决定。要控制思考成本，
用 `max_tokens` 留出的空间去间接约束，别依赖 `budget_tokens`。

这几个型号只接受 `temperature = 1.0` 与 `top_p >= 0.99`（Anthropic 对晚于 Opus 4.6
发布的模型的兼容边界），其他取值上游会直接 400。网关把不合规的值删掉，请求因此成功——
但**你设置的自定义 `temperature` / `top_p` 在这些型号上不会生效**。`claude-opus-4-6`、
`claude-sonnet-4-6`、`claude-haiku-4-5` 等旧型号不套用此规则，采样参数原样透传。

## 分组差异

key 分两类：**`auto`**（可调用除 `claude-opus-5-5`、`claude-fable-5`、`claude-fable-5-1` 外的全部模型）和 **`Claude 官方满血版`**。Claude 系模型
在这两类上有实测差异，**全部返回 200，没有任何报错或警告**：

| 能力                            | `auto`                                                       | `Claude 官方满血版`                                               |
| ----------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| 提示缓存 `cache_control`          | **不可用**，`usage` 里不返回缓存字段                                     | 返回 `cache_creation_input_tokens` / `cache_read_input_tokens` |
| 服务端执行的内置工具                    | 不保证，响应形状可能不符合官方约定                                            | 正常                                                           |
| `thinking`（`claude-sonnet-5`） | **不返回 thinking 块**，显式要求也不返回                                  | 返回                                                           |
| `thinking`（`claude-opus-5`）   | 返回，但输出（含思考）明显更短                                              | 完整                                                           |
| `max_tokens` 上限               | **不执行**，要求 16 实际产出 145\~159                                  | 精确执行，`stop_reason` 为 `max_tokens`                            |
| `stop_sequences`              | **被忽略**，输出照常跑完                                               | 生效，`stop_reason` 为 `stop_sequence`                           |
| `output_config` 结构化输出         | 退化成 markdown 代码块                                             | 返回纯 JSON                                                     |
| 可用模型                          | 不含 `claude-opus-5-5` / `claude-fable-5` / `claude-fable-5-1` | 含                                                            |

以上差异在 `auto` 上均表现为静默忽略：请求返回 200，响应内容正常，设置的约束不生效。

常规对话与代码生成用 `auto` 即可。**只要你的代码依赖参数被真正执行——限制输出长度、
停止序列、结构化输出、提示缓存、服务端工具、`claude-sonnet-5` 的 thinking——就必须换
官方满血 key，改参数没有用。**

**一把 key 可以多选分组。** 在控制台给 key 选多个分组后，请求按从左到右的顺序尝试：当前分组没有
这个模型的可用渠道，就换下一个；`auto` 在它所在的位置展开；计费按实际命中的分组结算。两种常见排法：

* **`auto` → `Claude 官方满血版`**：只有 `auto` 调不到的 `claude-opus-5-5`、`claude-fable-5`、
  `claude-fable-5-1` 会落到满血版，其余请求照旧走 `auto`。
* **`Claude 官方满血版` → `auto`**：Claude 请求全部先走满血版，拿到上表右列的完整行为，也按满血版的
  倍率计费；其他模型走 `auto`。

多选分组的 key 报错时，信息里显示的分组可能仍是 `auto`，这不代表请求只走了 `auto`。

## 如何验证生效

**不要用 HTTP 状态码判断**，上面两类情况都返回 200。看响应体：

* **思考是否生效** —— `content` 数组里有没有 `{"type": "thinking"}` 块。
* **缓存是否生效** —— `usage` 里有没有 `cache_creation_input_tokens` /
  `cache_read_input_tokens`。没有这两个字段就是没生效，不管你怎么标 `cache_control`。
* **参数有没有被改写** —— 把可疑参数换一个明显不同的值再发一次，看输出是否真的变化。
  两次没差异，多半是它没被送到模型那里。

## 国产模型兼容度

网关上的国产模型（glm / kimi / qwen / deepseek / MiniMax）两套协议都能调通，
工具调用也都可用，但对 `max_tokens`、停止序列、结构化输出的遵循程度**逐个模型不同**，
同一模型在 Messages 协议和另一套协议上还可能表现不同。逐项实测结果见
[模型与入口](https://docs.vibeapi.cn/zh/docs/models)。

其中 `deepseek-v4-pro` 与 `kimi-k3` 不执行 `max_tokens`，且仍将结束原因报为已截断。
使用这两个模型时，以 `usage` 中的实际 token 数对账。

## 真实响应示例

下面是从生产网关真实抓取、脱敏后的响应。注意 `content` 是内容块数组：

<Example id="messages-thinking" />

模型决定调用工具时，会多出一个 `tool_use` 块：

<Example id="messages-tool" />

流式的事件序列（中间事件已省略）：

<Example id="messages-stream" />

### 国产模型的真实响应

以下为各国产模型在 Messages 协议上的真实调用与响应。注意 `kimi-k3` 会返回
`thinking` 块，`usage.output_tokens_details.thinking_tokens` 是其消耗。

<Examples group="cn-msg" open="cn-msg-glm" />

## 能力边界

* **只保证核心能力**：消息、流式、thinking、基本的工具调用。批处理、文件上传、
  代码执行容器这些端点不在提供范围内。
* **`thinking` 的写法不能跨代次通用**，写死一种会在另一代次上 400。
* **`container` / `inference_geo` / `service_tier` 无效**，见参数表。
* **非流式不适合推理型号。**

## 在线调试

填入你自己的 API Key 即可直接发起请求，参数表与响应结构由接口定义生成。

<APIPage document={"openapi/generated/ai-model/聊天（Chat）/post-v1-messages-createmessage-383826476.json"} operations={[{"path":"/v1/messages","method":"post"}]} />

## 官方文档

本页只写与本网关有关的部分，参数语义的权威定义以官方为准：

* [Anthropic · Messages](https://platform.claude.com/docs/en/api/messages)
* [Anthropic · 流式](https://platform.claude.com/docs/en/build-with-claude/streaming)
* [Anthropic · 思考](https://platform.claude.com/docs/en/build-with-claude/thinking)


# 模型与入口

<HeroVideo src="https://studio.vibevibe.cn/docs/260915/docs-intro/video/models.mp4" poster="https://studio.vibevibe.cn/docs/260915/docs-intro/poster/models.webp" model="doubao-seedance-2-5-260628" />

网关地址 `https://www.vibeapi.cn/v1`，所有请求带 `Authorization: Bearer <API_KEY>`。

## 列出模型

`GET /v1/models` 返回当前 key 可调用的全部模型，模型名与下方矩阵一致。

<Tabs items={['curl', 'Python', 'Node.js']}>
  <Tab value="curl">
    ```bash
    curl "https://www.vibeapi.cn/v1/models" \
      -H "Authorization: Bearer $API_KEY"
    ```
  </Tab>

  <Tab value="Python">
    ```python
    from openai import OpenAI

    client = OpenAI(base_url="https://www.vibeapi.cn/v1", api_key="YOUR_API_KEY")

    for m in client.models.list():
        print(m.id)
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    import OpenAI from "openai";

    const client = new OpenAI({ baseURL: "https://www.vibeapi.cn/v1", apiKey: "YOUR_API_KEY" });

    for await (const m of client.models.list()) {
      console.log(m.id);
    }
    ```
  </Tab>
</Tabs>

## 流式与超时

请求超时上限是 **120 秒**。非流式请求在生成完成前没有任何数据下行，单次生成一旦超过这个
时间，连接会被中断，表现为「调用超时」。

短输出的非流式请求正常可用，通常几秒即返回。会触发上限的是长输出与推理型模型——
它们要等整段推理和生成结束才返回首字节。**由于单次生成耗时无法预先判断，生产环境
建议默认开启流式**：流式从第一个事件起就有数据下行，连接不会闲置到触发超时。

需要一次性拿到完整结果时，请在客户端聚合流式事件，而不是改回非流式。

## 标注含义

下面每个模型最多有三行，含义是固定的：

<Fields>
  <Field name="推荐" type="就这样写">
    这个模型的原生入口，功能最全、字段保真最好。没有特殊理由就用它。
  </Field>

  <Field name="也可" type="能用，但更差">
    可以调通，但会损失一些东西——具体差在哪写在模型下面的说明里。
  </Field>

  <Field name="转换" type="网关替你翻译">
    你用 A 协议发，网关翻译成 B 协议后再发出。**只保证核心功能**：消息、流式、基本的
    工具调用。协议特有的字段（比如 Claude 的 thinking 块、Gemini 的 imageConfig）会在
    翻译中丢失。调用成功不代表功能等价。
  </Field>
</Fields>

标着 **ⓘ 以实测为准** 的模型，它们的原生协议逐个模型而异，结论是实测出来的，日期是
最后一次验证的时间。没有这个标记的（OpenAI、Anthropic、Google 三家）是确定性的，
不随时间变化。

## 两类静默失效

**一、你的 key 分组会影响能力。** key 分 `auto`（可调用除 `claude-opus-5-5`、`claude-fable-5`、`claude-fable-5-1` 外的全部模型）和
`Claude 官方满血版` 两类。Claude 系模型在这两类上，提示缓存、服务端工具和 thinking
的实际可用性**是不同的**；GPT 系实测没有差异。一把 key 可以多选分组：想保留 `auto` 又要用这三个模型，
在 `auto` 后面加选 `Claude 官方满血版`。详见 [Messages · 分组差异](https://docs.vibeapi.cn/zh/docs/messages#分组差异)。

**二、网关会为部分模型过滤或改写参数**，比如 Claude 的 `thinking.budget_tokens`
会被丢掉、Grok 在 Chat 接口上的内置 `web_search` 会被移除。规则写在各自的调用页
（[Messages](https://docs.vibeapi.cn/zh/docs/messages) · [Chat](https://docs.vibeapi.cn/zh/docs/chat) · [Responses](https://docs.vibeapi.cn/zh/docs/responses)）。

两件事都返回 200，只看状态码发现不了。

## 国产模型的协议兼容度

国产模型两套协议都能调通，但**对参数的遵循程度参差不齐**。
下面是逐项实测结果（`auto` key，最后验证 2026-09-09）：

|                            | glm-5.3         | kimi-k3   | qwen3.8-max | deepseek-v4-pro | MiniMax-M3 |
| -------------------------- | --------------- | --------- | ----------- | --------------- | ---------- |
| 基本调用（两协议）                  | ✅               | ✅         | ✅           | ✅               | ✅          |
| **工具调用**（两协议）              | ✅               | ✅         | ✅           | ✅               | ✅          |
| `max_tokens` 是否执行          | ✅ 精确            | ❌ **不执行** | ✅ 精确        | ❌ **严重不执行**     | ✅ 精确       |
| `stop`（Chat 协议）            | ❌               | ✅         | ❌           | ✅               | ❌          |
| `stop_sequences`（Messages） | ❌               | ✅         | ✅           | ✅               | ❌          |
| `json_object` 结构化输出        | ❌ 带 markdown 包裹 | ✅         | ✅           | ✅               | ✅          |

三条要点：

**一、工具调用全部可用。** 五个模型在 Chat 和 Messages 两个协议上都能正确返回
`tool_calls` / `tool_use`。做 agent 类应用可以放心用。

**二、`max_tokens` 在两个模型上不执行，而且结束字段会误导你。**
`deepseek-v4-pro` 要求 16 token，实际产出 **1465**（Chat）/ **964**（Messages）；
`kimi-k3` 要求 16，实际产出 81 / 75。这两个模型同时将 `finish_reason` 报为 `length`、
`stop_reason` 报为 `max_tokens`，与实际不符。

> 不要用 `max_tokens` 估算成本上限，也不要依据 `finish_reason` 判断是否截断。
> 使用这两个模型时，以 `usage` 中的实际 token 数对账。

**三、`stop` / `stop_sequences` 看模型，而且同一模型在两个协议上可能不同。**
`qwen3.8-max` 在 Messages 协议上生效、在 Chat 协议上不生效。依赖停止序列的逻辑，
请先在你要用的那个协议上实测一次，不要跨协议套用结论。

`glm-5.3` 的 `json_object` 会返回带 ` ``` ` 包裹的代码块，解析前要先剥离。

<ModelMatrix />

## 在线调试

填入你自己的 API Key 即可直接发起请求，参数表与响应结构由接口定义生成。

<APIPage document={"openapi/generated/ai-model/模型（Models）/列出模型/get-v1-models-listmodels-383826468.json"} operations={[{"path":"/v1/models","method":"get"}]} />


# 快速开始

<HeroVideo src="https://studio.vibevibe.cn/docs/260915/docs-intro/video/quickstart.mp4" poster="https://studio.vibevibe.cn/docs/260915/docs-intro/poster/quickstart.webp" model="doubao-seedance-2-0-260128" />

VibeAPI 兼容 OpenAI、Anthropic、Google 三家的官方协议，**官方 SDK 只需要换一个 base URL**。一把 key 可调用 GPT、Claude、Gemini、Grok 与国产模型。

只是想在 Claude Code、Codex 这类编码工具里用，不写代码？看[编码工具（VibeCLI）](https://docs.vibeapi.cn/zh/docs/coding-tools)：一条命令装工具，一条命令配 key。

## 获取 key 与地址

|                                  |                                                               |
| -------------------------------- | ------------------------------------------------------------- |
| Base URL（OpenAI SDK / 直接调 HTTP）  | `https://www.vibeapi.cn/v1`                                   |
| Base URL（Anthropic / Google SDK） | `https://www.vibeapi.cn`，SDK 自己拼 `/v1/messages`、`/v1beta/...` |
| 认证                               | 请求头 `Authorization: Bearer <API_KEY>`                         |
| 可用模型                             | `GET /v1/models`，或看[模型与入口](https://docs.vibeapi.cn/zh/docs/models)                   |

`/v1` 只属于 OpenAI 协议这一族的路径。Anthropic SDK 与 Google `google-genai` SDK 填 base URL 时**不带** `/v1`，写 `https://www.vibeapi.cn` 即可，SDK 会自己拼上 `/v1/messages` 或 `/v1beta/...`；直接调 Gemini 原生 HTTP 时也是 `/v1beta/...`，不是 `/v1`。

## 使用官方 SDK

SDK 处理了以下几类容易出错的细节：

<Fields>
  <Field name="SSE 流式解析" type="最容易出错的一块">
    手写的 SSE 解析器几乎都会在这几处翻车：一个事件跨越多个 TCP 包、`data:` 出现多行、
    注释行（以 `:` 开头）、以及最后的 `[DONE]` 哨兵。SDK 的迭代器直接给你解析好的事件对象。
  </Field>

  <Field name="工具调用参数的拼接" type="第二容易出错">
    流式下函数参数是**分片下发**的，要按 `index` 累积拼成完整 JSON 才能解析。
    自己写很容易在多个并行工具调用时串行错位。
  </Field>

  <Field name="超时与重试" type="容易被忽略">
    SDK 自带合理的超时默认值和对 429 / 5xx 的指数退避重试。裸 `requests.post` 不设超时，
    一次网络抖动就是一个挂死的请求。
  </Field>

  <Field name="请求形状" type="写代码时就能发现">
    参数名写错、该用 `max_completion_tokens` 却用了 `max_tokens`、Messages 忘了必填的
    `max_tokens`——这些在有类型提示的 SDK 里当场就能发现，不用等线上报 400。
  </Field>
</Fields>

安装：

<Tabs items={['Python', 'Node.js']}>
  <Tab value="Python">
    ```bash
    pip install openai        # Responses / Chat / 图像 / Grok
    pip install anthropic     # Claude Messages
    pip install google-genai  # Gemini
    ```
  </Tab>

  <Tab value="Node.js">
    ```bash
    npm install openai             # Responses / Chat / 图像 / Grok
    npm install @anthropic-ai/sdk  # Claude Messages
    npm install @google/genai      # Gemini
    ```
  </Tab>
</Tabs>

## 发第一个请求

<Tabs items={['Python', 'Node.js', 'curl']}>
  <Tab value="Python">
    ```python
    from openai import OpenAI

    client = OpenAI(base_url="https://www.vibeapi.cn/v1", api_key="YOUR_API_KEY")

    stream = client.responses.create(
        model="gpt-6-astra",
        input="用一句话解释什么是幂等。",
        stream=True,
    )

    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    import OpenAI from "openai";

    const client = new OpenAI({
      baseURL: "https://www.vibeapi.cn/v1",
      apiKey: "YOUR_API_KEY",
    });

    const stream = await client.responses.create({
      model: "gpt-6-astra",
      input: "用一句话解释什么是幂等。",
      stream: true,
    });

    for await (const event of stream) {
      if (event.type === "response.output_text.delta") process.stdout.write(event.delta);
    }
    ```
  </Tab>

  <Tab value="curl">
    ```bash
    curl -N -X POST "https://www.vibeapi.cn/v1/responses" \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"model":"gpt-6-astra","input":"用一句话解释什么是幂等。","stream":true}'
    ```
  </Tab>
</Tabs>

用环境变量更省事，两家 SDK 都认：

```bash
# OpenAI SDK
export OPENAI_BASE_URL="https://www.vibeapi.cn/v1"
export OPENAI_API_KEY="sk-..."

# Anthropic SDK
export ANTHROPIC_BASE_URL="https://www.vibeapi.cn"
export ANTHROPIC_API_KEY="sk-..."
```

设好之后 `OpenAI()` / `Anthropic()` 不传参数就能直接用。

## 开启流式

**请求超时上限是 120 秒。** 非流式请求在生成完成前没有任何数据下行，单次生成一旦超过
这个时间，连接会被中断，表现为「调用超时」。

短输出的非流式请求正常可用；长输出与推理型模型容易触发上限。该超时为硬约束，
无法通过配置放宽，而单次生成耗时又无法预先判断，**因此生产环境建议默认开启流式**。

需要一次性获得完整结果时，请在客户端聚合流式事件。两家 SDK 均提供了聚合接口：
OpenAI SDK 的 `stream.get_final_response()`、Anthropic SDK 的 `stream.get_final_message()`。

## 选择端点

按模型家族选它的原生协议，功能最全；跨协议调用是网关翻译的，只保证消息、流式和基本工具调用。

| 你要做的事                      | 端点                                                                                                | SDK                                 |
| -------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------- |
| GPT 系对话（`gpt-*`、`codex-*`） | [OpenAI Responses](https://docs.vibeapi.cn/zh/docs/responses)，推荐                                                         | `openai`                            |
| Claude 系对话（`claude-*`）     | [Claude Messages](https://docs.vibeapi.cn/zh/docs/messages)                                                              | `anthropic`                         |
| Gemini 系对话（`gemini-*`）     | [Gemini generateContent](https://docs.vibeapi.cn/zh/docs/gemini)                                                         | `google-genai`                      |
| Grok 对话与国产模型               | [OpenAI Chat Completions](https://docs.vibeapi.cn/zh/docs/chat) / [Grok 对话](https://docs.vibeapi.cn/zh/docs/grok)                               | `openai`                            |
| 生图                         | [GPT 图像](https://docs.vibeapi.cn/zh/docs/images) · [Gemini 图像](https://docs.vibeapi.cn/zh/docs/gemini-images) · [Grok 图像](https://docs.vibeapi.cn/zh/docs/grok-images) | `openai` / `google-genai`           |
| 生视频                        | [视频生成](https://docs.vibeapi.cn/zh/docs/videos)（万相 / Seedance / MiniMax）· [Grok 视频](https://docs.vibeapi.cn/zh/docs/grok-videos)                 | 直接 HTTP                             |
| 判断而不是生成（路由 / 分类 / 打分）      | [TypeSafe 判断型模型](https://docs.vibeapi.cn/zh/docs/typesafe)                                                               | `typesafe-sdk` / `@typesafe-ai/sdk` |

拿不准就查[模型与入口](https://docs.vibeapi.cn/zh/docs/models)，那里逐个模型写明了推荐入口、可用入口，以及哪些是网关转换出来的。

## 给 AI 编程代理装 Skill

本站打包成了一个 Skill。装进代理之后，涉及 VibeAPI 的任务里它会自动读：该走哪套协议、
为什么建议流式、网关会改写哪些参数、两类 key 的差异，以及每个参数的实测结果。内容与本站同源，随站点构建更新。

把这句话发给你的代理，它自己会装：

```text
帮我安装这个 Skill：https://docs.vibeapi.cn/vibeapi-skill.zip
```

想手动装：解压得到 `vibeapi/`（`SKILL.md`、`references/`、`VERSION`、`scripts/update.sh`），放进代理的 skills 目录。
`SKILL.md` 是一份带 frontmatter 的普通 Markdown，不支持 Agent Skills 规范的工具，
把它贴进 `AGENTS.md` 或系统提示也能用，`references/` 下的文件按需附上。

**装一次，之后自己更新。** 每个 Skill 包都带版本号（内容截至日期 + 内容哈希，写在 `SKILL.md` 与 `VERSION` 里）。
`SKILL.md` 让代理每次会话开始时运行一次 `scripts/update.sh`：它读线上清单
[`vibeapi-skill.json`](https://docs.vibeapi.cn/vibeapi-skill.json)，版本不同就下载新包、校验 sha256 后覆盖，
并删掉线上已下线的参考页。更新不了（离线、目录只读）时，代理会用 `date` 核对日期，内容超过 14 天就改读线上页面、
以 `GET /v1/models` 为准。想手动检查：`sh vibeapi/scripts/update.sh --check`。

## 官方文档

我们只写与本网关有关的部分。参数语义的权威定义仍以官方为准：

* [OpenAI API Reference](https://developers.openai.com/api/reference/overview) ·
  [Responses](https://developers.openai.com/api/reference/resources/responses/methods/create) ·
  [迁移到 Responses](https://developers.openai.com/api/docs/guides/migrate-to-responses)
* [Anthropic Messages API](https://platform.claude.com/docs/en/api/messages) ·
  [流式](https://platform.claude.com/docs/en/build-with-claude/streaming)
* [Gemini API · generateContent](https://ai.google.dev/api/generate-content)
* [xAI · API 文档](https://docs.x.ai/)


# OpenAI Responses

<HeroVideo src="https://studio.vibevibe.cn/docs/260915/docs-intro/video/responses.mp4" poster="https://studio.vibevibe.cn/docs/260915/docs-intro/poster/responses.webp" model="wan3.0-image-720p" />

`POST /v1/responses`

OpenAI 对新项目推荐这个端点而不是 Chat Completions，Chat 仍受支持但不再是首选。
公开理由集中在几点：推理模型上表现更好、提示缓存命中率显著更高（因而更便宜）、
可用 `previous_response_id` 跨轮保留推理与工具上下文、内置工具只在这一侧提供。

**在 VibeAPI 上，GPT 系模型的推荐入口就是这里。** 走这个端点的模型见
[模型与入口](https://docs.vibeapi.cn/zh/docs/models)；Claude 系请去 [Messages](https://docs.vibeapi.cn/zh/docs/messages)。

## 基本调用

**建议用官方 SDK 而不是自己拼 HTTP**——SSE 解析、工具参数分片拼接、超时与重试都由它处理，能避开大部分常见问题。安装与环境变量配置见[快速开始](https://docs.vibeapi.cn/zh/docs/quickstart)。

<Tabs items={['curl', 'Python', 'Node.js']}>
  <Tab value="curl">
    ```bash
    curl -N -X POST "https://www.vibeapi.cn/v1/responses" \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "gpt-6-astra",
        "instructions": "你是一个简洁的助手。",
        "input": "用一句话解释什么是幂等。",
        "stream": true
      }'
    ```
  </Tab>

  <Tab value="Python">
    ```python
    from openai import OpenAI

    client = OpenAI(base_url="https://www.vibeapi.cn/v1", api_key="YOUR_API_KEY")

    stream = client.responses.create(
        model="gpt-6-astra",
        instructions="你是一个简洁的助手。",
        input="用一句话解释什么是幂等。",
        stream=True,
    )

    for event in stream:
        if event.type == "response.output_text.delta":
            print(event.delta, end="", flush=True)
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    import OpenAI from "openai";

    const client = new OpenAI({
      baseURL: "https://www.vibeapi.cn/v1",
      apiKey: "YOUR_API_KEY",
    });

    const stream = await client.responses.create({
      model: "gpt-6-astra",
      instructions: "你是一个简洁的助手。",
      input: "用一句话解释什么是幂等。",
      stream: true,
    });

    for await (const event of stream) {
      if (event.type === "response.output_text.delta") process.stdout.write(event.delta);
    }
    ```
  </Tab>
</Tabs>

## 认证

`Authorization: Bearer <API_KEY>`，`base_url` 为 `https://www.vibeapi.cn/v1`。
官方 SDK 换掉 `base_url` 即可。

## 流式要求

请求超时上限 **120 秒**。非流式请求在生成完成前没有数据下行，单次生成超过这个时间会被
中断。短输出不受影响；推理模型要等整段推理结束才返回首字节，容易触发上限。
**建议默认开启流式**，需要完整文本时在客户端聚合 `response.output_text.delta`。

## 与 Chat 的差异

从 Chat 迁过来最容易卡在这里，先看懂再往下写代码。

Chat 的输入输出都是 **Message** 数组；Responses 用 **Item**。Item 是联合类型，
`message` 只是其中一种，`function_call`、`function_call_output`、`reasoning` 各是独立的
一种——不再像 Chat 那样把多种含义塞进同一个对象。

响应形状也跟着变：Chat 返回 `choices` 数组、每项裹一个 `message`；Responses 返回一个
带自己 `id` 的 `response` 对象，产出在 `output` 数组里。Chat 用 `n` 一次要多个结果的
能力在这里去掉了，一次只有一个生成结果。

|      | Chat Completions             | Responses                   |
| ---- | ---------------------------- | --------------------------- |
| 输入单位 | `messages`（Message）          | `input`（Item，也可直接给字符串）      |
| 系统指引 | `messages` 里的 `system` 角色    | `instructions`              |
| 产出位置 | `choices[0].message.content` | `output` 数组 / `output_text` |
| 输出上限 | `max_completion_tokens`      | `max_output_tokens`         |
| 多轮   | 自己把历史拼回 `messages`           | `previous_response_id`      |
| 推理强度 | `reasoning_effort`           | `reasoning.effort`          |

## 请求参数

参数名、类型与语义对齐 [OpenAI Responses API](https://developers.openai.com/api/reference/resources/responses/methods/create)。每个参数先给官方定义，再以「网关」标注本网关的实测行为。
GPT 系模型的请求体不经改写，整个参数面照单转发；标注含义：**支持**＝有可观测证据生效；**接受**＝正常受理、效果取决于模型本身；**无效**＝本网关不提供这项能力。

### 核心

<Fields>
  <Field name="model" type="string" required>
    用于生成响应的模型 ID。走这个端点的模型见[模型与入口](https://docs.vibeapi.cn/zh/docs/models)。
  </Field>

  <Field name="input" type="string | array" required>
    给模型的文本、图片或文件输入。单轮问答直接给字符串；多轮、带工具结果或多模态时给 Item 数组。
  </Field>

  <Field name="instructions" type="string">
    插入模型上下文的系统（或 developer）消息。与 `previous_response_id` 同用时，上一轮的 `instructions` 不会带到下一轮，便于在多轮间替换指令——需要每轮都带。
  </Field>
</Fields>

### 多轮与状态

<Fields>
  <Field name="previous_response_id" type="string">
    上一次响应的唯一 ID，用于构建多轮对话：推理与工具上下文跨轮保留。不能与 `conversation` 同用。

    **网关 · 支持。** 这是相对 Chat Completions 最实际的收益。
  </Field>

  <Field name="conversation" type="string | object">
    本次响应所属的会话：会话里的 Item 会前置到本次输入，本次的输入输出也会自动追加进会话。

    **网关。** 依赖服务端存储，不保证可用。
  </Field>

  <Field name="store" type="boolean" default="true">
    是否保存生成的响应，供之后通过 API 取回；用 `previous_response_id` 串多轮时需要为 `true`。
  </Field>

  <Field name="include" type="array">
    要求响应额外带回的数据，如 `reasoning.encrypted_content`、`message.output_text.logprobs`、内置工具调用的中间产物。**接受。**
  </Field>

  <Field name="context_management" type="array">
    上下文管理配置，目前只有 `compaction`：达到 `compact_threshold` 个 token 时触发压缩。**接受。**
  </Field>
</Fields>

### 输出控制

<Fields>
  <Field name="stream" type="boolean" default="false">
    为 `true` 时以 server-sent events 边生成边返回。

    **网关。** 单次请求上限 120 秒，推理模型建议设为 `true`，见[流式要求](#流式要求)。
  </Field>

  <Field name="stream_options" type="object">
    流式选项，仅在 `stream: true` 时设置（如 `include_obfuscation`）。**接受。**
  </Field>

  <Field name="max_output_tokens" type="integer">
    本次响应可生成的 token 上限，**包含可见输出与推理 token**。不够时返回 `status: "incomplete"`、`incomplete_details.reason` 为 `max_output_tokens`，且可能一个可见字符都没产出就已计费。给推理模型留足空间。
  </Field>

  <Field name="text" type="object">
    文本响应的配置：纯文本或结构化 JSON。结构化输出写在 `{"format": {"type": "json_schema", ...}}`；能否严格遵守取决于模型。
  </Field>

  <Field name="truncation" type="string" default="disabled">
    `auto` 时输入超出上下文窗口会从对话开头丢弃 Item 以适配；`disabled` 时超出即报 400。**接受。**
  </Field>

  <Field name="background" type="boolean" default="false">
    以后台任务方式运行响应，之后轮询取结果。

    **网关 · 无效。** 不提供后台任务接口。
  </Field>
</Fields>

### 推理

<Fields>
  <Field name="reasoning" type="object">
    推理模型的配置。`effort` 约束推理投入（`none` / `minimal` / `low` / `medium` / `high` / `xhigh` / `max`，支持的取值与默认值随模型而异）；`summary` 要求返回推理摘要（`auto` / `concise` / `detailed`）。

    **网关 · 实测（2026-09-23）。** `gpt-6-astra` 只接受 `low` 到 `max`，传 `none` 或 `minimal` 返回 400
    `Unsupported value: 'none' is not supported with the 'gpt-6-astra' model`（`minimal` 被当成 `none` 处理）；
    `gpt-6-sol` / `gpt-6-luna` 七档都接受，`minimal` 在响应里回显为 `none`。
  </Field>
</Fields>

### 工具调用

<Fields>
  <Field name="tools" type="array">
    模型可调用的工具数组：内置工具（联网搜索、文件检索、代码解释器、图像生成、远程 MCP 等）、函数工具、自定义工具。用 `tool_choice` 指定使用方式。

    **网关。** 函数工具完整；内置工具不保证可用，也不保证与官方一致。

    **联网搜索按次计费。** `web_search` 与 `web_search_preview` 按实际搜索次数（`output` 里的 `web_search_call` 条目）计费：GPT 系每千次 10 美元（gpt-4o、gpt-4.1 系列用 `web_search_preview` 时 25 美元），Grok 每千次 5 美元，乘分组倍率；声明了工具但模型没有搜索不收费。Grok 的 `x_search` 按抓取的帖子与用户资料计，见 [Grok · 联网搜索](https://docs.vibeapi.cn/zh/docs/grok#联网搜索)。调用日志里写明次数与费用。
  </Field>

  <Field name="tool_choice" type="string | object">
    模型如何选择工具：`none` / `auto` / `required`，或指定某个函数、某类内置工具。
  </Field>

  <Field name="parallel_tool_calls" type="boolean" default="true">
    是否允许模型并行执行工具调用。**接受。**
  </Field>

  <Field name="max_tool_calls" type="integer">
    一次响应内内置工具调用的总次数上限，跨所有内置工具计数，超出的调用被忽略。**接受。**
  </Field>
</Fields>

### 提示缓存

<Fields>
  <Field name="prompt" type="object">
    引用服务端保存的提示模板及其变量（`id`、`version`、`variables`）。

    **网关。** 依赖服务端存储，不保证可用。
  </Field>

  <Field name="prompt_cache_key" type="string">
    用于把相似请求路由到同一缓存，提高提示缓存命中率；取代 `user` 字段的缓存用途。

    **网关 · 支持。** 相同前缀的请求 `usage.input_tokens_details.cached_tokens` 能读到命中量，`auto` 与官方满血两类 key 都可用。Responses 相对 Chat 的省钱优势主要来自缓存，值得用起来。
  </Field>

  <Field name="prompt_cache_options" type="object">
    提示缓存选项，`gpt-5.6` 及以后支持：`mode: "explicit"` 关闭隐式断点，`ttl` 目前只支持 `30m`。**接受。**
  </Field>

  <Field name="prompt_cache_retention" type="string">
    已弃用，改用 `prompt_cache_options.ttl`。设为 `24h` 延长缓存保留。**接受。**
  </Field>
</Fields>

### 采样与标识

<Fields>
  <Field name="temperature" type="number" default="1">
    采样温度，`0`–`2`。越高越随机，越低越集中；一般只调它或 `top_p` 之一。

    **网关。** 部分推理模型忽略它或只接受默认值，取决于模型。
  </Field>

  <Field name="top_p" type="number" default="1">
    核采样，替代温度：只考虑累计概率达到 `top_p` 的那部分 token。
  </Field>

  <Field name="top_logprobs" type="integer">
    每个位置返回最可能的 `0`–`20` 个 token 及其对数概率，需在 `include` 里加 `message.output_text.logprobs`。**接受。**
  </Field>

  <Field name="metadata" type="object">
    最多 16 对键值，键 ≤ 64 字符、值 ≤ 512 字符，随对象存储、可供查询。**接受。**
  </Field>

  <Field name="safety_identifier" type="string">
    帮助识别可能违反使用政策的终端用户的稳定标识，≤ 64 字符，建议用用户名或邮箱的哈希。**接受。**
  </Field>

  <Field name="user" type="string">
    终端用户的稳定标识，正被 `safety_identifier` 与 `prompt_cache_key` 取代。**接受。**
  </Field>

  <Field name="service_tier" type="string">
    处理类型：`auto` / `default` / `flex` / `priority` 等。

    **网关。** 由网关自行路由，该字段无意义。
  </Field>

  <Field name="moderation" type="object">
    对输入与输出运行内容审核的配置（`model`、`policy`）。**接受。**
  </Field>
</Fields>

## 响应字段

```json
{
  "id": "resp_...",
  "object": "response",
  "status": "completed",
  "model": "gpt-6-astra",
  "output": [
    { "type": "reasoning", "id": "rs_...", "summary": [] },
    {
      "type": "message",
      "id": "msg_...",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "同一个操作执行多次和执行一次效果相同。" }]
    }
  ],
  "usage": {
    "input_tokens": 32,
    "output_tokens": 18,
    "output_tokens_details": { "reasoning_tokens": 0 },
    "total_tokens": 50
  }
}
```

<Fields>
  <Field name="id" type="string">
    本次响应的 id，多轮时作为下一轮的 `previous_response_id`。
  </Field>

  <Field name="status" type="string">
    `completed` / `incomplete` / `in_progress` / `failed`。
  </Field>

  <Field name="incomplete_details.reason" type="string">
    `status` 为 `incomplete` 时的原因，最常见是 `max_output_tokens`。
  </Field>

  <Field name="output" type="array">
    产出的 Item 数组。**类型是混排的**——`reasoning`、`message`、`function_call` 都可能出现，
    取正文务必按 `type` 过滤，不要直接取 `output[0]`。
  </Field>

  <Field name="output_text" type="string">
    官方 SDK 提供的便捷字段，把所有 `output_text` 片段拼好。裸 HTTP 调用时没有这个字段，
    需要自己从 `output` 里取。
  </Field>

  <Field name="usage.output_tokens_details.reasoning_tokens" type="integer">
    不可见的推理 token 数，**计费但不出现在正文里**。推理模型上对账要看这个。
  </Field>
</Fields>

## 流式事件

事件是有类型的，按 `type` 分发，不像 Chat 那样只有一种 chunk：

```
event: response.created
data: {"type":"response.created","response":{"id":"resp_...","status":"in_progress"}}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"同一个"}

event: response.completed
data: {"type":"response.completed","response":{"id":"resp_...","status":"completed"}}
```

常见事件类型：

<Fields>
  <Field name="response.created" type="生命周期">
    响应已创建，此时能拿到 `id`。
  </Field>

  <Field name="response.output_item.added" type="生命周期">
    新增一个输出 Item（一条消息、一次函数调用、一段推理）。
  </Field>

  <Field name="response.output_text.delta" type="内容">
    正文增量。**只认这一种就够取全文了。**
  </Field>

  <Field name="response.function_call_arguments.delta" type="内容">
    函数调用参数的增量 JSON 片段，需自行累积拼接。
  </Field>

  <Field name="response.reasoning_summary_text.delta" type="内容">
    推理摘要增量，需在 `include` 里要求才会出现。
  </Field>

  <Field name="response.completed" type="生命周期">
    结束，带完整的 `response` 对象与 `usage`。
  </Field>

  <Field name="response.failed / response.incomplete" type="生命周期">
    异常结束。**要处理这两种，否则失败会表现为「流断了但没报错」。**
  </Field>
</Fields>

## 参数改写规则

| 模型       | 触发条件                                                                    | 网关的动作                 |
| -------- | ----------------------------------------------------------------------- | --------------------- |
| `grok-*` | `tools` 里的 `web_search` 带 `external_web_access` 或 `search_context_size` | 删掉这两个字段（xAI 不支持），工具保留 |
| `grok-*` | `reasoning.effort` 为 `none`                                             | 改写为 `low`             |

Claude 系模型也有一组改写规则（`thinking`、`temperature`、`top_p`），见
[Messages](https://docs.vibeapi.cn/zh/docs/messages) 页——从本页调用 Claude 时同样适用。

## 分组差异

key 分两类：**`auto`**（可调用除 `claude-opus-5-5`、`claude-fable-5`、`claude-fable-5-1` 外的全部模型）和 **`Claude 官方满血版`**。
**对 GPT 系模型，两类 key 实测没有差异**——提示缓存与内置工具在两边都可用。
差异只出现在 Claude 系模型上，见 [Messages](https://docs.vibeapi.cn/zh/docs/messages) 页。

## 真实响应示例

下面是从生产网关真实抓取、脱敏后的流式响应（中间的增量事件已省略）：

<Example id="responses-stream" />

非流式的完整响应对象：

<Example id="responses-basic" />

## 能力边界

* **Claude 与 Gemini 系没有这个端点。** 原生入口分别是 [Messages](https://docs.vibeapi.cn/zh/docs/messages) 和
  Gemini 的 `generateContent`。
* **服务端存储类字段不保证可用**：`conversation`、`prompt`、`background` 依赖官方的
  服务端状态，本网关不提供对应的管理接口。
* **内置工具不保证可用**，也不保证与官方一致。
* **`reasoning_tokens` 不可用于对账。** 实测中这个字段多数情况下返回 `0`，即使
  `reasoning.effort` 设为 `high`。它反映的是该字段是否被上报，不代表模型没有推理，
  所以不要拿它核算推理成本。
* **非流式不适合推理模型。**

## 在线调试

填入你自己的 API Key 即可直接发起请求，参数表与响应结构由接口定义生成。

<APIPage document={"openapi/generated/ai-model/聊天（Chat）/原生OpenAI格式/post-v1-responses-createresponse-383826475.json"} operations={[{"path":"/v1/responses","method":"post"}]} />

## 官方文档

本页只写与本网关有关的部分，参数语义的权威定义以官方为准：

* [OpenAI · Responses Create](https://developers.openai.com/api/reference/resources/responses/methods/create)
* [OpenAI · 迁移到 Responses](https://developers.openai.com/api/docs/guides/migrate-to-responses)
* [OpenAI · 推理模型](https://developers.openai.com/api/docs/guides/reasoning)


# 文本对话概览

<HeroVideo src="https://studio.vibevibe.cn/docs/260915/docs-intro/video/chat.mp4" poster="https://studio.vibevibe.cn/docs/260915/docs-intro/poster/chat.webp" model="wan3.0-video-720p" />

网关地址 `https://www.vibeapi.cn/v1`，`Authorization: Bearer <API_KEY>`。文本对话有四套原生协议，按模型家族选它自己的那一套，功能最全；
跨协议调用是网关翻译的，只保证消息、流式和基本工具调用，协议特有字段（Claude 的 thinking 块、Gemini 的 thoughtSignature）会在翻译中丢失。

## 协议怎么选

| 模型家族                                       | 端点                                            | 页面                                                    | SDK                    |
| ------------------------------------------ | --------------------------------------------- | ----------------------------------------------------- | ---------------------- |
| GPT / Codex（`gpt-*`、`codex-*`）             | `POST /v1/responses`                          | [OpenAI Responses](https://docs.vibeapi.cn/zh/docs/responses)，推荐             | `openai`               |
| 同上，或任何模型的兼容调用                              | `POST /v1/chat/completions`                   | [OpenAI Chat Completions](https://docs.vibeapi.cn/zh/docs/chat)              | `openai`               |
| Claude（`claude-*`）                         | `POST /v1/messages`                           | [Claude Messages](https://docs.vibeapi.cn/zh/docs/messages)                  | `anthropic`            |
| Gemini（`gemini-*`）                         | `POST /v1beta/models/{model}:generateContent` | [Gemini generateContent](https://docs.vibeapi.cn/zh/docs/gemini)             | `google-genai`         |
| Grok（`grok-*`）                             | `/v1/chat/completions` 或 `/v1/responses`      | [Grok 对话](https://docs.vibeapi.cn/zh/docs/grok)                              | `openai`               |
| 国产（glm / kimi / qwen / deepseek / MiniMax） | `/v1/chat/completions` 或 `/v1/messages`       | [Chat](https://docs.vibeapi.cn/zh/docs/chat) / [Messages](https://docs.vibeapi.cn/zh/docs/messages) | `openai` / `anthropic` |

逐个模型的推荐入口、可用入口与最后验证日期见[模型与入口](https://docs.vibeapi.cn/zh/docs/models)。

## 建议默认流式

请求超时上限 **120 秒**。非流式请求在生成完成前没有任何数据下行，单次生成一旦超过这个时间，连接会被中断。
短输出不受影响；推理型号要等整段思考结束才返回首字节，容易触发。**生产环境建议默认开启流式**，需要完整文本时在客户端聚合
（OpenAI SDK `stream.get_final_response()`、Anthropic SDK `stream.get_final_message()`）。

## 返回 200 不等于参数生效

两类情况都返回 200，只看状态码发现不了：

**key 分组。** key 分 `auto`（可调用除 `claude-opus-5-5`、`claude-fable-5`、`claude-fable-5-1` 外的全部模型）和 `Claude 官方满血版` 两类。GPT 系在两类上实测没有差异；
Claude 系在 `auto` 上会静默忽略提示缓存、`max_tokens`、`stop_sequences`、结构化输出，`claude-sonnet-5` 不返回 thinking 块。
依赖这些约束的代码必须用官方满血 key。详见 [Claude Messages · 分组差异](https://docs.vibeapi.cn/zh/docs/messages#分组差异)。

**网关改写。** 对部分模型，网关会在转发前删除或改写参数：Claude 新型号的 `temperature` / `top_p` / `top_k` 与 `thinking.budget_tokens`，
Grok 在 Chat 接口上的内置 `web_search` 工具、Responses 上 `web_search` 的两个上游不支持的字段，以及 `reasoning.effort: none`。规则写在各页的「参数改写规则」小节。

判断依据是响应体——thinking 块在不在、`usage` 里有没有缓存字段、输出长度是否真的受 `max_tokens` 约束。

## 国产模型

glm / kimi / qwen / deepseek / MiniMax 两套协议都能调通，工具调用全部可用；`max_tokens`、停止序列、结构化输出的遵循程度逐模型不同，
`deepseek-v4-pro` 与 `kimi-k3` 不执行 `max_tokens` 却仍把结束原因报为已截断。逐项实测见[模型与入口 · 国产模型的协议兼容度](https://docs.vibeapi.cn/zh/docs/models#国产模型的协议兼容度)。

## 各页的固定结构

每个协议页按同一骨架组织：基本调用（curl / Python / Node.js）→ 认证与流式要求 → 请求参数（先官方定义，再「网关」实测标注）→ 响应字段与流式事件
→ 参数改写规则与分组差异 → 真实响应示例 → 能力边界 → 在线调试 → 官方文档。


# TypeSafe 判断型模型

`POST /v1/systemone`

TypeSafe 的 **System One** 模型（当前是 **Jev**，模型名 `jev-latest`）和对话模型不是一类东西：
你给它一份 **state**（要评估的内容）和若干个带类型的 **questions**，它对每个问题返回一个
**概率**，不返回文字。三种问题类型——**Noul**（是 / 否的概率）、**Choice**（在你定义的选项里选一个，
附完整概率分布）、**Score**（在你定义的有序档位上按概率加权打分）——覆盖了路由、分类、打分、抽取、
校验这一类「代码里需要一小块常识判断」的场景。它快（本网关实测单次 1 秒左右）、便宜、输出可直接进 `if`。

本页讲在本网关上怎么调：地址、请求响应结构、三种原语怎么选、confidence 怎么用、计费与限制、错误。
概念与更多模式以 [TypeSafe 官方文档](https://docs.typesafe.ai/) 为准。最后验证：2026-09-19。

## 给 AI 编程代理装 Skill

TypeSafe 官方给 Claude Code 等代理写了一份 skill，教代理怎么把「提示词 + 解析文本」改成结构化判断、
三种原语怎么选、怎么组合与验证。我们把它完整译成中文，加上了本网关的差异（端点、令牌、按次计费、不支持 `models.list()`），
并附上 API 参考、模型页的中文版和本页的 Markdown 版。

把这句话发给你的代理，它自己会装：

```text
帮我安装这个 Skill：https://docs.vibeapi.cn/typesafe-skill.zip
```

想手动装：解压得到 `typesafe/`（`SKILL.md`、`references/`、`VERSION`、`scripts/update.sh`），放进代理的 skills 目录。
它和主 skill 一样会自己检查更新，机制见[快速开始](https://docs.vibeapi.cn/zh/docs/quickstart#agent-skill)。
装了[VibeAPI 主 skill](https://docs.vibeapi.cn/zh/docs/quickstart#agent-skill) 的代理，也能从它的 `references/typesafe.md` 读到本页。

## 与官方的差异

官方 SDK 和文档里的代码**只改两处**就能用：`base_url` 指到本网关，`api_key` 换成 VibeAPI 的令牌。

|                 | 官方                                          | 本网关                                                        |
| --------------- | ------------------------------------------- | ---------------------------------------------------------- |
| 端点              | `https://api.typesafe.ai/v1/systemone`      | `https://www.vibeapi.cn/v1/systemone`                      |
| 认证              | TypeSafe 的 key                              | `Authorization: Bearer <VibeAPI 的 sk- 令牌>`，任意分组            |
| 模型              | `jev-latest` / `jev-preview` / `jev-1.13.0` | 只开放 **`jev-latest`**（三者当前指向同一个模型）                          |
| 计费              | 按输入 token                                   | **按次**：一次请求一个价，与 state 长度、问题数量、返回 token 无关                 |
| `models.list()` | 返回 TypeSafe 形状                              | **不支持**——本网关 `/v1/models` 是 OpenAI 形状，SDK 会报响应校验错误；模型名直接写死 |
| 请求校验            | 上游 422                                      | 网关先做一层结构校验返回 400，再由上游做语义校验（422 逐条透出）                       |

## 基本调用

<Tabs items={['curl', 'Python', 'Node.js']}>
  <Tab value="curl">
    ```bash
    curl https://www.vibeapi.cn/v1/systemone \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "jev-latest",
        "state": "Help! My payouts have been failing for 3 days.",
        "questions": {
          "is_urgent":   {"type": "noul",   "instructions": "Does this convey urgency?"},
          "department":  {"type": "choice", "instructions": "Which team should handle this?",
                          "criteria": {"billing": "Payments, invoicing, refunds",
                                       "technical": "Bugs, outages, integrations",
                                       "sales": "Pricing, upgrades, new accounts"}},
          "frustration": {"type": "score",  "instructions": "How frustrated is the customer?",
                          "criteria": ["Calm", "Frustrated", "Very angry"]}
        }
      }'
    ```
  </Tab>

  <Tab value="Python">
    ```python
    # pip install typesafe-sdk
    from typesafe_sdk import TypeSafeClient, Choice, Noul, Score

    client = TypeSafeClient(api_key="YOUR_API_KEY", base_url="https://www.vibeapi.cn")

    response = client.system_one(
        model="jev-latest",
        state={"document": "Help! My payouts have been failing for 3 days."},
        questions={
            "is_urgent": Noul(instructions="Does this convey urgency?"),
            "department": Choice(
                instructions="Which team should handle this?",
                criteria={"billing": "Payments, invoicing, refunds",
                          "technical": "Bugs, outages, integrations",
                          "sales": "Pricing, upgrades, new accounts"},
            ),
            "frustration": Score(
                instructions="How frustrated is the customer?",
                criteria=["Calm", "Frustrated", "Very angry"],
            ),
        },
    )

    print(response.model)                        # 实际应答版本，如 jev-1.13.0
    print(response.answers["is_urgent"].noul)    # 0.95
    dept = response.answers["department"]
    print(dept.choice, dept.confidence, dept.probabilities)
    print(response.answers["frustration"].score) # 1.05，落在 Frustrated 附近
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    // npm install @typesafe-ai/sdk   （Node.js 20+）
    import { TypeSafeClient, noul, choice, score } from "@typesafe-ai/sdk";

    const client = new TypeSafeClient({ apiKey: "YOUR_API_KEY", baseURL: "https://www.vibeapi.cn" });

    const response = await client.systemOne({
      model: "jev-latest",
      state: { document: "Help! My payouts have been failing for 3 days." },
      questions: {
        is_urgent: noul("Does this convey urgency?"),
        department: choice("Which team should handle this?", {
          billing: "Payments, invoicing, refunds",
          technical: "Bugs, outages, integrations",
          sales: "Pricing, upgrades, new accounts",
        }),
        frustration: score("How frustrated is the customer?", ["Calm", "Frustrated", "Very angry"]),
      },
    });

    console.log(response.answers.is_urgent.noul);          // 0.95
    console.log(response.answers.department.choice);       // "billing"
    console.log(response.answers.frustration.score);       // 1.05
    ```
  </Tab>
</Tabs>

上面这次请求在本网关的真实响应（2026-09-19）：

```json
{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent":   { "type": "noul", "noul": 0.95 },
    "department":  { "type": "choice", "choice": "billing", "confidence": 0.82,
                     "probabilities": { "billing": 0.88, "technical": 0.12, "sales": 0.0 } },
    "frustration": { "type": "score", "score": 1.05, "confidence": 0.93,
                     "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
                     "probabilities": { "0": 0.0, "1": 0.95, "2": 0.05 } }
  },
  "usage": { "input_tokens": 395, "output_tokens": 73 }
}
```

三个问题、一次请求、一次计费。SDK 也支持环境变量：`TYPESAFE_API_KEY` 填 VibeAPI 令牌，
`TYPESAFE_BASE_URL=https://www.vibeapi.cn`，`TYPESAFE_DEFAULT_MODEL=jev-latest`，然后 `TypeSafeClient()` 不传参。

## 请求结构

<Fields>
  <Field name="model" type="string" required>
    固定写 `jev-latest`。这是别名，始终指向 Jev 当前稳定版；响应的 `model` 字段会报告实际应答的版本号（如 `jev-1.13.0`），
    把它记进日志，方便日后对比。
  </Field>

  <Field name="state" type="string | object | array" required>
    要评估的内容。一段文字传字符串；有多个部分（消息、订单、策略）传**带名字字段的对象**，让每部分含义清楚、关系明确；
    一串消息或记录传数组。同一次请求里所有问题看到的是同一份 state，各自独立评估。

    **只接受文本。** 图片、音频、视频要先自己转成文字或结构化字段再放进来。英文是主要训练语言、准确率最高；
    中文能处理但官方自述「不同等」，中文场景先用自己的数据测一轮，路由时多看 confidence。
  </Field>

  <Field name="questions" type="object · key → Question" required>
    问题映射，key 由你定，答案在同一个 key 下返回。**key 不会发给模型**，问题的完整含义要写在 `instructions` 里。
    本网关要求至少 1 条、至多 256 条。
  </Field>
</Fields>

### 三种问题

每个问题都有 `type` 和 `instructions`，`criteria` 的形状因类型而异。

<Fields>
  <Field name="noul" type="是 / 否">
    `instructions` 写一个是 / 否问题；`criteria` 可选，`{"true": "是的含义", "false": "否的含义"}`。
    返回 `noul`：0（否）到 1（是）的概率。**没有 confidence**——接近 0.5 表示「是」「否」概率相近，不是「中等程度」。
    多个标签可能同时成立时，每个标签一个 noul，不要用 choice 单选。
  </Field>

  <Field name="choice" type="多选一" required>
    `criteria` **必填**，是 `{选项: 说明}` 的对象，说明可为 `null`，至少一个选项。
    返回 `choice`（概率最高的选项）、`probabilities`（每个选项的概率，总和为 1）、`confidence`。
    可能什么都不匹配时，自己加一个 `"other"` / `"none"` 选项——模型选不出你没给的值。
  </Field>

  <Field name="score" type="有序档位" required>
    `criteria` **必填**，是有序的档位描述数组，**至少两档**，每一档要描述一个具体、独立成立的情形。
    返回 `score`（按概率加权的位置，可落在两档之间，如 1.6）、`legend`（档位编号 → 描述）、`probabilities`（每档概率）、`confidence`。
    要给一批条目做分级排序，就给每个条目一个可比较的 score。
  </Field>
</Fields>

`instructions` 和 `criteria` 的值都接受字符串、对象或数组：简单问题用字符串；需要定义、对比、排除项或示例时用结构化写法。
引用 state 里的嵌套字段用反引号包路径，例如 `` `ticket.messages[0].text` ``。

## 响应结构

<Fields>
  <Field name="model" type="string">
    实际执行评估的模型版本号。
  </Field>

  <Field name="answers" type="object · key → Answer">
    每个问题一个答案，`type` 与问题一致。各类型的字段见上一节。
  </Field>

  <Field name="usage" type="object">
    `input_tokens` / `output_tokens`。原样透传，**不参与本网关计费**，可用来观察 state 有多长。
  </Field>
</Fields>

## 用 confidence 分流

Choice 和 Score 的 `confidence`（0–1）是把 `probabilities` 的集中程度压成的一个数：分布集中在一个选项上就高，摊开就低。
它衡量的是「模型对这一题有多确定」，不是整条业务流程的正确性，也不是「可以执行」的许可。一个常用起点是分三段：

```python
action = response.answers["action"]

if action.confidence < 0.5:
    route_to_human()                 # 模型真的不确定，别猜
elif action.choice == "check_balance":
    show_balance()                   # 低风险动作，错了可恢复，直接做
elif action.choice == "approve_transfer":
    if action.confidence > 0.9:
        confirm_then_execute()       # 高风险 + 高确定：带确认执行
    else:
        ask_user_to_confirm()        # 高风险 + 中等确定：先核实
```

阈值随风险走：同一套系统里，只读操作和破坏性操作用不同的门槛。数字要在你自己的数据上试出来，从保守开始。
几个都可接受的备选项也会把概率摊开——对无害的偏好选择，低 confidence 不一定作废。

## 一次问多个问题

一次请求评估一份 state、回答任意多个问题，问题之间并行、互不可见。**本网关按次计费，多问不加钱**，
所以把能一起问的都放进同一次请求，包括「如果是 A 分支，那 X 是多少」这类推测性问题——
把前提写进问题里，由代码只消费命中的分支。只有当前一个答案是取证据、构造新 state 或决定下一步选项的前提时，
才值得发第二次请求。

上限：一次请求 64k token（state + 全部问题），其中 state + 单个最长问题不超过 32k；问题数不超过 256。

## 计费与限制

| 项   | 值                                                                                                          |
| --- | ---------------------------------------------------------------------------------------------------------- |
| 计费  | **按次**，`jev-latest` 每次请求一个固定价，见[价格页](https://www.vibeapi.cn/pricing)。与 state 长度、问题数、token 数无关；`usage` 只是信息 |
| 失败  | 400 / 401 / 422 / 429 / 5xx **不计费**                                                                        |
| 上下文 | 64k token / 请求；state + 最长问题 ≤ 32k                                                                          |
| 问题数 | 1–256 条 / 请求                                                                                               |
| 输入  | 仅文本；英文最佳，中文可用但先测                                                                                           |
| 超时  | 非流式、单次实测约 1 秒，不受对话模型 120 秒流式建议的影响                                                                          |
| 限流  | 按令牌 / 模型限流，超限 429；上游过载 529。用官方 SDK 自带退避重试，直接调 HTTP 自己做指数退避                                                 |

## 错误速查

| 状态                                        | 现象                                                                         | 先查                                                                                                                                 |
| ----------------------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| 400                                       | `question "q": score criteria must contain at least two levels` 之类         | 网关本地校验：`state` / `model` / `questions` 必填；`type` 只认 `noul` / `choice` / `score`；`choice` 的 `criteria` 非空对象；`score` 至少两档；问题 ≤ 256 条 |
| 401                                       | `Invalid token`                                                            | 用的是 VibeAPI 的 sk- 令牌吗（不是 TypeSafe 的 key）；Anthropic / OpenAI SDK 那种带 `/v1` 的 base\_url 在这里**不要带**                                   |
| 422                                       | `questions/q/choice/instructions/str: Input should be a valid string; ...` | 上游校验：字段类型不对（如 `instructions` 传了数字、`criteria` 的值不是字符串）。路径用 `/` 分隔指到出错的字段                                                            |
| 429 / 529                                 | 限流 / 上游过载                                                                  | 退避重试                                                                                                                               |
| SDK 报 `Invalid response data at 'models'` | 调了 `models.list()`                                                         | 本网关不支持这个方法，模型名写死 `jev-latest`                                                                                                      |
| 503 `No available channel for model ...`  | 模型名写错                                                                      | 只有 `jev-latest`                                                                                                                    |

## 官方文档

概念、更多模式与 cookbook 以官方为准，Mintlify 站在路径后加 `.md` 可拿 Markdown：

* [文档索引](https://docs.typesafe.ai/llms.txt) · [System One 是什么](https://docs.typesafe.ai/concepts/system-one) · [如何用 TypeSafe 构建](https://docs.typesafe.ai/concepts/how-to-build-with-system-one)
* [State](https://docs.typesafe.ai/concepts/state) · [原语](https://docs.typesafe.ai/primitives)：[Choice](https://docs.typesafe.ai/primitives/choice) / [Noul](https://docs.typesafe.ai/primitives/noul) / [Score](https://docs.typesafe.ai/primitives/score) · [Confidence](https://docs.typesafe.ai/confidence)
* [HTTP API](https://docs.typesafe.ai/api) · [Python SDK](https://docs.typesafe.ai/sdk/python) · [JavaScript SDK](https://docs.typesafe.ai/sdk/javascript)
* 模式：[推测性扇出](https://docs.typesafe.ai/patterns/fan-out) · [复合打分](https://docs.typesafe.ai/patterns/composite-scoring) · [用例地图](https://docs.typesafe.ai/concepts/use-case-map)


# MiniMax H3

`POST /v1/videos`，`model` 为 `MiniMax-H3`。按秒计费，见[视频生成](https://docs.vibeapi.cn/zh/docs/videos#模型与计费)。本页结论来自对本网关的真实调用，最后验证：2026-10-26。

## 基本调用

<Tabs items={['curl', 'Python', 'Node.js']}>
  <Tab value="curl">
    ```bash
    # 1. 提交
    curl https://www.vibeapi.cn/v1/videos \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "MiniMax-H3",
        "prompt": "日出时分的海面，镜头极缓慢推进，电影级布光",
        "seconds": "5",
        "aspect_ratio": "16:9"
    }'

    # 2. 轮询（每 10~15 秒一次）
    curl "https://www.vibeapi.cn/v1/videos/$TASK_ID" -H "Authorization: Bearer $API_KEY"

    # 3. 取片
    curl -L "https://www.vibeapi.cn/v1/videos/$TASK_ID/content" \
      -H "Authorization: Bearer $API_KEY" -o output.mp4
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import time, requests

    BASE = "https://www.vibeapi.cn/v1"
    H = {"Authorization": "Bearer YOUR_API_KEY"}

    task = requests.post(f"{BASE}/videos", headers=H, json={
        "model": "MiniMax-H3",
        "prompt": "日出时分的海面，镜头极缓慢推进，电影级布光",
        "seconds": "5",
        "aspect_ratio": "16:9",
    }).json()

    while True:
        s = requests.get(f"{BASE}/videos/{task['id']}", headers=H).json()
        if s["status"] in ("completed", "failed"):
            break
        time.sleep(12)

    if s["status"] == "completed":
        url = s.get("metadata", {}).get("url") or f"{BASE}/videos/{task['id']}/content"
        open("output.mp4", "wb").write(requests.get(url, headers=H).content)
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    import fs from "fs";

    const BASE = "https://www.vibeapi.cn/v1";
    const H = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };
    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

    const task = await (await fetch(`${BASE}/videos`, {
      method: "POST",
      headers: H,
      body: JSON.stringify({
        model: "MiniMax-H3",
        prompt: "日出时分的海面，镜头极缓慢推进，电影级布光",
        seconds: "5",
        aspect_ratio: "16:9",
      }),
    })).json();

    let s;
    while (true) {
      s = await (await fetch(`${BASE}/videos/${task.id}`, { headers: H })).json();
      if (s.status === "completed" || s.status === "failed") break;
      await sleep(12_000);
    }

    if (s.status === "completed") {
      const url = s.metadata?.url ?? `${BASE}/videos/${task.id}/content`;
      fs.writeFileSync("output.mp4", Buffer.from(await (await fetch(url, { headers: H })).arrayBuffer()));
    }
    ```
  </Tab>
</Tabs>

按秒计费，固定 768P，整数 1–15 秒。特点是**参考素材的种类最全**：图、视频、音频三类
可以同时给，提示词里用 `<Picture 1>` `<Video 1>` `<Audio 1>` 按顺序引用。

## 参数

| 字段                  | 类型        | 必填 | 说明                                                        |
| ------------------- | --------- | -- | --------------------------------------------------------- |
| `model`             | string    | 是  | 固定 `MiniMax-H3`                                           |
| `prompt`            | string    | 是  | 最长 7000 字符                                                |
| `seconds`           | string    | 建议 | 输出时长，整数 1–15；也接受数字型 `duration`。不传按 5 秒                    |
| `aspect_ratio`      | string    | 否  | `21:9` `16:9`（默认）`4:3` `1:1` `3:4` `9:16`，另见下方 `adaptive` |
| `image_urls`        | string\[] | 否  | 参考图，最多 9 张，顺序即 `<Picture N>` 编号                           |
| `first_frame_image` | string    | 否  | 首帧图，也可以用 `input_reference`                                |
| `last_frame_image`  | string    | 否  | 尾帧图                                                       |
| `video_urls`        | string\[] | 否  | 参考视频，最多 3 条                                               |
| `audio_urls`        | string\[] | 否  | 参考音频，最多 3 个                                               |

**分辨率不用传**，固定 768P，传了也不生效。

`adaptive` 比例只在**带了参考图或参考视频**时可用——它的意思是跟着视觉输入定画布，
纯文生和纯音频请求没有可跟的对象，会直接报错。

三类参考素材**合计不超过 12 个**，且每一类各有上限。

首尾帧和参考图二选一：给了 `first_frame_image` / `last_frame_image` 就不能再给 `image_urls`。

## 图片传 base64

所有图片字段都可以传公网 HTTPS 地址，也可以直接传 base64，带不带 `data:image/png;base64,` 前缀都行。
参考视频和参考音频只收 HTTPS 地址。

```bash
IMG=$(base64 -w0 cat.jpg)   # macOS 用 base64 -i cat.jpg
curl https://www.vibeapi.cn/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "小猫慢慢抬起头，看向镜头",
    "seconds": "5",
    "aspect_ratio": "adaptive",
    "first_frame_image": "'"$IMG"'"
  }'
```

用 OpenAI SDK 上传本地文件也可以：multipart 表单里的 `input_reference` 文件，第一张作首帧、第二张作尾帧，单张不超过 20 MB。

```python
from openai import OpenAI

client = OpenAI(base_url="https://www.vibeapi.cn/v1", api_key="YOUR_API_KEY")
video = client.videos.create(
    model="MiniMax-H3",
    prompt="小猫慢慢抬起头，看向镜头",
    seconds="5",
    input_reference=open("cat.jpg", "rb"),
)
```

## 多参考素材

```bash
curl https://www.vibeapi.cn/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "MiniMax-H3",
    "prompt": "<Picture 1> 中的人物，按 <Video 1> 的运镜节奏，配合 <Audio 1> 的节拍",
    "seconds": "8",
    "aspect_ratio": "adaptive",
    "image_urls": ["https://your-cdn.example.com/person.jpg"],
    "video_urls": ["https://your-cdn.example.com/motion.mp4"],
    "audio_urls": ["https://your-cdn.example.com/beat.mp3"]
  }'
```

参考视频和参考音频必须是公网可直接下载的 HTTPS 地址；图片也可以传 base64，见上一节。

## 已知限制（截至 2026-10-26）

| 限制                      | 说明                                             | 怎么办                                                                  |
| ----------------------- | ---------------------------------------------- | -------------------------------------------------------------------- |
| **固定 768P**             | 没有分辨率参数，传了不生效                                  | 要 1080p 用万相或 Seedance                                                |
| **`adaptive` 有条件**      | 只在带了参考图或参考视频时可用，纯文生 / 纯音频请求 400                | 纯文生传固定比例                                                             |
| **参考视频 / 音频超 15 秒只取片头** | 各自累计不得超过 15 秒，超了任务失败                           | 先自己剪                                                                 |
| **出片时间**                | 4.5–10 分钟，15 秒的更久                              | 轮询超时按 20 分钟设；曾出现上游已完成但状态停在「生成中」的情况，2026-09-15 起已修复，若再遇到请把任务 ID 反馈给我们 |
| **取片地址**                | `metadata.url` 是本站 `/content` 代理地址，带同一个 key 下载 | 视频不长期保存，取到就落盘                                                        |

## 商业方向样片

所有底图都是用 `gpt-image-2.5-sunburst` 出的（横版 2560×1440、竖版 1440×2560），
再作为首帧 / 参考图交给本页模型，提示词只写运镜与动态。成片保留原始音轨。

H3 是四个系列里唯一**允许人物入镜**且不卡人脸的，餐饮、服装这类要有人的方向优先用它；
固定 768P，横版 1344×768、竖版 768×1344。

<SampleVideos items={[{"src": "https://studio.vibevibe.cn/docs/260915/biz/video/coffee.mp4", "poster": "https://studio.vibevibe.cn/docs/260915/biz/poster/coffee.webp", "caption": "餐饮 · 咖啡拉花 · MiniMax-H3 · 8 s", "portrait": false}, {"src": "https://studio.vibevibe.cn/docs/260915/biz/video/fashion-h3.mp4", "poster": "https://studio.vibevibe.cn/docs/260915/biz/poster/fashion-h3.webp", "caption": "服装 · 沙丘长裙 · MiniMax-H3 · 8 s", "portrait": true}]} />

## 素材限制

| 素材 |     数量 |   单文件 | 时长                        |
| -- | -----: | ----: | ------------------------- |
| 图片 | 最多 9 张 | 30 MB | 不适用                       |
| 视频 | 最多 3 条 | 50 MB | 单条最短 2 秒；超过 15 秒只取片头 15 秒 |
| 音频 | 最多 3 个 | 15 MB | 单个最短 2 秒；超过 15 秒只取片头 15 秒 |

图片还需满足：单边 256–5760 像素，宽高比 0.4–2.5，不能是动图。

**参考视频与参考音频裁切后各自累计不得超过 15 秒**，超了任务会失败。
被裁切**不影响输出时长**，你请求几秒就出几秒。

## 会被当场拒绝的写法

这些在提交时就返回 400，不会创建任务、不产生费用：

| 写法                           | 报错                                                               |
| ---------------------------- | ---------------------------------------------------------------- |
| 时长写 0、负数或超过 15               | `duration must be an integer between 1 and 15 seconds`           |
| 比例不在六档之内                     | `unsupported ratio ...`                                          |
| 纯文生或纯音频用 `adaptive`          | `ratio adaptive requires at least one image or video input`      |
| 参考图超过 9 张                    | `at most 9 images are accepted`                                  |
| 参考视频或音频超过 3 个                | `at most 3 reference videos/audios are accepted`                 |
| 三类合计超过 12 个                  | `at most 12 media items are accepted in total`                   |
| 首尾帧和参考图同时给                   | `first_frame/last_frame cannot be combined with reference_image` |
| `input_reference` 上传超过 2 个文件 | `at most 2 input_reference files are accepted`                   |

素材本身的问题（下载不到、格式不对、时长不够）**要等异步阶段才知道**，
表现为任务进入 `failed`，此时全额退款。


# Seedance

`POST /v1/videos`，`model` 为 `doubao-seedance-2-5-260628` / `doubao-seedance-2-0-260128` /
`doubao-seedance-2-0-fast-260128` / `doubao-seedance-2-0-mini-260615`（就是字节官方的模型 ID）。
**按 token 计费**，时长和分辨率直接决定价格，见[计费](#计费)。本页结论来自对本网关的真实调用，最后验证：2026-09-21。

<Callout type="warn" title="旧的一口价型号已下线">
  `seedance-2.5` / `seedance-2.5-plus` / `seedance-2.5-pro` / `seedance-2.0` 四个一口价模型名的上游已停供，
  提交会返回 `model_not_found`。改用本页的官方模型 ID：请求字段完全一样，多传一个 `resolution`，
  计费从一口价变成按时长 × 分辨率算。
</Callout>

## 基本调用

<Tabs items={['curl', 'Python', 'Node.js']}>
  <Tab value="curl">
    ```bash
    # 1. 提交
    curl https://www.vibeapi.cn/v1/videos \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "doubao-seedance-2-5-260628",
        "prompt": "中国水墨动画。鲲化为鹏，自暴风怒海中腾空而起，双翼横贯画面，翼尖化入云雾。大量留白，湿笔在宣纸上缓缓洇开，单色水墨仅带一点淡赭",
        "duration": 10,
        "resolution": "720p",
        "aspect_ratio": "16:9"
    }'

    # 2. 轮询（每 10~15 秒一次）
    curl "https://www.vibeapi.cn/v1/videos/$TASK_ID" -H "Authorization: Bearer $API_KEY"

    # 3. 取片
    curl -L "https://www.vibeapi.cn/v1/videos/$TASK_ID/content" \
      -H "Authorization: Bearer $API_KEY" -o output.mp4
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import time, requests

    BASE = "https://www.vibeapi.cn/v1"
    H = {"Authorization": "Bearer YOUR_API_KEY"}

    task = requests.post(f"{BASE}/videos", headers=H, json={
        "model": "doubao-seedance-2-5-260628",
        "prompt": "中国水墨动画。鲲化为鹏，自暴风怒海中腾空而起，双翼横贯画面，翼尖化入云雾。大量留白，湿笔在宣纸上缓缓洇开，单色水墨仅带一点淡赭",
        "duration": 10,
        "resolution": "720p",
        "aspect_ratio": "16:9",
    }).json()

    while True:
        s = requests.get(f"{BASE}/videos/{task['id']}", headers=H).json()
        if s["status"] in ("completed", "failed"):
            break
        time.sleep(12)

    if s["status"] == "completed":
        url = s.get("metadata", {}).get("url") or f"{BASE}/videos/{task['id']}/content"
        open("output.mp4", "wb").write(requests.get(url, headers=H).content)
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    import fs from "fs";

    const BASE = "https://www.vibeapi.cn/v1";
    const H = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };
    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

    const task = await (await fetch(`${BASE}/videos`, {
      method: "POST",
      headers: H,
      body: JSON.stringify({
        model: "doubao-seedance-2-5-260628",
        prompt: "中国水墨动画。鲲化为鹏，自暴风怒海中腾空而起，双翼横贯画面，翼尖化入云雾。大量留白，湿笔在宣纸上缓缓洇开，单色水墨仅带一点淡赭",
        duration: 10,
        resolution: "720p",
        aspect_ratio: "16:9",
      }),
    })).json();

    let s;
    while (true) {
      s = await (await fetch(`${BASE}/videos/${task.id}`, { headers: H })).json();
      if (s.status === "completed" || s.status === "failed") break;
      await sleep(12_000);
    }

    if (s.status === "completed") {
      const url = s.metadata?.url ?? `${BASE}/videos/${task.id}/content`;
      fs.writeFileSync("output.mp4", Buffer.from(await (await fetch(url, { headers: H })).arrayBuffer()));
    }
    ```
  </Tab>
</Tabs>

## 四个型号

四个都是字节官方型号，能力和上限就是官方文档写的那套。差别在**时长上限、分辨率档位、参考素材数量和价格**：

|            | `doubao-seedance-2-5-260628` | `doubao-seedance-2-0-260128` | `doubao-seedance-2-0-fast-260128` | `doubao-seedance-2-0-mini-260615` |
| ---------- | ---------------------------- | ---------------------------- | --------------------------------- | --------------------------------- |
| 时长         | 4–30 秒                       | 4–15 秒                       | 4–15 秒                            | 4–15 秒                            |
| 分辨率        | 720p · 1080p                 | 720p · 1080p                 | 720p                              | 720p                              |
| 参考图        | 最多 30 张                      | 最多 9 张                       | 最多 9 张                            | 最多 9 张                            |
| 参考视频       | 最多 10 条，总时长 ≤ 30 秒           | 最多 3 条，总时长 ≤ 15 秒            | 同 2.0                             | 同 2.0                             |
| 参考音频       | 最多 10 段，总时长 ≤ 30 秒；**可只传音频** | 最多 3 段，总时长 ≤ 15 秒；不能只传音频     | 同 2.0                             | 同 2.0                             |
| 首尾帧        | 支持                           | 支持                           | 支持                                | 支持                                |
| 有声视频       | 总带音轨                         | 总带音轨                         | 总带音轨                              | 总带音轨                              |
| 720p 每秒参考价 | 约 ¥1.5                       | 约 ¥1.0                       | 约 ¥0.8                            | 约 ¥0.5                            |

怎么选：**要 30 秒连贯长片、要 1080p、素材多，用 2.5**；产品展示、短镜头、成本敏感用 **2.0 Mini**（最便宜，出片也最快）；
2.0 Fast 是 Mini 和 2.0 之间的档；2.0 标准版比 2.5 便宜三成、支持 1080p，但最长 15 秒。
素材审核：**公众人物、政治人物等敏感内容的参考图会被拒**（错误 `InputImageSensitiveContentDetected`，自动全额退款）；普通真人肖像 2026-09-21 实测可以通过，但官方仍标注不保证，接入时预留一次重试。

## 参数

| 参数                         | 类型         | 说明                                                                                        |
| -------------------------- | ---------- | ----------------------------------------------------------------------------------------- |
| `model`                    | string     | 四个官方模型 ID 之一                                                                              |
| `prompt`                   | string     | 描述画面与运镜；引用参考素材用 `@Image1` / `@Video1` / `@Audio1` 这样的编号                                   |
| `duration`                 | **number** | 秒。2.5 为 4–30，2.0 系列为 4–15；**不传按 5 秒**。每一秒都计费，别再习惯性用满                                      |
| `resolution`               | string     | `720p`（默认）或 `1080p`；1080p 只有 2.5 和 2.0 标准版有。`480p` / `4k` 不开放，传了 400                      |
| `aspect_ratio`             | string     | `16:9` `4:3` `1:1` `3:4` `9:16` `21:9`，或 `adaptive`（跟随首帧 / 参考视频）；不传时上游按素材自适应，纯文生视频默认 16:9 |
| `image_urls`               | string\[]  | 参考图直链数组，上限见上表；等价写法 `images`                                                               |
| `video_urls`               | string\[]  | 参考视频直链数组，mp4 / mov，单条 2–30 秒（2.0 系列 2–15 秒），≤ 200 MB                                      |
| `audio_urls`               | string\[]  | 参考音频直链数组，wav / mp3，单段 2–30 秒（2.0 系列 2–15 秒），≤ 15 MB                                       |
| `reference_images`         | object\[]  | `[{url, role}]`，`role` 取 `reference_image` / `first_frame` / `last_frame`；首尾帧只能走这个字段      |
| `input_reference`          | string     | 单张图作首帧，等价于 `reference_images: [{url, role: "first_frame"}]`                               |
| `generate_audio`           | boolean    | 是否生成同步音轨，默认 `true`。**当前传 `false` 不生效，成片总带音轨**（2026-09-21 实测），要无声自己去掉音轨                    |
| `watermark`                | boolean    | 是否加水印，默认 `false`                                                                          |
| `seed`                     | number     | 随机种子，同种子同提示词结果接近                                                                          |
| `omni_reference_task_type` | string     | 仅 2.5：`reference`（参考生视频，默认由模型判定）；`edit` / `extend` 两类子任务本接口暂不开放                           |

`size` 传 `1280x720` / `1920x1080` 也会被归到对应档位；`resolution` 与 `size` 同时给时以 `resolution` 为准。

### 首尾帧 vs 参考图

首尾帧（`first_frame` / `last_frame`）和参考图（`reference_image`）是**两种互斥的任务**，不能同时出现，
首帧尾帧各只能一张。要"首帧锁构图 + 多张参考"，把首帧那张放进 `image_urls[0]`，在提示词里写明 `@Image1 作为开场画面`。

```json
{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "从首帧的日出海面缓慢推进到尾帧的黄昏渔港，光线连续变化",
  "duration": 8,
  "resolution": "1080p",
  "reference_images": [
    { "url": "https://example.com/sunrise.png", "role": "first_frame" },
    { "url": "https://example.com/dusk.png", "role": "last_frame" }
  ]
}
```

## 传多张参考素材，以及在提示词里点名

三个数组都是**顺序即编号**：`image_urls[0]` 就是 `@Image1`，`image_urls[1]` 是 `@Image2`，
视频与音频同理是 `@Video1`、`@Audio1`。提示词里不点名时模型会自行参考全部素材，
点名之后它才知道"主体用哪张、场景用哪张、节奏跟哪段音频"。

```bash
curl https://www.vibeapi.cn/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-5-260628",
    "prompt": "@Image1 里的机器人走进 @Image2 的老街，步态参考 @Video1，动作节奏跟随 @Audio1 的鼓点，黄昏光线保持不变，镜头跟随背影缓缓推进",
    "duration": 12,
    "resolution": "720p",
    "aspect_ratio": "16:9",
    "image_urls": ["https://example.com/robot.png", "https://example.com/old-street.png"],
    "video_urls": ["https://example.com/walk-cycle.mp4"],
    "audio_urls": ["https://example.com/drums.mp3"]
  }'
```

几条实测经验：

* **主体放第一张**。素材没点名时模型偏向把 `@Image1` 当主角，其余当场景 / 风格。
* 素材链接必须是**公网可直接下载的 HTTPS 直链**，签名 URL 要保证任务期间不过期。图片 jpeg / png / webp，边长 300–6000 px，≤ 30 MB。
* 比例、时长只用参数控制，**不要写进提示词**（"竖屏" "8 秒" 会和参数冲突）。
* 带参考视频的任务**单价更低**（见下），但参考视频的秒数会计入 token，总价未必更便宜。
* 2.0 系列不能只传音频，至少配一张图或一条视频；2.5 可以只传音频。
* 素材数量、时长、分辨率超出型号上限时，提交阶段直接 HTTP 400，不扣费。
* 参考图含公众人物会在异步阶段被审核拒掉；普通人像可以过（实测 1 例），仍按可能重试来设计。

## 计费

按 token 计，**与字节官方（火山方舟）刊例同价**，单价按「输出分辨率」和「输入是否含参考视频」分档；
分辨率越高、时长越长，token 越多：

```
token ≈ (参考视频总秒数 + 输出秒数) × 输出宽 × 输出高 × 24 / 1024
```

准确数以任务完成后上游返回的 `usage.total_tokens` 为准；提交时按预估预扣，完成后按实际 token **多退少补**，失败全额退回。
单价见 [https://www.vibeapi.cn/pricing](https://www.vibeapi.cn/pricing) ；下面是官方给的每条参考价（16:9，5 秒，不含参考视频），方便估算：

| 分辨率   | 2.5             | 2.0             | 2.0 Fast       | 2.0 Mini       |
| ----- | --------------- | --------------- | -------------- | -------------- |
| 720p  | ¥7.56（¥1.51/秒）  | ¥4.97（¥0.99/秒）  | ¥4.00（¥0.80/秒） | ¥2.48（¥0.50/秒） |
| 1080p | ¥18.71（¥3.74/秒） | ¥12.39（¥2.48/秒） | —              | —              |

时长线性外推：2.5 720p 30 秒约 ¥45，1080p 30 秒约 ¥112。
带参考视频时 token 单价降到六成左右，但参考视频时长计入 token。

### 已知限制（2026-09-21 实测）

| 限制                  | 说明                                                                                    | 怎么办                                  |
| ------------------- | ------------------------------------------------------------------------------------- | ------------------------------------ |
| **成片总带音轨**          | `generate_audio: false` 当前不生效，成片音轨与默认一样大                                              | 要无声在自己那边去掉音轨；修好会在本页更新                |
| **1080p 按更高单价计**    | 720p 与 1080p 是两档单价，1080p 每百万 token 约贵 10%，token 数还是 720p 的 2.25 倍                     | 预览用 720p，定稿再出 1080p                  |
| **取片速度不稳**          | 同样几 MB 的成片，`/content` 有时 4–8 秒，有时一分钟                                                  | 下载超时按 3 分钟设，失败重试同一个地址即可，不要重新提交任务     |
| **只有 720p / 1080p** | 不接受 `480p` 与 `4k`，传了直接 400                                                            | —                                    |
| **不支持视频编辑 / 延长**    | 2.5 的 `edit` / `extend` 子任务需要 `duration: -1`，本接口只接受 4–30 的整数秒                         | 只做参考生视频；要编辑先把原片当 `video_urls` 参考重新生成 |
| **敏感内容素材会被拒**       | 公众人物 / 政治人物肖像提交约 2 分钟后 `failed`（`InputImageSensitiveContentDetected`），全额退款；普通真人肖像实测可过 | 换素材；人物类需求预留一次重试                      |

### 实测样本（2026-09-21）

| 请求                                                    | 成片                       | 用时     | 实扣                              |
| ----------------------------------------------------- | ------------------------ | ------ | ------------------------------- |
| Mini · 720p · 6 秒 · 9:16 · 1 图 + 1 条 10 秒参考视频 + 1 段音频 | 720×1280，6.05 秒，有音轨      | 6.3 分钟 | ¥4.85（参考视频 10 秒计入 token，按含视频单价） |
| 2.0 · 1080p · 5 秒 · 首尾帧                               | 1920×1080，5.04 秒         | 7.2 分钟 | ¥12.50（官方参考价 ¥12.39）            |
| 2.5 · 720p · 5 秒 · `input_reference` 竖版首帧             | 720×1280（跟随首帧自适应），5.06 秒 | 9.0 分钟 | ¥7.29（官方参考价 ¥7.56）              |
| Mini · 720p · 5 秒 · 纯文生                               | 1280×720，5.06 秒          | 5.7 分钟 | ¥2.50（官方参考价 ¥2.48）              |

轮询超时按 20 分钟设；一次生成 5–9 分钟，2.5 与 1080p 偏慢。

### 响应

提交返回 `{"id": "task_…", "status": "queued"}`；`GET /v1/videos/{id}` 轮询到 `completed` 后，
`metadata.url` 指向 `/v1/videos/{id}/content`，带 `Authorization` 取片。完整流程与错误码见[视频生成](https://docs.vibeapi.cn/zh/docs/videos#轮询与取片)。

## 逐型号示例

### `doubao-seedance-2-5-260628` · 30 秒长片 · 1080p

```json
{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "@Image1 的水墨群山，云海缓缓流动，一叶扁舟自左向右穿过江面，镜头极缓慢推进，大量留白",
  "duration": 30,
  "resolution": "1080p",
  "aspect_ratio": "16:9",
  "image_urls": ["https://example.com/ink-mountains.png"]
}
```

### `doubao-seedance-2-0-260128` · 多图 + 参考视频 + 参考音频

```json
{
  "model": "doubao-seedance-2-0-260128",
  "prompt": "@Image1 里的机器人走进 @Image2 的老街，步态参考 @Video1，动作节奏跟随 @Audio1 的鼓点",
  "duration": 10,
  "resolution": "720p",
  "aspect_ratio": "16:9",
  "image_urls": ["https://example.com/robot.png", "https://example.com/old-street.png"],
  "video_urls": ["https://example.com/walk-cycle.mp4"],
  "audio_urls": ["https://example.com/drums.mp3"]
}
```

### `doubao-seedance-2-0-mini-260615` · 产品静物 · 最省

```json
{
  "model": "doubao-seedance-2-0-mini-260615",
  "prompt": "@Image1 的产品在转盘上缓慢旋转一周，柔光，背景保持纯色，节奏跟随 @Audio1",
  "duration": 6,
  "resolution": "720p",
  "aspect_ratio": "1:1",
  "image_urls": ["https://example.com/product.png"],
  "audio_urls": ["https://example.com/beat.mp3"]
}
```

## 样片

下面的样片来自本站早前的 Seedance 2.5 / 2.0 线路，画面能力与现在的官方型号一致（同一底层模型），仅计费口径不同。
所有底图都是用 `gpt-image-2.5-sunburst` 出的（横版 2560×1440、竖版 1440×2560），再作为参考图交给视频模型，提示词只写运镜与动态。

<SampleVideos items={[{"src": "https://studio.vibevibe.cn/docs/260915/biz/video/skincare-r.mp4", "poster": "https://studio.vibevibe.cn/docs/260915/biz/poster/skincare-r.webp", "caption": "美妆 · 精华液水花 · Seedance 2.5 · 10 s", "portrait": false}, {"src": "https://studio.vibevibe.cn/docs/260915/biz/video/perfume.mp4", "poster": "https://studio.vibevibe.cn/docs/260915/biz/poster/perfume.webp", "caption": "美妆 · 香水花瓣 · Seedance 2.5 · 10 s", "portrait": true}, {"src": "https://studio.vibevibe.cn/docs/260915/biz/video/evcar-plus.mp4", "poster": "https://studio.vibevibe.cn/docs/260915/biz/poster/evcar-plus.webp", "caption": "汽车 · 海岸公路 · Seedance 2.5 · 10 s", "portrait": false}, {"src": "https://studio.vibevibe.cn/docs/260915/biz/video/drink-plus.mp4", "poster": "https://studio.vibevibe.cn/docs/260915/biz/poster/drink-plus.webp", "caption": "饮品 · 冰块入杯 · Seedance 2.5 · 10 s", "portrait": true}, {"src": "https://studio.vibevibe.cn/docs/260915/biz/video/sneaker-pro.mp4", "poster": "https://studio.vibevibe.cn/docs/260915/biz/poster/sneaker-pro.webp", "caption": "运动鞋 · 雨夜悬浮 · Seedance 2.5 · 10 s", "portrait": false}, {"src": "https://studio.vibevibe.cn/docs/260915/biz/video/jewelry-pro-r.mp4", "poster": "https://studio.vibevibe.cn/docs/260915/biz/poster/jewelry-pro-r.webp", "caption": "珠宝 · 钻戒微距 · Seedance 2.5 · 10 s", "portrait": true}, {"src": "https://studio.vibevibe.cn/docs/260915/biz/video/headphones.mp4", "poster": "https://studio.vibevibe.cn/docs/260915/biz/poster/headphones.webp", "caption": "3C · 耳机爆炸图合体 · Seedance 2.0 · 8 s", "portrait": false}, {"src": "https://studio.vibevibe.cn/docs/260915/biz/video/jewelry-20.mp4", "poster": "https://studio.vibevibe.cn/docs/260915/biz/poster/jewelry-20.webp", "caption": "珠宝 · 钻戒微距 · Seedance 2.0 · 8 s", "portrait": true}]} />

### 文生视频样片

<div className="not-prose my-6 grid gap-4 sm:grid-cols-2">
  <figure className="m-0">
    <video src="https://studio.vibevibe.cn/docs/20260904/video-models/video/kunpeng-sd25.mp4" controls loop playsInline preload="none" className="w-full rounded-lg border border-fd-border" />

    <figcaption className="mt-2 text-center text-xs text-fd-muted-foreground">
      鲲鹏水墨
    </figcaption>
  </figure>

  <figure className="m-0">
    <video src="https://studio.vibevibe.cn/docs/20260904/video-models/video/nuwa-sd25.mp4" controls loop playsInline preload="none" className="w-full rounded-lg border border-fd-border" />

    <figcaption className="mt-2 text-center text-xs text-fd-muted-foreground">
      女娲补天
    </figcaption>
  </figure>

  <figure className="m-0">
    <video src="https://studio.vibevibe.cn/docs/20260904/video-models/video/dunhuang-sd25.mp4" controls loop playsInline preload="none" className="w-full rounded-lg border border-fd-border" />

    <figcaption className="mt-2 text-center text-xs text-fd-muted-foreground">
      敦煌飞天
    </figcaption>
  </figure>
</div>

以上三条为 Seedance 2.5 文生视频，30 秒，早期样片没有音轨。


# 可灵 4.0

`POST /v1/videos`，`model` 为 `kling-4.0-720p` 或 `kling-4.0-1080p`。
**分辨率写在模型名里**，请求体里的 `resolution` / `size` 会被模型名覆盖。按秒计费，见[视频生成](https://docs.vibeapi.cn/zh/docs/videos#模型与计费)。本页结论来自对本网关的真实调用，最后验证：2026-10-31。

## 基本调用

<Tabs items={['curl', 'Python', 'Node.js']}>
  <Tab value="curl">
    ```bash
    # 1. 提交
    curl https://www.vibeapi.cn/v1/videos \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "kling-4.0-720p",
        "prompt": "一只橘猫在草地上追蝴蝶，阳光柔和，镜头缓慢跟随",
        "duration": 5,
        "aspect_ratio": "16:9"
    }'

    # 2. 轮询（每 10~15 秒一次）
    curl "https://www.vibeapi.cn/v1/videos/$TASK_ID" -H "Authorization: Bearer $API_KEY"

    # 3. 取片
    curl -L "https://www.vibeapi.cn/v1/videos/$TASK_ID/content" \
      -H "Authorization: Bearer $API_KEY" -o output.mp4
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import time, requests

    BASE = "https://www.vibeapi.cn/v1"
    H = {"Authorization": "Bearer YOUR_API_KEY"}

    task = requests.post(f"{BASE}/videos", headers=H, json={
        "model": "kling-4.0-720p",
        "prompt": "一只橘猫在草地上追蝴蝶，阳光柔和，镜头缓慢跟随",
        "duration": 5,               # 整数，3–30 秒
        "aspect_ratio": "16:9",
    }).json()

    while True:
        s = requests.get(f"{BASE}/videos/{task['id']}", headers=H).json()
        if s["status"] in ("completed", "failed"):
            break
        time.sleep(12)

    if s["status"] == "completed":
        url = s.get("metadata", {}).get("url") or f"{BASE}/videos/{task['id']}/content"
        open("output.mp4", "wb").write(requests.get(url, headers=H).content)
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    import fs from "fs";

    const BASE = "https://www.vibeapi.cn/v1";
    const H = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };
    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

    const task = await (await fetch(`${BASE}/videos`, {
      method: "POST",
      headers: H,
      body: JSON.stringify({
        model: "kling-4.0-720p",
        prompt: "一只橘猫在草地上追蝴蝶，阳光柔和，镜头缓慢跟随",
        duration: 5,               // 整数，3–30 秒
        aspect_ratio: "16:9",
      }),
    })).json();

    let s;
    while (true) {
      s = await (await fetch(`${BASE}/videos/${task.id}`, { headers: H })).json();
      if (s.status === "completed" || s.status === "failed") break;
      await sleep(12_000);
    }

    if (s.status === "completed") {
      const url = s.metadata?.url ?? `${BASE}/videos/${task.id}/content`;
      fs.writeFileSync("output.mp4", Buffer.from(await (await fetch(url, { headers: H })).arrayBuffer()));
    }
    ```
  </Tab>
</Tabs>

## 型号

| 型号                | 输出                       | 时长     | 计费 |
| ----------------- | ------------------------ | ------ | -- |
| `kling-4.0-720p`  | 720p，如 16:9 出 1280×720   | 3–30 秒 | 按秒 |
| `kling-4.0-1080p` | 1080p，如 9:16 出 1080×1920 | 3–30 秒 | 按秒 |

两档参数完全一样，只是清晰度和单价不同。实测 5 秒 720p、3 秒 1080p 都在 4 分钟左右出片。单价见 [https://www.vibeapi.cn/pricing](https://www.vibeapi.cn/pricing)

## 参数

| 字段             | 类型        | 必填 | 说明                                         |
| -------------- | --------- | -- | ------------------------------------------ |
| `model`        | string    | 是  | `kling-4.0-720p` 或 `kling-4.0-1080p`       |
| `prompt`       | string    | 是  | 描述主体、动作、场景与镜头                              |
| `duration`     | integer   | 是  | 输出时长，3–30 秒，按这个秒数计费                        |
| `aspect_ratio` | string    | 否  | 支持各种比例，如 `16:9`、`9:16`、`1:1`               |
| `images`       | string\[] | 否  | 参考图片的 HTTPS 地址，最多 10 张，每张不超过 10 MB，按传入顺序参考 |
| `audios`       | string\[] | 否  | 参考音频的 HTTPS 地址，最多 3 段，每段 5–30 秒、不超过 20 MB  |

* 分辨率只认模型名。请求体里另写 `resolution` 不报错，但会被换成模型名里的档位。
* 只传一张参考图时，也可以写 `image` 或 `input_reference`；三者同时传以 `images` 为准。
* 素材地址必须是**公网可直接下载**的直链，要登录、要 Cookie、分享页都不行。

## 图生视频

```bash
curl https://www.vibeapi.cn/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "kling-4.0-1080p",
    "prompt": "保持参考图中的主体外观，镜头缓慢推进，画面自然微动",
    "images": ["https://your-cdn.example.com/subject.jpg"],
    "duration": 5,
    "aspect_ratio": "9:16"
  }'
```

参考音频用同样的顶层数组写法，和参考图一起传：

```json
{
  "images": ["https://your-cdn.example.com/subject.jpg"],
  "audios": ["https://your-cdn.example.com/rhythm.wav"]
}
```

## 已知限制（截至 2026-10-31）

| 限制            | 说明                                                  | 怎么办                             |
| ------------- | --------------------------------------------------- | ------------------------------- |
| **暂不收参考视频**   | 请求带 `videos` 时返回 400 `reference_videos_unsupported` | 去掉 `videos`；要参考动作或运镜，可以先截一帧作参考图 |
| **分辨率只认模型名**  | `resolution` / `size` 会被模型名里的档位覆盖                   | 换分辨率就换模型名                       |
| **时长 3–30 秒** | 超出范围会在提交时被拒，额度不扣                                    | 按需要的秒数传，每多一秒都计费                 |


# 万相 3.0

`POST /v1/videos`，`model` 为 `wan3.0-video-{480p,720p,1080p}`（文生 / 图生）或 `wan3.0-image-*`（图生视频专用）；`prime` 版为高速档。
**分辨率写在模型名里**，请求体里的 `size` / `resolution` 会被模型名覆盖。按秒计费，见[视频生成](https://docs.vibeapi.cn/zh/docs/videos#模型与计费)。本页结论来自对本网关的真实调用，最后验证：2026-09-05。

<Callout type="warn" title="万相 3.0 暂停供应">
  2026-10-31 起万相 3.0 暂时不可用，恢复时间未定。期间可以改用[可灵 4.0](https://docs.vibeapi.cn/zh/docs/videos-kling)，同样按秒计费，分辨率也写在模型名里。
</Callout>

## 基本调用

<Tabs items={['curl', 'Python', 'Node.js']}>
  <Tab value="curl">
    ```bash
    # 1. 提交
    curl https://www.vibeapi.cn/v1/videos \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "wan3.0-video-1080p",
        "prompt": "潘多拉魔盒开启的瞬间。昏暗石室中一只古老匣子微微开启，金色与暗色的光雾自缝隙翻涌而出，尘埃在光柱中悬浮，镜头极缓慢推近，电影级布光",
        "seconds": "5",
        "aspect_ratio": "16:9"
    }'

    # 2. 轮询（每 10~15 秒一次）
    curl "https://www.vibeapi.cn/v1/videos/$TASK_ID" -H "Authorization: Bearer $API_KEY"

    # 3. 取片
    curl -L "https://www.vibeapi.cn/v1/videos/$TASK_ID/content" \
      -H "Authorization: Bearer $API_KEY" -o output.mp4
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import time, requests

    BASE = "https://www.vibeapi.cn/v1"
    H = {"Authorization": "Bearer YOUR_API_KEY"}

    task = requests.post(f"{BASE}/videos", headers=H, json={
        "model": "wan3.0-video-1080p",
        "prompt": "潘多拉魔盒开启的瞬间。昏暗石室中一只古老匣子微微开启，金色与暗色的光雾自缝隙翻涌而出，尘埃在光柱中悬浮，镜头极缓慢推近，电影级布光",
        "seconds": "5",
        "aspect_ratio": "16:9",
    }).json()

    while True:
        s = requests.get(f"{BASE}/videos/{task['id']}", headers=H).json()
        if s["status"] in ("completed", "failed"):
            break
        time.sleep(12)

    if s["status"] == "completed":
        url = s.get("metadata", {}).get("url") or f"{BASE}/videos/{task['id']}/content"
        open("output.mp4", "wb").write(requests.get(url, headers=H).content)
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    import fs from "fs";

    const BASE = "https://www.vibeapi.cn/v1";
    const H = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };
    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

    const task = await (await fetch(`${BASE}/videos`, {
      method: "POST",
      headers: H,
      body: JSON.stringify({
        model: "wan3.0-video-1080p",
        prompt: "潘多拉魔盒开启的瞬间。昏暗石室中一只古老匣子微微开启，金色与暗色的光雾自缝隙翻涌而出，尘埃在光柱中悬浮，镜头极缓慢推近，电影级布光",
        seconds: "5",
        aspect_ratio: "16:9",
      }),
    })).json();

    let s;
    while (true) {
      s = await (await fetch(`${BASE}/videos/${task.id}`, { headers: H })).json();
      if (s.status === "completed" || s.status === "failed") break;
      await sleep(12_000);
    }

    if (s.status === "completed") {
      const url = s.metadata?.url ?? `${BASE}/videos/${task.id}/content`;
      fs.writeFileSync("output.mp4", Buffer.from(await (await fetch(url, { headers: H })).arrayBuffer()));
    }
    ```
  </Tab>
</Tabs>

<div className="not-prose my-6 grid gap-4 max-w-xl">
  <figure className="m-0">
    <video src="https://studio.vibevibe.cn/docs/20260904/video-models/video/pandora-1080p.mp4" controls muted loop playsInline preload="none" className="w-full rounded-lg border border-fd-border" />

    <figcaption className="mt-2 text-center text-xs text-fd-muted-foreground">
      潘多拉魔盒 · wan3.0-video-1080p · 5 秒
    </figcaption>
  </figure>
</div>

## 型号怎么选

| 型号                               | 用途                         | 输出                             | 备注                |
| -------------------------------- | -------------------------- | ------------------------------ | ----------------- |
| `wan3.0-video-{480p,720p,1080p}` | 文生 / 图生                    | 832×480 / 1280×720 / 1920×1080 | 暂不收参考视频           |
| `wan3.0-video-prime-*`           | 同上，高速版                     | 同上                             | 单价高约 20%，1–3 分钟出片 |
| `wan3.0-image-*`                 | 图生专用，`reference_images` 必填 | 同上三档                           | **不收参考视频**        |
| `wan3.0-image-prime-*`           | 同上，高速版                     | 同上三档                           |                   |

### 三档分辨率与 prime

分辨率只由模型名决定，请求体里的 `size` 不生效；同一档的 prime 版本参数完全一样，只是更快、更贵。
纯文生视频用 `wan3.0-video-*`，不传任何参考素材：

```json
{
  "model": "wan3.0-video-720p",
  "prompt": "一只猫在窗台上打盹，阳光缓缓移动，窗帘轻轻摆动",
  "seconds": "5",
  "aspect_ratio": "16:9"
}
```

## 参数

| 字段                 | 类型        | 必填 | 说明                                               |
| ------------------ | --------- | -- | ------------------------------------------------ |
| `model`            | string    | 是  | 带分辨率后缀的模型名                                       |
| `prompt`           | string    | 是  | 画面描述，可用「图1」「音频1」引用素材顺序                           |
| `seconds`          | string    | 建议 | 输出时长，如 `"10"`；也接受 `duration` 别名                  |
| `size`             | string    | 否  | `480P` / `720P` / `1080P`，会被模型名后缀覆盖              |
| `aspect_ratio`     | string    | 否  | `16:9`（默认）/ `9:16` / `1:1` / `adaptive`          |
| `reference_images` | object\[] | 否  | 最多 10 张，用 `role` 指定用途                            |
| `reference_videos` | object\[] | 否  | **暂不支持**，带了返回 400 `reference_videos_unsupported` |
| `reference_audios` | object\[] | 否  | 参与生成，不计入秒数                                       |

`seconds` 请传字符串。所有 wan3.0 型号都只按输出时长计费。

## 图生视频

`role` 三个取值：`reference_image`（默认）、`first_frame`、`last_frame`。
素材必须是公网可直接下载的 HTTPS 地址。

```bash
curl https://www.vibeapi.cn/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-image-1080p",
    "prompt": "以参考图为首帧。火炬的火焰剧烈燃烧，火星向上飘散，背景云层缓慢翻涌，镜头极缓慢推进",
    "seconds": "5",
    "aspect_ratio": "16:9",
    "reference_images": [
      { "url": "https://your-cdn.example.com/prometheus.png", "role": "first_frame" }
    ]
  }'
```

<div className="not-prose my-6 grid gap-4 max-w-xl">
  <figure className="m-0">
    <video src="https://studio.vibevibe.cn/docs/20260904/video-models/video/prometheus-i2v-1080p.mp4" controls muted loop playsInline preload="none" className="w-full rounded-lg border border-fd-border" />

    <figcaption className="mt-2 text-center text-xs text-fd-muted-foreground">
      普罗米修斯 · wan3.0-image-1080p · 参考图作首帧
    </figcaption>
  </figure>
</div>

## 多参考素材：首帧 + 参考图 + 参考音频

`reference_images` 里每一项都带 `role`，所以**位置不重要、角色才重要**：首帧和尾帧各只能一张，
`reference_image` 可以多张。提示词里按素材在各自数组里的顺序叫「图1」「图2」「音频1」。
下面这条是 `wan3.0-video-*` 的完整形态。参考视频暂不支持，请求里不要带 `reference_videos`：

```bash
curl https://www.vibeapi.cn/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video-720p",
    "prompt": "以图1为首帧。图2里的机器人从画面右侧走入，沿着街道走向镜头，动作节奏跟随音频1的鼓点；黄昏光线保持不变，镜头缓慢推进",
    "seconds": "8",
    "aspect_ratio": "16:9",
    "reference_images": [
      { "url": "https://your-cdn.example.com/street-dusk.png", "role": "first_frame" },
      { "url": "https://your-cdn.example.com/robot.png", "role": "reference_image" }
    ],
    "reference_audios": [
      { "url": "https://your-cdn.example.com/drums.mp3" }
    ]
  }'
```

* 「图1」「图2」按 `reference_images` 的数组顺序数，与 `role` 无关；首帧不必排第一，但习惯上放第一。
* 参考音频不计入计费秒数。
* 带 `reference_videos`、或在 `input.media` 里放视频，都会返回 400 `reference_videos_unsupported`。
* 要首尾帧插值就再加一项 `{"url": ..., "role": "last_frame"}`；同一张图同时作首尾帧就是无缝循环的做法，见[视频生成工作流](https://docs.vibeapi.cn/zh/docs/videos-workflow)。

## 已知限制（截至 2026-10-31）

| 限制                              | 说明                                                                             | 怎么办                               |
| ------------------------------- | ------------------------------------------------------------------------------ | --------------------------------- |
| **分辨率只认模型名**                    | `size` / `resolution` 传了会被模型名后缀覆盖，不报错                                          | 换分辨率就换模型名                         |
| **暂停供应**                        | 2026-10-31 起暂时不可用，恢复时间未定                                                       | 改用[可灵 4.0](https://docs.vibeapi.cn/zh/docs/videos-kling) |
| **暂不收参考视频**                     | 带 `reference_videos` 或 `input.media` 里的视频返回 400 `reference_videos_unsupported` | 去掉参考视频；要参考动作可以先截一帧作参考图            |
| **1080p 成片很大**                  | 15 秒 1080p 通常 40–230 MB，码率高                                                    | 做网页背景先转码；下载超时按 3 分钟设              |
| **`wan3.0-image-*` 收不收参考音频未验证** | 传了不会在提交阶段被拒，可能到异步阶段才 `failed`（全额退款）                                            | 需要音频参考走 `wan3.0-video-*`          |
| **首尾帧与参考图规则**                   | 首帧、尾帧各只能一张；`adaptive` 画幅要带图或视频才可用                                              | 见[图生视频](#图生视频)                    |
| **出片时间**                        | 普通版 3–8 分钟，`prime` 1–3 分钟                                                      | 轮询超时按 20 分钟设                      |

## 商业方向样片

所有底图都是用 `gpt-image-2.5-sunburst` 出的（横版 2560×1440、竖版 1440×2560），
再作为首帧 / 参考图交给本页模型，提示词只写运镜与动态。成片保留原始音轨。

汽车、地产这类需要 1080p 的方向用 `wan3.0-video-1080p` / `wan3.0-image-prime-1080p`；
竖版短视频用 720p 档就够，5 秒一条 1–3 分钟出片。

<SampleVideos items={[{"src": "https://studio.vibevibe.cn/docs/260915/biz/video/ev-car.mp4", "poster": "https://studio.vibevibe.cn/docs/260915/biz/poster/ev-car.webp", "caption": "汽车 · 海岸公路 · wan3.0-video-1080p · 8 s", "portrait": false}, {"src": "https://studio.vibevibe.cn/docs/260915/biz/video/villa.mp4", "poster": "https://studio.vibevibe.cn/docs/260915/biz/poster/villa.webp", "caption": "地产 · 黄昏别墅 · wan3.0-image-prime-1080p · 8 s", "portrait": false}, {"src": "https://studio.vibevibe.cn/docs/260915/biz/video/drink.mp4", "poster": "https://studio.vibevibe.cn/docs/260915/biz/poster/drink.webp", "caption": "饮品 · 冰块入杯 · wan3.0-video-720p · 5 s", "portrait": true}, {"src": "https://studio.vibevibe.cn/docs/260915/biz/video/drink-wanimg.mp4", "poster": "https://studio.vibevibe.cn/docs/260915/biz/poster/drink-wanimg.webp", "caption": "饮品 · 气泡上升 · wan3.0-image-720p · 5 s", "portrait": true}]} />


# 视频生成工作流

讲怎么把视频调得好看。接口本身怎么调见[视频生成](https://docs.vibeapi.cn/zh/docs/videos)。文内样片均为真实调用产出，最后验证：2026-09-05。

## 为什么不该一句话直接出视频

**不要指望一句提示词直接出好视频。** 视频模型要同时处理构图、光线、材质和运动，
注意力被摊薄，画面细节往往不如同价位的图像模型。更稳的做法是拆成两步：
**先用图像模型把「第一帧长什么样」定死，再让视频模型只负责让它动起来。**

1. **用 `gpt-image-2` 或 `gemini-3-pro-image` 生成 4K 参考图。**
   把画面描述、风格、色调、光线全写进图像提示词，反复生成到满意为止。
   图像调用比视频便宜得多，试错成本低，而且立刻能看到结果。
2. **把图放到公网可直接下载的地址。** 视频模型要自己去下载，
   不能要登录、不能是网盘分享页。
3. **用它当首帧，提示词只写「怎么动」。** 画面内容已由参考图定死，
   视频提示词别再重复描述场景，只写运动。

## 第一步：生成 4K 参考图

`gpt-image-2` 最大边 3840px；`gemini-3-pro-image`（Nano Banana Pro）4K 档实际输出 5504×3072。

```bash
curl https://www.vibeapi.cn/v1/images/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "quality": "high",
    "size": "3840x2160",
    "prompt": "Nuwa mending the broken sky. A celestial goddess in flowing crimson and gold robes suspended among shattered heavens... traditional Chinese gongbi heavy-color painting, mineral pigments, cinnabar red, malachite green and gold leaf; no text, no watermark"
  }'
```

<ImageGrid cols={1} ratio="16 / 9" items={[{"src": "https://studio.vibevibe.cn/docs/20260904/video-models/image/nuwa-mending-sky-HIGH.webp", "alt": "女娲补天 4K 参考图", "caption": "gpt-image-2 · quality high · 3840×2160"}]} />

**要真正的高清档，`quality: "high"` 必须显式传。** 不传或传 `auto` 会落到中间档，
而分辨率、文件大小都看不出差别——唯一能分辨的是响应里的 `usage.output_tokens`：
4K 高清档约 13000，中间档只有约 3300，差约 4 倍算力。
发一批图时建议逐张核对这个数，不对就重发，命中率通常一两次就够。

## 第二步：喂给视频模型

<Callout type="warn" title="万相 3.0 暂停供应">
  下面的示例用的是 wan3.0，它从 2026-10-31 起暂时不可用。期间可以把参考图放进[可灵 4.0](https://docs.vibeapi.cn/zh/docs/videos-kling) 的 `images`，做法一样，提示词只写运动；无缝循环靠的是 wan3.0 的首尾帧，可灵没有这项能力。
</Callout>

```bash
curl https://www.vibeapi.cn/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video-1080p",
    "prompt": "五色石的白热光芒缓缓明灭，天穹裂隙中的金液缓缓流淌弥合，祥云与凤羽绕身缓慢盘旋，衣袂飘动，镜头极缓慢推进",
    "seconds": "15",
    "aspect_ratio": "16:9",
    "reference_images": [
      { "url": "https://your-cdn.example.com/nuwa-4k.png", "role": "first_frame" }
    ]
  }'
```

注意提示词里**一句场景描述都没有**——人物、服饰、色调全由参考图决定，提示词只管运动。
这是这套工作流最关键的一点。

## 做接缝看不出来的循环背景

做网站动态背景时，片子每循环一轮都会在接缝处跳一下。
用万相的首尾帧能基本消掉：**把同一张图同时传给 `first_frame` 和 `last_frame`**。

```bash
curl https://www.vibeapi.cn/v1/videos \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "wan3.0-video-1080p",
    "prompt": "从首帧自然演化后回到尾帧，形成完整闭环。云层缓慢翻涌一周后回到起始形态，光线强度轻微起伏后复原，镜头极缓慢推进再退回原位。全程无剪切、无淡入淡出",
    "seconds": "15",
    "aspect_ratio": "16:9",
    "reference_images": [
      { "url": "https://your-cdn.example.com/frame.png", "role": "first_frame" },
      { "url": "https://your-cdn.example.com/frame.png", "role": "last_frame" }
    ]
  }'
```

提示词里明写「回到起始形态」「全程无剪切」很关键，不写模型容易在结尾自由发挥。

### 交叉淡化补掉残差

首尾已经很接近，但不到像素级重合。首帧与末帧缩到 320×180 后逐像素求平均差为
**9.66 / 255**；作为对照，首帧与中间帧是 26.91 / 255。
差距只有对照组的三分之一，但 3.8% 的残差循环播放时仍看得见。

```bash
ffmpeg -i in.mp4 -filter_complex \
"[0:v]split[body][pre];\
 [pre]trim=duration=1,format=yuva420p,fade=t=in:st=0:d=1:alpha=1,setpts=PTS+13.02/TB[jt];\
 [body]trim=start=1,setpts=PTS-STARTPTS[main];\
 [main][jt]overlay=shortest=0[v]" \
 -map "[v]" -c:v libx264 -crf 17 -preset slow -pix_fmt yuv420p -an out.mp4
```

`setpts=PTS+13.02/TB` 里的 13.02 是「原片时长 − 2」，按你的片子换算。输出比原片短 1 秒。
做完这一步首末帧平均像素差从 **9.66 降到 1.65 / 255**，循环播放看不出接缝。

四条无缝循环样片见下文「成片展示」。

## 成片展示

同一套两步法，换四种题材与画风。全部 `wan3.0-video-1080p`，15 秒，1920×1080，
首尾帧循环 + 交叉淡化：

<div className="not-prose my-6 grid gap-4 sm:grid-cols-2">
  <figure className="m-0">
    <video src="https://studio.vibevibe.cn/docs/20260904/video-models/video/nuwa-wan-seamless.mp4" controls muted loop playsInline preload="none" className="w-full rounded-lg border border-fd-border" />

    <figcaption className="mt-2 text-center text-xs text-fd-muted-foreground">
      女娲补天 · 工笔重彩（首末帧差 1.87/255）
    </figcaption>
  </figure>

  <figure className="m-0">
    <video src="https://studio.vibevibe.cn/docs/20260904/video-models/video/dunhuang-wan-seamless.mp4" controls muted loop playsInline preload="none" className="w-full rounded-lg border border-fd-border" />

    <figcaption className="mt-2 text-center text-xs text-fd-muted-foreground">
      敦煌飞天 · 莫高窟壁画（2.15/255）
    </figcaption>
  </figure>

  <figure className="m-0">
    <video src="https://studio.vibevibe.cn/docs/20260904/video-models/video/kunpeng-wan-seamless.mp4" controls muted loop playsInline preload="none" className="w-full rounded-lg border border-fd-border" />

    <figcaption className="mt-2 text-center text-xs text-fd-muted-foreground">
      鲲鹏 · 水墨留白（2.11/255）
    </figcaption>
  </figure>

  <figure className="m-0">
    <video src="https://studio.vibevibe.cn/docs/20260904/video-models/video/loop15-prometheus-seamless.mp4" controls muted loop playsInline preload="none" className="w-full rounded-lg border border-fd-border" />

    <figcaption className="mt-2 text-center text-xs text-fd-muted-foreground">
      普罗米修斯 · 电影写实（1.65/255）
    </figcaption>
  </figure>
</div>

不走参考图的 Seedance 2.5 长片（30 秒 / 1280×720，现用 `doubao-seedance-2-5-260628`）：

<div className="not-prose my-6 grid gap-4 sm:grid-cols-2">
  <figure className="m-0">
    <video src="https://studio.vibevibe.cn/docs/20260904/video-models/video/nuwa-sd25.mp4" controls muted loop playsInline preload="none" className="w-full rounded-lg border border-fd-border" />

    <figcaption className="mt-2 text-center text-xs text-fd-muted-foreground">
      女娲补天
    </figcaption>
  </figure>

  <figure className="m-0">
    <video src="https://studio.vibevibe.cn/docs/20260904/video-models/video/dunhuang-sd25.mp4" controls muted loop playsInline preload="none" className="w-full rounded-lg border border-fd-border" />

    <figcaption className="mt-2 text-center text-xs text-fd-muted-foreground">
      敦煌飞天
    </figcaption>
  </figure>

  <figure className="m-0">
    <video src="https://studio.vibevibe.cn/docs/20260904/video-models/video/kunpeng-sd25.mp4" controls muted loop playsInline preload="none" className="w-full rounded-lg border border-fd-border" />

    <figcaption className="mt-2 text-center text-xs text-fd-muted-foreground">
      鲲鹏水墨
    </figcaption>
  </figure>
</div>

作为对照，不带参考图的纯文生（5 秒 / 1920×1080）：

<div className="not-prose my-6 grid gap-4 sm:grid-cols-2">
  <figure className="m-0">
    <video src="https://studio.vibevibe.cn/docs/20260904/video-models/video/icarus-1080p.mp4" controls muted loop playsInline preload="none" className="w-full rounded-lg border border-fd-border" />

    <figcaption className="mt-2 text-center text-xs text-fd-muted-foreground">
      伊卡洛斯坠落
    </figcaption>
  </figure>

  <figure className="m-0">
    <video src="https://studio.vibevibe.cn/docs/20260904/video-models/video/atlas-1080p.mp4" controls muted loop playsInline preload="none" className="w-full rounded-lg border border-fd-border" />

    <figcaption className="mt-2 text-center text-xs text-fd-muted-foreground">
      阿特拉斯扛天球
    </figcaption>
  </figure>
</div>

## 工作流要点

* **别一句话直接出视频。** 拆成两步：图像模型定画面，视频模型只做运动。
* 参考图提示词**把画面吃干榨净**——主体、构图、光源、色调、材质、画风；但别写运动。
* 视频提示词**一句场景描述都不要写**，只写运动。两边抢活画面反而会飘。
* `gpt-image-2` 的 **`quality: "high"` 必须显式传**，靠 `usage.output_tokens` 核对：
  4K 高清约 13000，中间档约 3300。
* 参考图必须是**公网可直接下载**的 HTTPS 直链，贴进无痕窗口能下载才算数。
* 要无缝循环：**同一张图同时作首帧与尾帧**，提示词明写「回到起始形态、全程无剪切」。
* 循环片再用 **ffmpeg 交叉淡化 1 秒**，首末帧像素差能从 9.66 降到 1.65 / 255。


# 视频生成概览

<HeroVideo src="https://studio.vibevibe.cn/docs/260915/docs-intro/video/videos.mp4" poster="https://studio.vibevibe.cn/docs/260915/docs-intro/poster/videos.webp" model="doubao-seedance-2-5-260628" />

视频生成是**异步**的：提交拿到 `task_id`，轮询到 `completed`，再取片。
一次生成通常 3 到 8 分钟，长时长更久。

```
POST  /v1/videos                    提交任务
GET   /v1/videos/{task_id}          查询状态
GET   /v1/videos/{task_id}/content  下载成片
```

三个接口共用同一把 key，都带 `Authorization: Bearer <API_KEY>`。

**因为是异步的，这里不受 120 秒超时的约束**——提交请求本身很快返回，长耗时发生在
轮询之间。这是视频与文本、图像端点最大的不同。

## 基本调用

提交、轮询、取片三步。官方 SDK 未覆盖这组接口，直接发 HTTP 即可。

<Tabs items={['curl', 'Python', 'Node.js']}>
  <Tab value="curl">
    ```bash
    # 1. 提交
    curl -X POST "https://www.vibeapi.cn/v1/videos" \
      -H "Authorization: Bearer $API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "kling-4.0-720p",
        "prompt": "一只猫在窗台上打盹，阳光缓缓移动",
        "duration": 5,
        "aspect_ratio": "16:9"
      }'

    # 2. 轮询（每 10~15 秒一次）
    curl "https://www.vibeapi.cn/v1/videos/$TASK_ID" -H "Authorization: Bearer $API_KEY"

    # 3. 取片
    curl -L "https://www.vibeapi.cn/v1/videos/$TASK_ID/content" \
      -H "Authorization: Bearer $API_KEY" -o output.mp4
    ```
  </Tab>

  <Tab value="Python">
    ```python
    import time, requests

    BASE = "https://www.vibeapi.cn/v1"
    H = {"Authorization": "Bearer YOUR_API_KEY"}

    task = requests.post(f"{BASE}/videos", headers=H, json={
        "model": "kling-4.0-720p",
        "prompt": "一只猫在窗台上打盹，阳光缓缓移动",
        "duration": 5,               # 可灵传整数；wan3.0 用字符串 seconds
        "aspect_ratio": "16:9",
    }).json()
    task_id = task["id"]

    while True:
        s = requests.get(f"{BASE}/videos/{task_id}", headers=H).json()
        if s["status"] in ("completed", "failed"):
            break
        time.sleep(12)               # 每 10~15 秒一次，超时按 15 分钟设

    if s["status"] == "completed":
        # metadata.url 多数模型指向 /content，H3 则是对象存储直链
        url = s.get("metadata", {}).get("url") or f"{BASE}/videos/{task_id}/content"
        mp4 = requests.get(url, headers=H).content
        open("output.mp4", "wb").write(mp4)
    ```
  </Tab>

  <Tab value="Node.js">
    ```javascript
    import fs from "fs";

    const BASE = "https://www.vibeapi.cn/v1";
    const H = { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json" };
    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

    const task = await (await fetch(`${BASE}/videos`, {
      method: "POST",
      headers: H,
      body: JSON.stringify({
        model: "kling-4.0-720p",
        prompt: "一只猫在窗台上打盹，阳光缓缓移动",
        duration: 5,               // 可灵传整数；wan3.0 用字符串 seconds
        aspect_ratio: "16:9",
      }),
    })).json();

    let s;
    while (true) {
      s = await (await fetch(`${BASE}/videos/${task.id}`, { headers: H })).json();
      if (s.status === "completed" || s.status === "failed") break;
      await sleep(12_000);         // 每 10~15 秒一次，超时按 15 分钟设
    }

    if (s.status === "completed") {
      // metadata.url 多数模型指向 /content，H3 则是对象存储直链
      const url = s.metadata?.url ?? `${BASE}/videos/${task.id}/content`;
      const mp4 = Buffer.from(await (await fetch(url, { headers: H })).arrayBuffer());
      fs.writeFileSync("output.mp4", mp4);
    }
    ```
  </Tab>
</Tabs>

所有参数行为、分辨率与计费口径均来自真实调用，最后验证：2026-09-05。怎么调得好看，见[视频生成工作流](https://docs.vibeapi.cn/zh/docs/videos-workflow)。

本页结论来自对本网关的真实调用，最后验证：2026-09-21。

| 页面                                    | 内容                                                      |
| ------------------------------------- | ------------------------------------------------------- |
| [可灵 4.0](https://docs.vibeapi.cn/zh/docs/videos-kling)       | 文生 / 图生视频，720p / 1080p 写在模型名里，3–30 秒，参考图与参考音频           |
| [万相 3.0](https://docs.vibeapi.cn/zh/docs/videos-wan)         | 文生 / 图生视频，分辨率在模型名里，首尾帧；**暂停供应**                         |
| [Seedance](https://docs.vibeapi.cn/zh/docs/videos-seedance)  | 字节官方四个型号，最长 30 秒、到 1080p，参考图 / 视频 / 音频与首尾帧都收；按 token 计费 |
| [MiniMax H3](https://docs.vibeapi.cn/zh/docs/videos-minimax) | 首尾帧或图 / 视频 / 音频三类参考素材，图片可传 base64，768P                  |
| [Grok 视频](https://docs.vibeapi.cn/zh/docs/grok-videos)       | 按秒计费，走 Grok 自己的端点                                       |
| [视频生成工作流](https://docs.vibeapi.cn/zh/docs/videos-workflow)   | 先出 4K 参考图再喂视频模型、无缝循环                                    |

## 三个接口

视频生成是**异步**的：提交拿到 `task_id`，轮询到 `completed`，再取片。
一次生成通常 3 到 8 分钟，长时长更久。三个接口共用同一把 key。

```
POST https://www.vibeapi.cn/v1/videos                    提交任务
GET  https://www.vibeapi.cn/v1/videos/{task_id}          查询状态
GET  https://www.vibeapi.cn/v1/videos/{task_id}/content  下载成片
```

`/content` 对所有模型都可用，需带同一个 `Authorization` 头。
查询响应里的 `metadata.url` 就是上面那个 `/content` 地址，写代码时取 `metadata.url` 即可。

## 模型与计费

**同一个 `/v1/videos` 接口下，各系列的收费方式并不一致。**

|      | 可灵 4.0              | wan3.0 系列                     | MiniMax H3              | Seedance 系列                      |
| ---- | ------------------- | ----------------------------- | ----------------------- | -------------------------------- |
| 计费口径 | **按秒** — 单价 × 时长    | **按秒** — 单价 × 时长              | **按秒** — 单价 × 时长        | **按 token** — 时长 × 分辨率，与字节官方刊例同价 |
| 时长参数 | `duration`，整数       | `seconds`，字符串                 | `seconds` 或 `duration`  | `duration`，数字，不传按 5 秒            |
| 分辨率  | 写在模型名里，两档           | 写在模型名里，三档                     | 固定 768P                 | `resolution`：`720p`（默认）/ `1080p` |
| 时长范围 | 3–30 秒              | 推荐 5–15 秒                     | 1–15 秒整数                | 2.5 为 4–30 秒，2.0 系列 4–15 秒       |
| 画面比例 | `aspect_ratio`，各种比例 | `aspect_ratio`，四档含 `adaptive` | 六档固定，另有条件可用的 `adaptive` | `aspect_ratio`，六档固定 + `adaptive` |

各系列都是**每多一秒都在计费**；Seedance 还按分辨率分档，1080p 约是 720p 的 2.5 倍。

### 全部模型

| 模型                                | 能力                                                           | 输出                             | 计费          |
| --------------------------------- | ------------------------------------------------------------ | ------------------------------ | ----------- |
| `kling-4.0-{720p,1080p}`          | 文生 / 图生，3–30 秒，参考图 10 · 参考音频 3，暂不收参考视频                       | 720p / 1080p                   | **按秒**      |
| `wan3.0-video-{480p,720p,1080p}`  | 文生 / 图生，暂不收参考视频；**暂停供应**                                     | 832×480 / 1280×720 / 1920×1080 | 按秒          |
| `wan3.0-video-prime-*`            | 同上，高速版                                                       | 同上                             | 按秒，单价高约 20% |
| `wan3.0-image-*`                  | 图生视频专用，不收参考视频                                                | 同上三档                           | 仅按输出时长      |
| `wan3.0-image-prime-*`            | 同上，高速版                                                       | 同上三档                           | 仅按输出时长      |
| `doubao-seedance-2-5-260628`      | 文生 / 图生 / 首尾帧，4–30 秒，参考图 30 · 参考视频 10 · 参考音频 10，实测 5 秒约 9 分钟 | 720p / 1080p                   | 按 token     |
| `doubao-seedance-2-0-260128`      | 文生 / 图生 / 首尾帧，4–15 秒，参考图 9 · 参考视频 3 · 参考音频 3                 | 720p / 1080p                   | 按 token     |
| `doubao-seedance-2-0-fast-260128` | 同 2.0，更快更便宜                                                  | 720p                           | 按 token     |
| `doubao-seedance-2-0-mini-260615` | 同 2.0，最便宜                                                    | 720p                           | 按 token     |
| `MiniMax-H3`                      | 文生 / 首尾帧 / 参考图生，1–15 秒，9 图 / 3 视频 / 3 音频参考                   | 固定 768P，六种比例                   | **按秒**      |

旧的一口价模型名 `seedance-2.5` / `-plus` / `-pro` / `seedance-2.0` 已下线，换成上面的官方模型 ID 即可，字段不变。

单价见 [https://www.vibeapi.cn/pricing](https://www.vibeapi.cn/pricing)

## 轮询与取片

状态走 `queued` → `in_progress` → `completed`。建议每 10 到 15 秒查一次，超时按 15 分钟设。

```bash
curl "https://www.vibeapi.cn/v1/videos/$TASK_ID" -H "Authorization: Bearer $API_KEY"
```

完成时：

```json
{
  "id": "task_397b84onbn1ML8uBNhsiaQP3gafAe3AI",
  "status": "completed",
  "progress": 100,
  "metadata": { "url": "https://www.vibeapi.cn/v1/videos/task_397b.../content" }
}
```

下载：

```bash
curl -L "https://www.vibeapi.cn/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $API_KEY" -o output.mp4
```

### 完整 Python 示例

```python
import os, time, requests

BASE = "https://www.vibeapi.cn/v1"
H = {"Authorization": f"Bearer {os.environ['VIBEAPI_KEY']}"}

def generate(payload, timeout=900, interval=12):
    task = requests.post(f"{BASE}/videos", headers=H, json=payload, timeout=120).json()
    if "id" not in task:
        raise RuntimeError(f"提交失败: {task}")
    tid = task["id"]
    print("已提交", tid)

    deadline = time.time() + timeout
    while time.time() < deadline:
        r = requests.get(f"{BASE}/videos/{tid}", headers=H, timeout=60).json()
        status = r.get("status")
        if status == "completed":
            break
        if status == "failed":
            raise RuntimeError(f"生成失败: {r.get('error')}")
        time.sleep(interval)
    else:
        raise TimeoutError(f"{timeout} 秒内未完成: {tid}")

    mp4 = requests.get(f"{BASE}/videos/{tid}/content", headers=H, timeout=600)
    mp4.raise_for_status()
    return tid, mp4.content

tid, data = generate({
    "model": "kling-4.0-1080p",
    "prompt": "伊卡洛斯坠落。少年蜡制的双翼在刺目烈日下崩解成漫天金色羽毛，"
              "自极高处向湛蓝的爱琴海坠落，云层翻涌，镜头自远处缓慢仰摇",
    "duration": 5,
    "aspect_ratio": "16:9",
})
open(f"{tid}.mp4", "wb").write(data)
```

样片（当时用 `wan3.0-video-1080p` 生成）：[https://studio.vibevibe.cn/docs/20260904/video-models/video/icarus-1080p.mp4](https://studio.vibevibe.cn/docs/20260904/video-models/video/icarus-1080p.mp4)

一条 15 秒的 1080P 成片通常 40 到 230 MB，码率很高，做网页背景前建议自行转码压缩。

## 商业方向怎么选模型

按今天用同一批 `gpt-image-2.5` 底图实测（每个模型页底部都有对应样片）：

| 方向             | 推荐模型                                                        | 画幅          | 为什么                              |
| -------------- | ----------------------------------------------------------- | ----------- | -------------------------------- |
| 美妆 / 香水 / 护肤   | `doubao-seedance-2-5-260628`                                | 9:16 · 16:9 | 花瓣、水花这类慢动作最稳；按秒计费，10 秒够用就别拍 30 秒 |
| 3C 数码          | `doubao-seedance-2-0-260128` / `doubao-seedance-2-5-260628` | 16:9        | 爆炸图合体、旋转展示，2.0 出片快、便宜三成          |
| 珠宝             | `doubao-seedance-2-5-260628` / `doubao-seedance-2-0-260128` | 9:16        | 微距火彩，竖版直接进信息流；要 1080p 两个都行       |
| 汽车             | `wan3.0-video-1080p`                                        | 16:9        | 需要 1080p，跟拍运镜稳定                  |
| 地产 / 空间        | `wan3.0-image-prime-1080p`                                  | 16:9        | 首帧锁构图，推轨 + 天光变化                  |
| 饮品 / 食品        | `wan3.0-video-720p` · `wan3.0-image-720p`                   | 9:16        | 5 秒短片 1–3 分钟出，成本最低               |
| 餐饮场景（有人手 / 人物） | `MiniMax-H3`                                                | 16:9        | 唯一不卡人脸的系列，动作自然                   |
| 服装             | `MiniMax-H3` · `grok-imagine-video-1.5`                     | 9:16        | 布料动态好；Grok 1–2 分钟出片适合快速出多版       |

wan3.0 目前暂停供应，表里用到 wan3.0 的方向可以先换 `kling-4.0-1080p`（汽车、地产）或 `kling-4.0-720p`（饮品、食品）。

通用做法：先用图像模型把产品、光线、构图定死，再让视频模型只管"怎么动"，见[视频生成工作流](https://docs.vibeapi.cn/zh/docs/videos-workflow)。

## 参考素材

**各系列传素材的字段和在提示词里点名的写法各不相同**，这是最容易混的地方：

| 系列         | 参考图                                                                                         | 参考视频 / 音频                               | 提示词里怎么点名                              | 详情                                    |
| ---------- | ------------------------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------- | ------------------------------------- |
| 可灵 4.0     | `images: [url, …]`                                                                          | 暂不收参考视频；音频用 `audios: [url, …]`          | 描述主体、动作即可，按数组顺序参考                     | [可灵 4.0](https://docs.vibeapi.cn/zh/docs/videos-kling)       |
| Seedance   | `image_urls: [url, …]`；首尾帧用 `reference_images: [{url, role}]`                               | `video_urls` / `audio_urls`             | `@Image1` `@Video1` `@Audio1`，按数组顺序   | [Seedance](https://docs.vibeapi.cn/zh/docs/videos-seedance)  |
| wan3.0     | `reference_images: [{url, role}]`，`role` = `first_frame` / `last_frame` / `reference_image` | 暂不收参考视频；音频用 `reference_audios: [{url}]` | 「图1」「音频1」，按数组顺序                       | [万相 3.0](https://docs.vibeapi.cn/zh/docs/videos-wan)         |
| MiniMax H3 | `image_urls: [url, …]`（不能与首尾帧混用；首尾帧用 `first_frame_image` / `last_frame_image`）              | `video_urls` / `audio_urls`             | `<Picture 1>` `<Video 1>` `<Audio 1>` | [MiniMax H3](https://docs.vibeapi.cn/zh/docs/videos-minimax) |
| Grok       | `image: {url}` 锁首帧；`reference_images: [{url}]` 引导                                           | 不收                                      | `<IMAGE_1>` `<IMAGE_2>`               | [Grok 视频](https://docs.vibeapi.cn/zh/docs/grok-videos)       |

编号一律从 1 开始、按数组顺序数；不点名时模型会自行参考全部素材，点名之后才能区分"主体用哪张、场景用哪张"。
链接必须是**公网可直接下载的 HTTPS 直链**，贴进无痕窗口能直接下载才算数。每个详情页都有完整的多素材示例。

## 错误与退款

**提交阶段报错，额度不扣；任务失败，额度全额退回**（用量日志里失败任务额度记为 0）。

| 现象                                      | 原因                        | 怎么办                                  |
| --------------------------------------- | ------------------------- | ------------------------------------ |
| `model_not_found`                       | key 所在分组没有这个模型            | 确认 key 分组，或换模型名                      |
| HTTP 400，提示缺时长                          | 没传 `seconds` / `duration` | 补上；wan3.0 传字符串，Seedance 传数字（不传按 5 秒） |
| 提示该模型维护中                                | 模型临时不可用                   | 换模型，或稍后重试                            |
| HTTP 400 `reference_videos_unsupported` | 可灵 4.0、wan3.0 暂不收参考视频     | 去掉参考视频；要参考动作可以先截一帧作参考图               |
| 提交成功但很快 `failed`                        | 生成失败                      | 额度已全额退回，直接重试                         |

参考素材导致失败的两个常见原因：

1. **链接不是公网可直接下载。** 要登录、要 Cookie、是分享页而非直链都不行。
   贴进无痕窗口能直接下载才算数。
2. **在提示词里写了比例或时长。** 「竖屏」「16:9」「8 秒」会和参数冲突，
   比例和时长只用 `aspect_ratio` 和 `seconds` 控制。

### 能力边界

| 做不到          | 说明                                                                                |
| ------------ | --------------------------------------------------------------------------------- |
| 续写 / 剪辑 / 延长 | 只做单条生成                                                                            |
| 固定随机种子       | 同一提示词两次结果不同，没有 seed 参数                                                            |
| 任意模型收参考视频    | 可灵 4.0 与 wan3.0 暂不收，带了返回 400 `reference_videos_unsupported`；Seedance、MiniMax H3 收 |
| H3 上用首尾帧     | 上游不允许首尾帧与参考图混用，本接口只开放参考图。要首尾帧请用 `wan3.0-image-*`                                  |
| 成片长期保留       | 取到就存自己那边                                                                          |
| 完成回调         | 只能轮询，没有 Webhook                                                                   |

## 要点

* 先分清计费口径：**可灵 4.0、wan3.0 与 MiniMax H3 按秒，Seedance 按 token（时长 × 分辨率）**，每多一秒都花钱。
* 分辨率**写在模型名里**，请求体里的 `size` 覆盖不了它。
* **Seedance 用字节官方模型 ID**：`doubao-seedance-2-5-260628` 最长 30 秒、到 1080p、素材最多；`doubao-seedance-2-0-mini-260615` 最便宜。公众人物等敏感素材会被拒。
* 参考素材必须是**公网可直接下载**的 HTTPS 直链，不能要登录。
* 比例和时长**只用参数控制**，别写进提示词，会冲突。
* **可灵 4.0 与 wan3.0 暂不收参考视频**，带了返回 400；参考图和参考音频照常可用。
* 任务失败**全额退款**，重试即可；Seedance 系列请预留一次重试，公众人物等敏感素材会被审核拒掉。
* **H3 的分辨率不用传**，固定 768P；`adaptive` 比例只在带了图或视频时可用。
* **接口以本页为准**，不要照上游厂商的原文调用我们的域名——协议由网关翻译，端点和请求体都不一样。

想让画面更好看，接着读[视频生成工作流](https://docs.vibeapi.cn/zh/docs/videos-workflow)。

## 在线调试

填入你自己的 API Key 即可直接发起请求，参数表与响应结构由接口定义生成。

### 提交任务

<APIPage document={"openapi/generated/ai-model/视频（Videos）/Sora格式/post-v1-videos-createvideo-383844578.json"} operations={[{"path":"/v1/videos","method":"post"}]} />

### 查询状态

<APIPage document={"openapi/generated/ai-model/视频（Videos）/Sora格式/get-v1-videos-task-id-getvideo-383844579.json"} operations={[{"path":"/v1/videos/{task_id}","method":"get"}]} />

### 下载成片

<APIPage document={"openapi/generated/ai-model/视频（Videos）/Sora格式/get-v1-videos-task-id-content-getvideocontent-383844580.json"} operations={[{"path":"/v1/videos/{task_id}/content","method":"get"}]} />


# 接口参考

import { Card, Cards } from 'fumadocs-ui/components/card';

这里是逐端点的参数与响应定义，每页可直接在线调试（需填入你自己的 API Key）。
「怎么用」「选哪个」「有什么坑」在[调用指南](https://docs.vibeapi.cn/zh/docs/quickstart)里。

## 模型接口

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/api/ai-model/chat" title="聊天" description="Chat Completions 与 Messages" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/ai-model/images" title="图像" description="生成与编辑" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/ai-model/videos" title="视频" description="异步提交、轮询、取片" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/ai-model/models" title="模型列表" description="当前 key 可用的模型" />
</Cards>

## 账户接口

令牌、用量、日志、充值等——你自己账户下可调用的接口。

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/token-management" title="令牌" description="创建、查询、删除自己的令牌" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/logs" title="日志与用量" description="调用记录与消耗统计" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/payment" title="充值" description="余额与充值记录" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-management" title="账户" description="个人信息、密钥、安全设置" />
</Cards>


# Antigravity CLI（agy）

Antigravity CLI（命令 `agy`）是 Google Antigravity 的终端版，和开源的 Gemini CLI 不是同一个工具。接入 VibeAPI 后走 Gemini 原生协议，**只能用 Gemini 模型**，不需要登录 Google 账号。

**前提**：agy 1.3.5 及以上；令牌能用 Gemini 模型。

## 配置

下面的命令里，把 `sk-xxx` 换成你的令牌。令牌能用 Gemini 模型时，`setup` 会自动配置 agy；还没有安装 agy 的，它会问你是否安装，安装好再写配置：

```bash
vibecli setup --key sk-xxx
```

只让 agy 使用这个令牌：

```bash
vibecli setup --agykey sk-xxx
```

配置完成后，在任何终端都能直接运行 `agy`，用 `/model` 或 `--model` 选择模型。菜单里是这个令牌能用、agy 也认识的 Gemini 模型（如 Gemini 4 Argon、Gemini 3.8 Flash），第一个是默认模型。在新开的终端里，菜单还会带思考档位（低 / 中 / 高）。

## 写了什么

<ThemeImage light="/img/coding-tools/agy-files.svg" dark="/img/coding-tools/agy-files-dark.svg" alt=".antigravity/settings.json 写网关地址、令牌、模型列表；菜单变量文件只有思考档位，不含令牌；shell 配置加一行加载它" />

<Accordions>
  <Accordion title="详细字段">
    | 位置                                        | 写入                                                              |
    | ----------------------------------------- | --------------------------------------------------------------- |
    | `~/.antigravity/settings.json`（权限 `0600`） | `gateway`：VibeAPI 地址、你的令牌、Gemini 原生协议；`models`：模型列表和默认模型。其它设置保留 |
    | `~/.gemini/antigravity-cli/` 下的菜单变量文件     | 只有 `AGY_LLM_GATEWAY_MODELS`（带思考档位的菜单），不含令牌                      |
    | shell 配置（`.zshrc` / `.bashrc` 等）          | 加一行加载上面这个文件，行尾带 `# vibecli:agy` 标记；Windows 上写成用户环境变量            |

    旧版本 VibeCLI 写过的 `modelProvider: "gemini"` 和 `GEMINI_API_KEY` 会被清掉。
  </Accordion>
</Accordions>

## 验证

运行 `agy`，发一句话能正常回复即配置完成。

## 为什么这样设计

<Fields>
  <Field name="令牌写在 agy 自己的设置文件里" type="不靠环境变量">
    agy 每次启动都读 `~/.antigravity/settings.json`，写进去后任何终端立即生效，已经打开的终端也不用重开。早期 VibeCLI 只用环境变量传令牌，Windows 上已打开的终端拿不到新变量，用户因此看不到新模型。
  </Field>

  <Field name="菜单变量不含令牌" type="shell 配置可以放心同步">
    思考档位只能通过环境变量传给菜单，所以另写一个只含菜单的变量文件。shell 配置常被 dotfiles 仓库同步到网上，里面不放令牌。
  </Field>

  <Field name="最低 1.3.5" type="只验证过这一版">
    网关模式只在 1.3.5 上完整验证过，更早的版本不保证可用。
  </Field>
</Fields>

## 排障

| 现象        | 原因                      | 处理                                          |
| --------- | ----------------------- | ------------------------------------------- |
| 菜单里没有思考档位 | 在配置前就打开的终端里运行           | 新开一个终端                                      |
| 菜单里少了某个模型 | 这个令牌用不了它，或 agy 还不认识这个模型 | 在控制台确认令牌的分组；运行 `vibecli upgrade agy` 升级 agy |
| 提示版本过旧    | 低于 1.3.5                | 运行 `vibecli upgrade agy`                    |

## 移除

运行 `vibecli config agy remove`，或在 `vibecli config agy` 的菜单里选「移除」：删掉 `settings.json` 里的 `gateway`、`models`，以及菜单变量文件和 shell 配置里那一行；Windows 上删掉 VibeCLI 写的用户环境变量。之后 agy 回到 Google 账号登录。


# Claude Code

**前提**：Claude Code 2.1.291 及以上；令牌能用 Claude 模型。还没有安装 Claude Code 的，`setup` 会问你是否安装，也可以先用[安装命令](https://docs.vibeapi.cn/zh/docs/coding-tools#手动安装)安装。

## 配置

下面的命令里，把 `sk-xxx` 换成你的令牌。令牌能用 Claude 模型时，`setup` 会自动配置 Claude Code：

```bash
vibecli setup --key sk-xxx
```

只让 Claude Code 使用这个令牌：

```bash
vibecli setup --claudekey sk-xxx
```

打开菜单，选择模型、写入配置、移除或还原：

```bash
vibecli config claude-code
```

配置完成后**新开一个终端**，运行 `claude`。

一般不需要指定模型，默认用 Claude Code 自带的档位。

指定 Opus 档位使用的模型：

```bash
vibecli config tool-model set claude-code opus 'claude-opus-5-5[1m]'
```

再把它写进 Claude Code：

```bash
vibecli config claude-code --yes
```

取消指定，改回 Claude Code 的默认：

```bash
vibecli config claude-code clear-model
```

## 写了什么

<ThemeImage light="/img/coding-tools/claude-code-files.svg" dark="/img/coding-tools/claude-code-files-dark.svg" alt="settings.json 写地址、令牌、模型菜单；.claude.json 只跳过首次引导；shell 配置里删掉旧变量" />

<Accordions>
  <Accordion title="详细字段">
    | 文件                                          | 写入                                                                                                                                                                                                   | 保留                            |
    | ------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
    | `~/.claude/settings.json`                   | `env.ANTHROPIC_BASE_URL`、`env.ANTHROPIC_AUTH_TOKEN`；推荐环境变量（工具搜索、较长的请求超时、关闭非必要流量等）；`/model` 菜单里的其它模型（`modelPicker`）和它们的压缩点（`modelSettings`）；默认组合下顶层 `model: "opus[1m]"`；你没设置过的推荐设置（默认思考强度 `medium` 等） | hooks、MCP、权限、插件、你自己加的环境变量和菜单项 |
    | `~/.claude.json`                            | 只补 `hasCompletedOnboarding: true`，跳过首次登录引导                                                                                                                                                           | 项目信任状态、MCP 服务器等其它内容           |
    | shell 配置（Windows 上是用户环境变量和 PowerShell 配置文件） | 删掉 export 过的 `ANTHROPIC_API_KEY`、`ANTHROPIC_BASE_URL`、`ANTHROPIC_*_MODEL`                                                                                                                            | 其它内容                          |
  </Accordion>
</Accordions>

`settings.json` 里旧的 `ANTHROPIC_API_KEY` 会被删掉，统一用 `ANTHROPIC_AUTH_TOKEN`。

## 验证

1. 新开终端，运行 `claude`，输入 `/status`：Anthropic base URL 应是 VibeAPI 的地址，认证来源是 auth token。
2. 输入 `/model`：能看到 Opus、Sonnet 等档位，后面是这个令牌能用的 GPT、Gemini、Grok、国产模型。
3. 发一句话，能正常回复即配置完成。

也可以运行 `vibecli doctor --deep`：它检查配置是否仍指向 VibeAPI，并通过 Claude Code 实际发一条请求（消耗少量额度）。

## 为什么这样设计

<Fields>
  <Field name="默认不指定模型" type="用 Claude Code 自带的档位">
    用默认组合时不写模型变量，Claude Code 升级后的新模型会自动出现在 `/model` 里；只有你明确选了别的模型才写。
  </Field>

  <Field name="档位回退" type="令牌用不了内置模型时">
    <ThemeImage light="/img/coding-tools/cc-tier.svg" dark="/img/coding-tools/cc-tier-dark.svg" alt="令牌能用档位默认模型就照用，用不了就换成同系列第一个能用的 Claude 模型，不换成 GPT" />

    换成能用默认模型的令牌后重新配置，回退会自动撤掉。
  </Field>

  <Field name="/model 里的其它模型" type="GPT / Gemini / Grok / 国产">
    <ThemeImage light="/img/coding-tools/cc-menu.svg" dark="/img/coding-tools/cc-menu-dark.svg" alt="/model 菜单：Claude 自带档位，后面追加 GPT、Gemini、Grok、国产模型" />

    上下文达到 100 万 token 的模型写成 `<模型名>[1m]`，每个模型用到 80% 时自动压缩。最低版本定为 2.1.291：按模型设置压缩点从 2.1.288 起生效，2.1.288–2.1.290 有退出时丢消息的问题。
  </Field>

  <Field name="为什么用 AUTH_TOKEN" type="不用 ANTHROPIC_API_KEY">
    `ANTHROPIC_AUTH_TOKEN` 是给网关用的 Bearer 凭据，`ANTHROPIC_API_KEY` 是直连 Anthropic 用的。两个同时存在会互相干扰，所以只保留前者。
  </Field>

  <Field name="清掉冲突的环境变量" type="只在配置时清">
    <ThemeImage light="/img/coding-tools/cc-env.svg" dark="/img/coding-tools/cc-env-dark.svg" alt="shell 里 export 的变量优先级更高，会盖过 settings.json，所以配置时删掉" />

    只在 `setup`、`config` 这类配置命令里删；`doctor`、`base` 不删，以免影响靠这些变量手动接入的用户。
  </Field>

  <Field name="推荐设置只补不改" type="你的设置优先">
    你设置过的值都保留，只补没设置过的；只有「显示思考摘要」始终打开。
  </Field>

  <Field name="自动模式的安全检查" type="CLAUDE_CODE_AUTO_MODE_SERVER=0">
    经第三方网关时，服务端安全检查不可用，每个动作都会停下等你回车。写入这个变量后改用本地检查；你设置过就不覆盖。
  </Field>

  <Field name="官方插件" type="只安装一次">
    <ThemeImage light="/img/coding-tools/cc-plugins.svg" dark="/img/coding-tools/cc-plugins-dark.svg" alt="官方插件先从国内镜像市场安装，无法连接再用 GitHub 官方市场，都无法连接就跳过" />

    安装 code-review、feature-dev、frontend-design 等 10 个插件，每个只安装一次，你卸载的不会再装回来；其余插件在 Claude Code 里用 `/plugin` 自选。安装插件需要 Git。
  </Field>
</Fields>

## 修改后要不要重启

已经打开的 Claude Code 会话读的是旧配置，**重开一个会话**即可。删了 shell 里的环境变量时，还要**新开一个终端**。

## 排障

| 现象                      | 原因                                      | 处理                                                           |
| ----------------------- | --------------------------------------- | ------------------------------------------------------------ |
| `/status` 里地址不是 VibeAPI | shell 或企业托管配置里的变量盖过了 settings.json      | 新开终端；运行 `vibecli doctor`，它会指出托管配置                            |
| 第一条请求就报模型不存在            | 令牌的分组没有 Claude Code 默认的模型               | 重新运行 `vibecli setup --key <你的令牌>`，给这个档位换成能用的模型               |
| `/model` 里缺某个模型         | 这个令牌用不了它，或菜单还没同步                        | 在控制台确认令牌的分组；重新运行 `vibecli setup --key <你的令牌>` 立即同步           |
| 提示版本过旧                  | Claude Code 低于 2.1.291                  | 运行 `vibecli upgrade claude-code`；更新渠道是 `stable` 时改成 `latest` |
| Windows 上提示未安装 Git      | 没有 Git 时 Claude Code 改用 PowerShell 执行命令 | 用[安装命令](https://docs.vibeapi.cn/zh/docs/coding-tools#手动安装)安装 Git                    |
| 插件没有安装                  | 未安装 Git，或镜像和 GitHub 都无法连接               | 安装 Git 或等网络恢复后，在 Claude Code 里用 `/plugin` 安装                 |

## 移除

运行 `vibecli config claude-code remove`，或在 `vibecli config claude-code` 的菜单里选「移除」：删掉 VibeAPI 的地址、令牌和菜单项，其它设置保留。想回到 VibeCLI 修改前的状态，运行 `vibecli config claude-code restore`。


# Claude Desktop

**前提**：Claude Desktop 2.2553.0 及以上；令牌能用 Claude 模型。

## 配置

下面的命令里，把 `sk-xxx` 换成你的令牌。令牌能用 Claude 模型时，`setup` 在 macOS 和 Windows 上会一起配置桌面端；桌面端还没安装也会先写好配置，安装后打开即可使用：

```bash
vibecli setup --key sk-xxx
```

只让桌面端使用这个令牌：

```bash
vibecli setup --desktopkey sk-xxx
```

保留 Claude.ai 账号登录入口：

```bash
vibecli setup --desktopkey sk-xxx --claude-official on
```

打开菜单配置：

```bash
vibecli config claude-desktop
```

配置完成后要**完全退出 Claude Desktop 再打开**，只关窗口不够。VibeCLI 检测到桌面端正在运行时，会问你是否由它来重启。

## 写了什么

VibeCLI 在桌面端「第三方推理」的本地配置库里，新建并选中一条名为 `VibeAPI` 的配置：

| 内容     | 写入                                                       |
| ------ | -------------------------------------------------------- |
| 推理方式   | 网关（gateway），地址是 VibeAPI 根地址，凭据是你的令牌                      |
| 模型列表   | 这个令牌能用的 Claude 模型，第一个是默认模型；支持 1M 的标上 1M                  |
| 官方登录入口 | 默认隐藏 Claude.ai 登录（`--claude-official on` 保留）             |
| 功能开关   | 网页抓取、工具搜索、内置浏览器、扩展、SSH 远程会话、导入导出、MCP 超时等，默认打开；只在你没设置过时写入 |

你自己在桌面端保存的其它配置都保留。移除时，选中项会交还给你原来的配置。

配置库位置：macOS `~/Library/Application Support/Claude-3p/`，Windows `%LOCALAPPDATA%\Claude-3p\`，Linux `~/.config/Claude-3p/`。

## 验证

1. 完全退出并重新打开 Claude Desktop。
2. 设置里的推理方式显示为第三方网关，选中的是 `VibeAPI`。
3. 模型菜单里是这个令牌能用的 Claude 模型，支持 1M 的显示 1M。
4. 发一句话，能正常回复即配置完成。

## 聊天记录

第三方推理模式下，聊天记录只存在这台电脑上。VibeCLI 默认打开了导入导出：在 **Settings → Import & export → Export…** 导出成 zip，换电脑后在 **Import…** 里选它导回去；claude.ai 网页上的历史也能从这里导入。步骤见[导出与迁移聊天记录](https://docs.vibeapi.cn/zh/docs/coding-tools/history#claude-desktop)。

## 为什么这样设计

<Fields>
  <Field name="写本地配置，不用托管配置" type="不需要管理员，不锁设置">
    <ThemeImage light="/img/coding-tools/desktop-layers.svg" dark="/img/coding-tools/desktop-layers-dark.svg" alt="有托管配置时桌面端只认它，本地配置库会被忽略；VibeCLI 写本地配置库，并提示移除托管配置" />

    托管配置要管理员或 root 权限才能安装，安装后设置窗口会被锁住；本地配置在三个平台上都不需要额外操作。
  </Field>

  <Field name="模型列表按令牌生成" type="不是固定三个">
    <ThemeImage light="/img/coding-tools/desktop-1m.svg" dark="/img/coding-tools/desktop-1m-dark.svg" alt="网关分组表标了 1M 才标；不确定时不标，标错会报错" />

    写入这个令牌能用的 Claude 模型，数量随令牌的分组变化，不是固定的三个。
  </Field>

  <Field name="不写国产模型" type="桌面端会拦截">
    桌面端会剔除非 Anthropic 厂商的模型名，并弹出「配置需要注意」，所以国产模型只写进 Claude Code。
  </Field>

  <Field name="默认隐藏官方登录" type="避免误登官方账号">
    登录官方账号后，请求不再经过 VibeAPI。需要在两边切换的，用 `--claude-official on`。
  </Field>

  <Field name="功能开关默认打开" type="你改过的不动">
    只在你没设置过时打开；关闭遥测的设置保持不变。打开 SSH 远程会话后，令牌会被带到你选的远程主机上。
  </Field>

  <Field name="Windows 的注册表" type="兼容老用户">
    <ThemeImage light="/img/coding-tools/desktop-windows.svg" dark="/img/coding-tools/desktop-windows-dark.svg" alt="能确定桌面端读本地配置时，只写本地配置库并清掉旧注册表值；不能确定时，本地配置库和注册表策略都写" />

    注册表策略存在时，桌面端不读本地配置，普通权限也改不了它（以前从网关页面下载 .reg 的用户就有这一层）。需要删除旧值时，VibeCLI 会问你一次，再弹一次管理员确认。「不能确定」包括还没安装桌面端、应用商店版还没启动过。仍然不生效，用 `vibecli setup --desktop-registry on` 固定写注册表。
  </Field>
</Fields>

## 排障

| 现象                             | 原因                                                 | 处理                                                                                     |
| ------------------------------ | -------------------------------------------------- | -------------------------------------------------------------------------------------- |
| 重开后仍不是 VibeAPI                 | 只关了窗口，没有完全退出；或有托管配置                                | 从托盘 / 菜单栏完全退出再打开；运行 `vibecli doctor` 检查托管配置                                            |
| Windows 上始终不生效                 | 注册表里有旧的 .reg 配置                                    | 运行 `vibecli setup --desktopkey <你的令牌>`，按提示确认，在系统弹窗里点击「是」；仍不生效用 `--desktop-registry on` |
| 报 `ERR_CERT_AUTHORITY_INVALID` | 当前网络把域名解析到了别的服务器                                   | 运行 `vibecli base auto` 换到备用地址；或换网络、改用公共 DNS                                            |
| 提示「配置需要注意」                     | 配置里有桌面端不接受的模型名                                     | 重新运行 `vibecli setup --desktopkey <你的令牌>`，VibeCLI 不写国产模型                                |
| 模型菜单里没有 1M                     | 你的分组没有给这个模型开启 1M                                   | 在控制台查看分组说明                                                                             |
| `setup --key` 跳过了桌面端           | 在 Linux 上且没有安装桌面端（Linux 上只配置已安装的），或令牌不能用 Claude 模型 | 在 macOS / Windows 上运行，或换一个能用 Claude 模型的令牌                                              |

## 移除

运行 `vibecli config claude-desktop remove`，或在 `vibecli config claude-desktop` 的菜单里选「移除」：删掉 `VibeAPI` 这条配置，并把选中项交还给你原来的配置；Windows 上同时清掉 VibeCLI 写过的注册表值。

只删模型列表、让桌面端自动发现模型：

```bash
vibecli config claude-desktop clear-model
```


# Codex

**前提**：Codex 0.122.0 及以上；令牌能用 GPT 模型。命令行和桌面版共用同一份配置，配置一次两边都能用。

## 配置

下面的命令里，把 `sk-xxx` 换成你的令牌。令牌能用 GPT 模型时，`setup` 会自动配置 Codex：

```bash
vibecli setup --key sk-xxx
```

只让 Codex 使用这个令牌：

```bash
vibecli setup --codexkey sk-xxx
```

关闭 1M 上下文（只改上下文设置，不动令牌）：

```bash
vibecli setup --no-1m
```

重新打开 1M 上下文：

```bash
vibecli setup --1m
```

指定默认模型：

```bash
vibecli config tool-model set codex gpt-6-astra
```

再把它写进 Codex：

```bash
vibecli config codex --yes
```

配置完成后，**完全退出 Codex（包括桌面版）再打开**。

## 写了什么

<ThemeImage light="/img/coding-tools/codex-files.svg" dark="/img/coding-tools/codex-files-dark.svg" alt="config.toml 写服务商和默认模型，auth.json 写令牌，模型目录文件写各模型的上下文" />

<Accordions>
  <Accordion title="详细字段">
    | 文件                                    | 写入                                                                                                                                                                | 保留                    |
    | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
    | `~/.codex/config.toml`                | 服务商 `[model_providers.custom]`（VibeAPI 地址、Responses 协议、从 `auth.json` 取凭据）；`model_provider = "custom"`；默认模型（`gpt-6-astra`）与思考强度 `high`；`model_catalog_json` 指向模型目录 | 你的 MCP、权限、沙箱、其它服务商等设置 |
    | `~/.codex/auth.json`                  | `auth_mode: "apikey"` 和你的令牌                                                                                                                                       | —                     |
    | `~/.codex/vibeapi-model-catalog.json` | 模型目录：Codex 自带的 GPT 模型，加上这个令牌能用的 Claude、Gemini、Grok、国产模型，每个模型带自己的上下文窗口和自动压缩点                                                                                       | —                     |
  </Accordion>
</Accordions>

服务商下如果有 cc-switch 等工具留下的 `experimental_bearer_token`，VibeCLI 会删掉它（原因见下文）。

## 验证

1. 完全退出 Codex 再打开（命令行重新运行 `codex`）。
2. 打开模型菜单：能看到 GPT 模型，以及这个令牌能用的 Claude、Gemini、Grok、国产模型。
3. 发一句话，能正常回复即配置完成。命令行里可以用 `/status` 确认当前服务商和模型。

## 为什么这样设计

<Fields>
  <Field name="令牌只放在 auth.json" type="不写进 config.toml">
    <ThemeImage light="/img/coding-tools/codex-auth.svg" dark="/img/coding-tools/codex-auth-dark.svg" alt="服务商下有 bearer token 时 Codex 优先用它，占位符会导致 401；VibeCLI 删掉它，令牌只放在 auth.json" />

    cc-switch 这类工具会在服务商下留下 `PROXY_MANAGED` 占位符，Codex 会优先发送它，导致 401。令牌也不写在这里，以免你切换到别的服务商时被一起带过去。
  </Field>

  <Field name="为什么要写模型目录" type="菜单里才有 Claude 等模型">
    <ThemeImage light="/img/coding-tools/codex-catalog.svg" dark="/img/coding-tools/codex-catalog-dark.svg" alt="模型目录由本机 Codex 导出的 GPT 条目和网关模型组成，整体替换 Codex 自带的目录" />

    使用自定义服务商时，Codex 不向网关请求模型列表，不写目录的话菜单里只有 GPT。导出自带目录的功能从 0.122 开始才有，所以最低版本是 0.122。
  </Field>

  <Field name="每个模型各用各的窗口" type="不写全局上下文设置">
    每个模型带自己的上下文窗口，用到 80% 时自动压缩。不写全局上下文设置，因为它会盖掉所有模型的值。1M 默认开启，关闭后上下文不超过 272K。
  </Field>

  <Field name="菜单只列令牌能用的模型" type="auto 分组看到的更少">
    auto 分组的令牌看到的模型比官方分组少，这是正常的。Claude 每个系列只放最新的一个。
  </Field>

  <Field name="旧会话为什么会不见" type="vibecli codex sessions">
    <ThemeImage light="/img/coding-tools/codex-sessions.svg" dark="/img/coding-tools/codex-sessions-dark.svg" alt="Codex 会话列表只显示服务商与当前一致的会话；codex sessions 命令把它们改成当前服务商" />

    `setup` 配置好 Codex 后，如果发现以前的会话，会问你是否搬过来。当时没有搬的，之后运行 `vibecli codex sessions`。改之前会先备份，`--undo` 可以撤销；Codex 正在运行时它会拒绝执行。
  </Field>
</Fields>

## 排障

| 现象                                                      | 原因                                                  | 处理                                                                  |
| ------------------------------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------- |
| `401 Unauthorized: Invalid token`，同一个令牌在 Claude Code 能用 | `config.toml` 里有切换工具留下的占位令牌，或 Codex 用 ChatGPT 账号登录过 | 运行 `vibecli setup --codexkey <你的令牌>`，然后完全退出 Codex 再打开               |
| 以前的会话不见了                                                | 换过登录方式，会话的服务商对不上                                    | 退出 Codex 后运行 `vibecli codex sessions`                               |
| 菜单里只有 GPT                                               | 写目录时没找到本机的 Codex 程序，或版本低于 0.122                     | 先运行 `vibecli upgrade codex`，再重新运行 `vibecli setup --codexkey <你的令牌>` |
| 提示版本过旧                                                  | Codex 低于 0.122.0                                    | 运行 `vibecli upgrade codex`                                          |
| 上下文比预期小                                                 | 关闭过 1M                                              | 运行 `vibecli setup --1m`                                             |

## 移除

不再让 Codex 使用 VibeAPI（例如改回 ChatGPT 订阅）时，运行：

```bash
vibecli config codex remove
```

它删掉 VibeAPI 的服务商、令牌和模型目录引用，其它设置保留。之前在 Codex 里登录过 ChatGPT 的，会直接切回那个登录；没有登录过的，Codex 回到未登录状态，再运行下面的命令用 ChatGPT 订阅登录。Codex 桌面版要完全退出后重新打开，按提示登录。

```bash
codex login
```

这需要 VibeCLI 0.0.105 或更新版本。用旧版本移除后，Codex 仍会用 VibeAPI 的令牌登录（请求报 401），升级后再运行一次上面的移除命令即可。在 `vibecli config codex` 的菜单里选「移除」，效果相同。想回到 VibeCLI 修改前的状态，运行 `vibecli config codex restore`。


# 配置、备份与安全

## 文件在哪

<ThemeImage light="/img/coding-tools/config-files.svg" dark="/img/coding-tools/config-files-dark.svg" alt="配置目录里有 config.yaml、backups、日志；各工具配置旁边留最近 10 份 .bak 备份" />

<Accordions>
  <Accordion title="完整路径">
    | 内容            | 位置                                          |
    | ------------- | ------------------------------------------- |
    | VibeCLI 配置和令牌 | `~/.vibecli/config.yaml`，文件权限 `0600`（只有你能读） |
    | VibeCLI 自己的备份 | `~/.vibecli/backups/*.yaml`，同样 `0600`       |
    | 工具配置的备份       | 各工具配置文件旁边的 `<文件名>.bak-<时间>`，每个文件保留最近 10 份   |
    | 日志            | `~/.vibecli/<日期>.log`，按天一个文件，保留 14 天        |
  </Accordion>
</Accordions>

各工具自己的配置文件位置见[各工具一览](https://docs.vibeapi.cn/zh/docs/coding-tools/tools)。

`config.yaml` 的大致结构：

```yaml
active_profile: default
profiles:
  default:
    api_key: sk-...
    tool_api_keys:          # 可选：工具专属令牌，优先于 api_key
      codex: sk-...
    base_url: https://www.vibeapi.cn
    models:
      opus: claude-opus-5-5[1m]
      sonnet: claude-sonnet-5[1m]
    tool_models:            # 可选：按工具覆盖模型
      codex: { opus: gpt-6-astra }
```

## 令牌怎么保存

<ThemeImage light="/img/coding-tools/key-flow.svg" dark="/img/coding-tools/key-flow-dark.svg" alt="令牌保存在本机只有你能读的文件里，写进各工具配置；只发给内置接入地址和当前地址" />

令牌明文保存，文件权限 `0600`，换电脑不会因为加密绑定了机器而失效。请把用户目录和备份当作敏感数据。`vibecli status` 只显示令牌的指纹。

## 备份与还原

<ThemeImage light="/img/coding-tools/backup-flow.svg" dark="/img/coding-tools/backup-flow-dark.svg" alt="备份原文件 → 写临时文件 → 一次性替换，不会写一半" />

原文件已损坏（不是合法的 JSON / TOML）时，VibeCLI 拒绝写入；加 `--force` 才会先备份、再整份重写。还原前也会先备份当前状态，所以还原本身也能撤销。

| 命令                            | 作用       |
| ----------------------------- | -------- |
| `vibecli config <工具> restore` | 回到上一次修改前 |
| `vibecli config <工具> backups` | 列出所有备份   |

## 自动更新与模型同步

<ThemeImage light="/img/coding-tools/update-chain.svg" dark="/img/coding-tools/update-chain-dark.svg" alt="启动时检查新版，依次尝试高速下载站、npmjs、npmmirror、Yarn" />

<ThemeImage light="/img/coding-tools/menu.svg" dark="/img/coding-tools/menu-dark.svg" alt="网关模型清单和令牌能用的模型取交集，写进各工具菜单，最多每小时同步一次" />

只有全局安装时才自动更新（每次启动都检查新版本，更新失败不影响原命令）。用 `npx` 运行，或带 `--json`、`--non-interactive`、`--dry-run` 时不更新。模型菜单同步只改菜单，不动令牌和你选中的模型。

## 环境变量

| 变量                                | 作用                  |
| --------------------------------- | ------------------- |
| `VIBECLI_DISABLE_AUTO_UPDATE=1`   | 关闭启动时的自动更新          |
| `VIBECLI_DISABLE_MODEL_REFRESH=1` | 关闭模型菜单的自动同步         |
| `VIBECLI_CONFIG_DIR`              | 把 VibeCLI 的配置目录改到别处 |
| `NO_COLOR` / `FORCE_COLOR=0`      | 不输出颜色               |

## 退出码与错误输出

命令成功返回 0。失败时按原因返回固定退出码：

| 退出码 | 含义                       |
| --: | ------------------------ |
|   1 | 操作失败                     |
|   2 | 用法或输入错误                  |
|   3 | 认证失败，令牌无效或被拒绝            |
|   4 | 网络问题，例如 DNS、证书、超时或无法连接网关 |
|   5 | 内部错误                     |
|  10 | 需要确认；非交互模式下加 `--yes`     |
| 130 | 已取消                      |

普通模式下，错误写到 stderr，下一行给出完整的下一条 `vibecli` 命令。带 `--json` 时，失败只在 stderr 输出一个 JSON 对象，stdout 不输出内容；成功时 stdout 的 JSON 格式不变。失败时的输出示例：

```json
{"ok":false,"error":{"type":"authentication","message":"网关拒绝了这个令牌，它可能已被删除、停用或已过期","hint":"vibecli setup --key <你的令牌>","subtype":"invalid_api_key"}}
```


# 常见问题

遇到问题先运行 `vibecli doctor`，它会检查网络、证书、令牌、工具版本和配置是否生效，并给出下一步。

## 一键安装

* **PowerShell 报「标记“&&”不是此版本中的有效语句分隔符」，或 cmd 报「'sh' 不是内部或外部命令」**：复制了 macOS 的命令，请换成 Windows 标签页里的命令。
* **Mac 弹出「命令行开发者工具」安装窗口**：点击「安装」，它会安装 Git；在后台下载，不影响其它步骤。
* **令牌粘贴错了**：会提示重新粘贴，最多三次。
* **不要在命令前加 `sudo`**：工具都安装在你自己的用户目录里。
* **Claude Desktop 还没有安装**：配置已经先写好，安装后打开即可使用。

- **vibecli.cn 无法打开**：把命令里的 `https://vibecli.cn` 换成 `https://cnb.cool/vibeapi/install/-/git/raw/main/vibecli.sh`（Windows 换成 `…/vibecli.ps1`），单个工具同理换成同目录下的同名文件。

## 提示 `command not found: npx`，或安装后找不到 `node`、`claude`

`command not found: npx`：电脑上还没有 Node.js，用[一键安装命令](https://docs.vibeapi.cn/zh/docs/coding-tools)从头安装。

安装后找不到命令：

<ThemeImage light="/img/coding-tools/faq-path.svg" dark="/img/coding-tools/faq-path-dark.svg" alt="安装脚本是终端的子进程，改不了当前终端已经读入的 PATH，只能写进 shell 配置文件，重新加载后才生效" />

在当前窗口运行一次（页面上的安装命令末尾已经带了这一句）：

```bash
exec "$SHELL" -l
```

Windows 上安装后当前窗口即可使用，之前打开的其它窗口要重新打开。

## 配置后，Claude Code 仍没有使用 VibeAPI

常见原因是 shell 配置里 export 过 `ANTHROPIC_API_KEY`、`ANTHROPIC_BASE_URL`，它们会盖过配置文件。VibeCLI 配置 Claude Code 时会自动删掉这些行，删完要**新开一个终端**，并重开 Claude Code 会话。企业电脑上还可能有托管配置覆盖了地址或令牌，`vibecli doctor` 会指出来。

## 提示「证书不对」「连接不是私密连接」，或一直超时

这不是令牌的问题：当前网络（常见于校园网、酒店网络）把 `www.vibeapi.cn` 解析到了别的服务器。运行 `vibecli base auto` 换到能用的备用地址，已配置的工具会一起换过去；网络恢复后运行 `vibecli base default` 回到主站。也可以换一个网络，或把 DNS 改成公共 DNS（如 119.29.29.29）。用 Clash 这类代理时，确认它的 DNS 设置已生效（配置里应写 `dns: enable: true`，写成 `enabled` 不生效）。

## Codex 报 401，同一个令牌在 Claude Code 里能用

常见原因有两种：`~/.codex/config.toml` 里有 cc-switch 等工具留下的 `experimental_bearer_token`，Codex 会优先发送它，而不是你的令牌；或者 Codex 用 ChatGPT 账号登录过。运行 `vibecli setup --codexkey <你的令牌>`（或 `--key`）重新配置即可修复，然后完全退出 Codex 再打开。

## 换了登录方式，Codex 里以前的会话不见了

会话还在本地，只是 Codex 只显示和当前服务商一致的会话。完全退出 Codex（包括桌面版）后运行 `vibecli codex sessions`，可以用 `--undo <备份目录>` 撤销。换电脑后怎么把会话搬过去，见[导出与迁移聊天记录](https://docs.vibeapi.cn/zh/docs/coding-tools/history#codex)。

## Windows 上配置了 Claude Desktop，重开后仍没有使用 VibeAPI

多半是以前从网关页面下载的 .reg 写进了注册表 `HKCU\SOFTWARE\Policies\Claude`：这一层存在时，桌面端不读本地配置，普通权限也改不了它。运行 `vibecli setup --desktopkey <你的令牌>`，按提示确认，在系统弹窗里点击「是」；仍不生效就运行 `vibecli setup --desktop-registry on`。修改后要**完全退出**桌面端再打开。

## Windows 提示「禁止运行脚本」

PowerShell 默认不允许运行脚本，一键安装命令、`npm`、`npx` 都会被拦截。运行一次下面的命令（只改当前用户，不需要管理员权限），再重新运行原来的命令：

```powershell
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
```

## 提示工具版本过旧，或 `claude update` 无法连接

运行 `vibecli upgrade`（或 `vibecli upgrade claude-code`）。官方渠道无法连接时，它改用国内镜像下载同一个官方程序；电脑上有多份安装时，询问后只保留最新的一份。还没有安装的，用[安装命令](https://docs.vibeapi.cn/zh/docs/coding-tools#手动安装)。

## Claude Code 的 `/model` 菜单里看不到某个模型

菜单只列这个令牌能调用的模型，先在控制台确认令牌的分组。网关新上架的模型，VibeCLI 最多一小时后同步进菜单；想立即更新，运行 `vibecli refresh`，或重新运行 `vibecli setup --key <你的令牌>`。

## 指定过模型，想恢复工具自己的默认

```bash
vibecli config claude-code clear-model
```

只删掉指定的模型，令牌、hooks、MCP、插件都保留。其它工具把 `claude-code` 换成对应的名字即可。

## 工具的配置改坏了

| 命令                            | 作用                |
| ----------------------------- | ----------------- |
| `vibecli config <工具> restore` | 回到上一次 VibeCLI 修改前 |
| `vibecli config <工具> --force` | 先备份，再整份重写为推荐配置    |

## Antigravity CLI 提示没有设置 GEMINI\_API\_KEY

这是旧版 VibeCLI 留下的配置。升级 VibeCLI 后重新运行 `vibecli setup --key <你的令牌>`（或 `vibecli config agy`），配置会改为写进 agy 自己的设置文件，任何终端都能直接使用；同时确认 agy 在 1.3.5 及以上（`vibecli upgrade agy`）。

## 命令失败时怎么看退出码

脚本或 CI 可以按退出码处理失败：2 是用法错误，3 是认证失败，4 是网络问题，1 是其它操作失败，完整列表见[配置、备份与安全](https://docs.vibeapi.cn/zh/docs/coding-tools/config#退出码与错误输出)。需要程序读取时加 `--json`，错误对象只写到 stderr。


# Grok Build

**前提**：令牌能用 Grok 模型。还没有安装 Grok Build 的，用[安装命令](https://docs.vibeapi.cn/zh/docs/coding-tools#手动安装)从国内镜像安装（官方安装地址 `x.ai/cli/install.sh` 在国内网络下无法访问），或者在 `vibecli setup` 问你是否安装时选「是」。

## 配置

下面的命令里，把 `sk-xxx` 换成你的令牌。令牌能用 Grok 模型时，`setup` 会自动配置 Grok Build：

```bash
vibecli setup --key sk-xxx
```

只让 Grok Build 使用这个令牌：

```bash
vibecli setup --grokkey sk-xxx
```

打开菜单配置：

```bash
vibecli config grok
```

然后运行 `grok`。思考强度可以在 `/model` 里选，也可以启动时指定：

```bash
grok --effort high
```

## 写了什么

`~/.grok/config.toml`：

| 写入                       | 内容                                                                         |
| ------------------------ | -------------------------------------------------------------------------- |
| `[endpoints]`            | 指向 VibeAPI 的地址                                                             |
| `[model."vibeapi-<模型>"]` | 这个令牌能用的每个 Grok 模型各一条，带令牌、上下文窗口和 `low` / `medium` / `high` / `xhigh` 四档思考强度 |
| `[models].default`       | 当前默认模型，默认是 `vibeapi-grok-4.6`                                              |

你自己写的其它模型条目和界面设置都保留。

## 验证

运行 `grok`，在 `/model` 里能看到这个令牌能用的 Grok 模型，发一句话能正常回复即配置完成。

## 为什么这样设计

<Fields>
  <Field name="每个模型一条，带 vibeapi- 前缀" type="能在 /model 里切换">
    <ThemeImage light="/img/coding-tools/grok-entries.svg" dark="/img/coding-tools/grok-entries-dark.svg" alt="config.toml 里每个模型写一条带前缀的条目，/model 可切换；你自己写的条目原样保留" />

    Grok Build 只在设置了 `XAI_API_KEY` 时才向网关请求模型清单，多数人没有设置，所以 VibeCLI 把模型逐条写进配置。
  </Field>

  <Field name="令牌直接写进配置" type="不另设环境变量">
    你不需要再维护一个环境变量；配置文件只在你的用户目录下。
  </Field>
</Fields>

## 移除

运行 `vibecli config grok remove`，或在 `vibecli config grok` 的菜单里选「移除」：删掉 `vibeapi-` 开头的条目、指向它们的默认模型和 `[endpoints]` 里的 VibeAPI 地址。


# 导出与迁移聊天记录

通过 VibeAPI 使用编码工具时，聊天记录只存在你自己的电脑上，VibeAPI 不保存你的对话。换电脑、重装系统之前，需要你自己导出。下面命令里的 `sk-xxx` 换成你的令牌。

| 工具              | 有没有官方导出                          | 换电脑后怎么导回去                           |
| --------------- | -------------------------------- | ----------------------------------- |
| Claude Desktop  | 有：设置 → Import & export → Export… | 新电脑上 Import… 选那个 zip                |
| Claude Code（终端） | 没有，复制会话文件夹                       | 放回同一位置，`claude --resume` 接着聊        |
| Codex（命令行和桌面版）  | 没有，复制会话文件夹                       | 放回同一位置，再运行 `vibecli codex sessions` |

## 让 AI 帮你做

不想自己找文件夹，可以给 Claude Code、Codex 这类编码助手安装一个 Skill。把下面这句话发给它：

```text
帮我安装这个 Skill：https://docs.vibeapi.cn/agent-history-skill.zip
```

安装后直接对它说「帮我把 Codex 的聊天记录导出来」「换了电脑，帮我把 Claude Code 的会话导回去」「Codex 里以前的会话不见了」「把这几个会话存成 Markdown」。它会先备份、只复制不删除，打包好的文件放在你指定的位置。

## 以前用官方账号，换到 VibeAPI

以前用 Claude 账号、ChatGPT 账号登录，现在改用 VibeAPI 的令牌，原来的聊天记录都能接着用：

| 工具              | 原来的记录在哪                  | 怎么接上                                              |
| --------------- | ------------------------ | ------------------------------------------------- |
| Claude Desktop  | claude.ai 云端             | 在桌面端导入 claude.ai 的历史                              |
| Claude Code（终端） | 本机 `~/.claude/projects/` | 不用搬，配置后直接 `claude --resume`                       |
| Codex（命令行和桌面版）  | 本机 `~/.codex/sessions/`  | 不用搬，`setup` 时同意搬会话，或运行一次 `vibecli codex sessions` |

**Claude Desktop**：

1. 用 VibeCLI 配置桌面端，然后完全退出 Claude Desktop 再打开：

```bash
vibecli setup --desktopkey sk-xxx
```

2. 进入 **Settings → Import & export**，点击 **Import…**。
3. 第一步点击 **Sign in to claude.ai…**，在浏览器里登录原来的账号、点击 **Authorize**，回到桌面端点击 **Fetch export**。
4. 一路点击 **Continue**，最后点击 **Import**。

以前在官方模式下用过的 Cowork 任务和 Code 会话存在本机，导入向导第二步会一起列出来，勾选即可。附件和项目知识库文件不会导出，这是 claude.ai 的规定。Team、Enterprise 账号要先由空间所有者在 claude.ai 打开「Allow members to export their own data」。

**Claude Code**：会话记录和登录方式无关。用下面的命令配置好令牌后，在原来的项目目录里运行 `claude --resume` 就能看到以前的会话，接着聊即可。

```bash
vibecli setup --key sk-xxx
```

**Codex**：会话也在本机，只是 ChatGPT 账号登录时记的服务商是 `openai`，VibeAPI 是 `custom`。Codex 只列出和当前服务商一致的会话，所以换过来后列表是空的。`setup` 配置好 Codex 后，发现以前的会话会问你是否搬过来，选「是」即可。当时没有搬的，完全退出 Codex（包括桌面版）后运行：

```bash
vibecli codex sessions
```

再打开 Codex，以前的会话就回来了，可以接着聊。用 [Codex++](https://github.com/BigPizzaV3/CodexPlusPlus) 管理桌面版的，它的「供应商切换」也会同步会话，两种方法选一种即可。

桌面版侧边栏仍然没有旧会话时，先把 VibeCLI 升级到 0.0.129 或更新的版本，再运行一次：新版桌面端另有一份会话目录，旧版本的 VibeCLI 不会修改它。

## Claude Desktop

用 VibeCLI 配置的 Claude Desktop，默认打开了导入和导出。

### 导出

1. 打开 Claude Desktop，进入 **Settings**（macOS 快捷键 ⌘,）。
2. 在左侧点击 **Import & export**，再点击 **Export…**。
3. 选择时间范围（Last 30 days / Last 90 days / Everything），点击 **Export**。

文件保存在「下载」文件夹，名字是 `claude-desktop-export-年月日.zip`。

| 包含                           | 不包含                      |
| ---------------------------- | ------------------------ |
| Chat、Cowork 任务、Code 标签页里的会话  | 你上传的附件                   |
| Claude 生成的文件（每个会话 100 MB 以内） | 项目指令、记忆、定时任务、技能、插件、设置    |
| 项目名称                         | 终端里的 Claude Code 会话（见下文） |

这个 zip 里是完整的对话内容，按私人文件保管，用完删掉。

### 在新电脑上导入

1. 在新电脑上安装 Claude Desktop，用 VibeCLI 配置：

```bash
vibecli setup --desktopkey sk-xxx
```

2. 进入 **Settings → Import & export**，点 **Import…**。
3. 第一步 **Chats** 点击 **Choose file…**，选择导出的 zip。
4. 第二步 **Cowork & Code** 会列出 zip 里的会话，以及这台电脑上能找到的其它会话。不想导入的来源，取消勾选。
5. 第三步 **Review** 点击 **Import**。

导入的会话出现在左侧列表里。第一次在导入的会话里发消息时，会弹出 **Resume imported session?**，点击 **Trust and resume**。

<Callout type="warn" title="不要在原来那台电脑上导入它自己导出的 zip">
  那样每个会话都会多出一份。导错了，到 **Settings → Import & export → Import history**，在那次导入后面点击 **Remove**，只删导入进来的副本，原来的会话不受影响。
</Callout>

### claude.ai 网页上的历史

在 **Import…** 的第一步点击 **Sign in to claude.ai…**，登录授权后点击 **Fetch export**，网页版的对话和项目会导入桌面端，之后接着聊时请求经过 VibeAPI。

也可以先在 claude.ai 的 **Settings → Privacy → Export data** 导出，收到邮件后下载 zip，再用 **Choose file…** 选它。附件和项目知识库文件不会导出。

### 没有 Import & export，或者没有 Export… 按钮

重新配置一次，VibeCLI 会补上导入导出开关：

```bash
vibecli setup --desktopkey sk-xxx
```

然后完全退出 Claude Desktop 再打开。还是没有，多半是公司电脑上有管理员下发的配置，它会盖过本机配置，需要管理员在配置里打开 `claudeAiImport` 的 `enabled` 和 `exportEnabled`。

### 存放位置

| 系统      | 目录                                         |
| ------- | ------------------------------------------ |
| macOS   | `~/Library/Application Support/Claude-3p/` |
| Windows | `%LOCALAPPDATA%\Claude-3p\`                |
| Linux   | `~/.config/Claude-3p/`                     |

Chat 和 Cowork 的会话在 `local-agent-mode-sessions/` 下；Code 标签页的会话记录在 Claude Code 自己的 `~/.claude/projects/` 里。

## Claude Code（终端）

会话记录在 `~/.claude/projects/` 下（Windows 是 `%USERPROFILE%\.claude\projects\`），每个项目一个文件夹，每个会话一个 `<会话ID>.jsonl` 文件。

**导出**：退出 Claude Code，把整个 `projects` 文件夹打包。只想把某个会话给人看，在会话里运行 `/export`，导出成纯文本。

**导回去**：把打包的文件夹放回新电脑的 `~/.claude/projects/`。项目路径和原来一样时，在项目目录里运行 `claude --resume` 就能在列表里看到。

路径不一样（比如用户名变了），列表里看不到，用会话 ID 直接接着聊：

```bash
claude --resume 会话ID
```

会话 ID 就是 `.jsonl` 的文件名。

想在 Claude Desktop 里看这些会话：Desktop 的 **Import…** 第二步会自动扫描 `~/.claude/projects`，勾上就能导进去。

## Codex

命令行和桌面版共用一个目录 `~/.codex/`（Windows 是 `%USERPROFILE%\.codex\`；设了 `CODEX_HOME` 就是那个目录）：

| 内容      | 位置                               |
| ------- | -------------------------------- |
| 会话记录    | `sessions/年/月/日/rollout-*.jsonl` |
| 已归档的会话  | `archived_sessions/`             |
| 会话列表的索引 | `state_*.sqlite`                 |

**导出**：完全退出 Codex（包括桌面版），打包 `sessions` 和 `archived_sessions` 两个文件夹。不要带上 `auth.json`，里面是你的令牌或登录信息。

**导回去**：

1. 在新电脑上用 VibeCLI 配置 Codex：

```bash
vibecli setup --key sk-xxx
```

2. 完全退出 Codex，把两个文件夹放进新电脑的 `~/.codex/`。索引不用拷，Codex 下次启动会自己补上。
3. 把会话改到当前服务商：

```bash
vibecli codex sessions
```

4. 打开 Codex，旧会话就在列表里了。

### 以前的会话不见了

会话文件还在，只是 Codex 只显示服务商和现在一致的会话。换过登录方式（在官方账号和令牌之间切换）、用过 cc-switch 这类切换工具，旧会话都会被隐藏。

完全退出 Codex（包括桌面版）后运行：

```bash
vibecli codex sessions
```

桌面版侧边栏里仍然没有的话，先把 VibeCLI 升级到 0.0.129 或更新的版本，再运行一次：新版桌面端另有一份会话目录，旧版本的 VibeCLI 不会修改它。

改之前会先备份，输出里有备份目录。想改回去：

```bash
vibecli codex sessions --undo 备份目录
```

还是找不到某个会话，用会话 ID 直接接着聊，ID 是 `rollout-*.jsonl` 文件名末尾那串：

```bash
codex resume 会话ID
```


# 工作原理与设计

## 一次 setup 做了什么

以 `vibecli setup --key sk-xxx` 为例：

<ThemeImage light="/img/coding-tools/setup-steps.svg" dark="/img/coding-tools/setup-steps-dark.svg" alt="确认接入地址 → 校验令牌 → 按令牌能用的模型选择工具 → 列出要改的文件并确认 → 保存令牌、备份并只改自己负责的字段 → 安装缺少的命令行工具，安装后再写配置" />

令牌无效时立即停下并说明原因，不写任何配置。在终端里运行时，VibeCLI 会先列出要修改的文件和要先安装的工具，你确认后才保存令牌、写配置；选「否」则什么都不改。加 `--yes`、`--non-interactive` 或 `--json` 时不询问。

还没有安装的命令行工具（Claude Code、Codex、Grok Build、agy）先安装、再写配置，不安装就不写。Claude Desktop 例外：在 macOS 和 Windows 上没安装也会先写好配置，安装后打开即可使用。

每个工具由独立的模块负责，一个工具出问题不影响别的工具。

## 只合并，不覆盖

<ThemeImage light="/img/coding-tools/merge.svg" dark="/img/coding-tools/merge-dark.svg" alt="同一个配置文件里，VibeCLI 只写地址、令牌、模型菜单；你的插件、MCP、hooks 原样保留" />

配置文件里大部分是你自己积累的设置，整份覆盖会抹掉它们。原文件已经损坏（不是合法的 JSON / TOML）时，VibeCLI 会停下提示，不猜测着修复；确实要重来，用 `--force`，它先完整备份再重写。

每次修改前，VibeCLI 在原文件旁边留一份 `<文件名>.bak-<时间>`（每个文件保留最近 10 份）。写入时先写临时文件再整体替换，中途被打断也不会留下写了一半的配置。卸载 VibeCLI 不影响已经配置好的工具。

## 令牌怎么保存、发给谁

<ThemeImage light="/img/coding-tools/key-flow.svg" dark="/img/coding-tools/key-flow-dark.svg" alt="令牌保存在本机只有你能读的文件里，写进各工具配置；只发给内置接入地址和当前地址，其它地址只测连通、不带令牌" />

令牌明文保存，不加密。早期的加密版本把密钥和主机名绑在一起，换电脑就解不开；而 Claude Code、Codex 本来就明文保存同一个令牌，再存一份加密副本并不更安全。`vibecli status` 只显示令牌的指纹。

令牌只发给 VibeCLI 内置的接入地址和你当前使用的地址。有人诱导你「试试这条线路」时，对方的地址拿不到令牌。

## 模型菜单从哪来

<ThemeImage light="/img/coding-tools/menu.svg" dark="/img/coding-tools/menu-dark.svg" alt="网关模型清单和令牌实测能用的模型取交集，写进各工具菜单，最多每小时同步一次" />

不同分组能用的模型不同，按分组名推算容易出错，所以 VibeCLI 直接用这个令牌请求模型列表。同步只改菜单，不动你选中的模型和令牌。工具里的令牌已经不是 VibeCLI 保存的那个时，跳过这个工具。

## 接入地址：按优先级，不按速度

<ThemeImage light="/img/coding-tools/base-auto.svg" dark="/img/coding-tools/base-auto-dark.svg" alt="主站无法连接 → 依次测试接入地址，取第一个能用的 → 已配置的工具一起换过去，令牌不用改" />

只有主站无法连接时才换，即使备用地址测速更快也不换。「能用」指用你的令牌实际拉到了模型列表。`--base` 在 `setup`、`init`、`auth`、`config` 和交互菜单里会保存，在其它命令里只对这一次有效。

## 升级与国内镜像

<ThemeImage light="/img/coding-tools/upgrade.svg" dark="/img/coding-tools/upgrade-dark.svg" alt="先用官方渠道升级，失败或超时改用国内镜像，最后只保留最新的一份" />

镜像里的程序和官方下载的是同一个文件，都核对过校验值。电脑上常有 npm 安装的和官方安装器安装的两份，VibeCLI 按终端实际运行的那份升级，再询问你是否删到只剩一份。

## VibeCLI 自己的更新

<ThemeImage light="/img/coding-tools/update-chain.svg" dark="/img/coding-tools/update-chain-dark.svg" alt="启动时检查新版，依次尝试高速下载站、npmjs、npmmirror、Yarn" />

只有全局安装时才自动更新（每次启动都检查新版本），更新失败不影响正在运行的命令。用 `npx` 运行，或带 `--json`、`--non-interactive`、`--dry-run` 时不更新；设置 `VIBECLI_DISABLE_AUTO_UPDATE=1` 可以关闭自动更新。


# 一键配置编码工具

import { Card, Cards } from 'fumadocs-ui/components/card';

先在控制台的[「令牌」页](https://www.vibeapi.cn/console/token)新建一个令牌并复制（`sk-` 开头），再把下面一条命令复制到终端运行，即可安装并配置好编码工具。

电脑上还没有 Node.js 和 Git 也可以运行：命令会自动安装它们。新 Mac 弹出「安装命令行开发者工具」时，点击「安装」即可。

<Tabs items={['macOS / Linux', 'Windows']}>
  <Tab value="macOS / Linux">
    运行后按提示粘贴令牌（显示为 `*`，回车后会告诉你令牌是否有效）：

    ```bash
    curl -fsSL https://vibecli.cn | sh && exec "$SHELL" -l
    ```

    也可以把令牌写在命令里（把 `sk-xxx` 换成你的令牌）：

    ```bash
    curl -fsSL https://vibecli.cn | sh -s -- --key sk-xxx && exec "$SHELL" -l
    ```
  </Tab>

  <Tab value="Windows">
    在 PowerShell 里运行，运行后按提示粘贴令牌：

    ```powershell
    irm https://vibecli.cn | iex
    ```

    也可以把令牌写在命令里（把 `sk-xxx` 换成你的令牌）：

    ```powershell
    & ([scriptblock]::Create((irm https://vibecli.cn))) --key sk-xxx
    ```

    <Accordions>
      <Accordion title="用的是命令提示符（cmd）">
        ```bat
        powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://vibecli.cn | iex"
        ```

        ```bat
        powershell -NoProfile -ExecutionPolicy Bypass -Command "& ([scriptblock]::Create((irm https://vibecli.cn))) --key sk-xxx"
        ```

        安装完成后新开一个窗口。
      </Accordion>
    </Accordions>
  </Tab>
</Tabs>

<ThemeImage light="/img/coding-tools/install-flow.svg" dark="/img/coding-tools/install-flow-dark.svg" alt="一条命令：粘贴命令并输入令牌 → 准备 Node.js 和 Git → 安装 VibeCLI → 安装还没有的编码工具并写好配置" />

命令运行完，编码工具就已安装并配置好，在终端输入 `claude`、`codex`、`grok` 或 `agy` 即可使用，不需要再做下面的「手动安装」。遇到问题见[常见问题](https://docs.vibeapi.cn/zh/docs/coding-tools/faq#一键安装)。

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/coding-tools/how-it-works" title="工作原理与设计" description="一次 setup 做了什么，为什么只合并不覆盖，令牌怎么保存和发送，模型菜单从哪来。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/coding-tools/tools" title="各工具一览" description="Claude Code、Claude Desktop、Codex、Grok Build、Antigravity 各一页：写了什么、怎么验证、为什么这样设计。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/coding-tools/commands" title="命令参考" description="setup、config、base、doctor、upgrade 等命令与参数的完整说明。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/coding-tools/config" title="配置、备份与安全" description="令牌存在哪，备份与还原，profile，自动更新与模型同步。" />

  <Card href="https://docs.vibeapi.cn/zh/docs/coding-tools/faq" title="常见问题" description="配置后不生效、证书报错、Codex 401、旧会话不见了……" />
</Cards>

## 手动安装

用过页首命令的，可以跳过这一节。

<Accordions>
  <Accordion title="只安装某一个编码工具">
    从国内镜像下载，程序和官方安装的相同；再运行一次即可升级。

    <Tabs items={['macOS / Linux', 'Windows']}>
      <Tab value="macOS / Linux">
        Node.js：

        ```bash
        curl -fsSL https://vibecli.cn/node.sh | sh && exec "$SHELL" -l
        ```

        Git：

        ```bash
        curl -fsSL https://vibecli.cn/git.sh | sh && exec "$SHELL" -l
        ```

        Claude Code：

        ```bash
        curl -fsSL https://vibecli.cn/claude-code.sh | sh && exec "$SHELL" -l
        ```

        Codex：

        ```bash
        curl -fsSL https://vibecli.cn/codex.sh | sh && exec "$SHELL" -l
        ```

        Grok Build：

        ```bash
        curl -fsSL https://vibecli.cn/grok.sh | sh && exec "$SHELL" -l
        ```

        Antigravity CLI（agy）：

        ```bash
        curl -fsSL https://vibecli.cn/agy.sh | sh && exec "$SHELL" -l
        ```
      </Tab>

      <Tab value="Windows">
        在 PowerShell 里运行：

        Node.js：

        ```powershell
        irm https://vibecli.cn/node.ps1 | iex
        ```

        Git：

        ```powershell
        irm https://vibecli.cn/git.ps1 | iex
        ```

        Claude Code：

        ```powershell
        irm https://vibecli.cn/claude-code.ps1 | iex
        ```

        Codex：

        ```powershell
        irm https://vibecli.cn/codex.ps1 | iex
        ```

        Grok Build：

        ```powershell
        irm https://vibecli.cn/grok.ps1 | iex
        ```

        Antigravity CLI（agy）：

        ```powershell
        irm https://vibecli.cn/agy.ps1 | iex
        ```

        <Accordions>
          <Accordion title="用的是命令提示符（cmd）">
            下面依次是 Node.js、Git、Claude Code、Codex、Grok Build、Antigravity CLI，安装完成后新开一个窗口：

            ```bat
            powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://vibecli.cn/node.ps1 | iex"
            ```

            ```bat
            powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://vibecli.cn/git.ps1 | iex"
            ```

            ```bat
            powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://vibecli.cn/claude-code.ps1 | iex"
            ```

            ```bat
            powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://vibecli.cn/codex.ps1 | iex"
            ```

            ```bat
            powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://vibecli.cn/grok.ps1 | iex"
            ```

            ```bat
            powershell -NoProfile -ExecutionPolicy Bypass -Command "irm https://vibecli.cn/agy.ps1 | iex"
            ```
          </Accordion>
        </Accordions>
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="已有 Node.js 20 及以上：手动安装 VibeCLI 并配置令牌">
    把 `sk-xxx` 换成你的令牌：

    ```bash
    npm install -g @vibeapi/cli --registry=https://registry.npmmirror.com
    vibecli setup --key sk-xxx
    ```

    `setup` 按令牌能用的模型配置对应的工具：Claude 配置 Claude Code 与 Claude Desktop，GPT 配置 Codex，Grok 配置 Grok Build，Gemini 配置 Antigravity CLI。在终端里运行时，它会先列出要修改的文件，你确认后才写入。还没有安装的命令行工具，它会问你是否安装，安装好再写配置；选择不安装就不写。Claude Desktop 例外：在 macOS 和 Windows 上没安装也会先写好配置。

    不想全局安装 VibeCLI，也可以直接运行：

    ```bash
    npx @vibeapi/cli@latest setup --key sk-xxx
    ```

    不同工具用不同的令牌：

    ```bash
    vibecli setup --claudekey sk-a --codexkey sk-b --agykey sk-g
    ```

    在菜单里选择工具和模型：

    ```bash
    vibecli init
    ```
  </Accordion>
</Accordions>

## 常用命令

| 命令                                | 作用                     |
| --------------------------------- | ---------------------- |
| `vibecli status`                  | 查看当前配置                 |
| `vibecli doctor`                  | 检查网络、令牌、版本、配置          |
| `vibecli upgrade`                 | 升级编码工具，官方渠道无法连接时改用国内镜像 |
| `vibecli config <工具>`             | 单独配置某个工具               |
| `vibecli config <工具> restore`     | 回到上一次修改前               |
| `vibecli config <工具> clear-model` | 改回工具自带的默认模型            |
| `vibecli config <工具> --force`     | 整份重写为推荐配置              |

`<工具>` 可以是 `claude-code`、`codex`、`grok`、`agy`、`claude-desktop`。完整命令见[命令参考](https://docs.vibeapi.cn/zh/docs/coding-tools/commands)。

## 主站无法连接

校园网、酒店网络有时会出现证书报错，或者请求一直超时。运行下面的命令，VibeCLI 会按顺序测试接入地址，换到第一个能用的：

<ThemeImage light="/img/coding-tools/base-auto.svg" dark="/img/coding-tools/base-auto-dark.svg" alt="主站无法连接 → 依次测试接入地址，取第一个能用的 → 已配置的工具一起换过去，令牌不用改" />

```bash
vibecli base auto
```

查看所有接入地址：

```bash
vibecli base
```

网络恢复后回到主站：

```bash
vibecli base default
```


# 长会话省额度

Claude Code 每发一次请求，都会把整段会话一起发给模型：你说的话、它的回复、每一次工具调用和输出。

会话越长，每一步的输入就越多。

提示缓存让重复的那部分按低价计费，但缓存会过期。过期后的第一条消息，整段会话要按写入价重新算一遍。

## 缓存怎么计费

以 `claude-opus-5` 为例，按[模型价格](https://www.vibeapi.cn/pricing)里的输入单价，一次请求的输入分三种状态计费：

| 状态          | 什么时候出现          | 按输入单价的倍数 |
| ----------- | --------------- | -------- |
| 缓存命中        | 和上一步前缀相同，缓存还没过期 | 0.1      |
| 缓存写入（5 分钟档） | 第一次发送，或缓存已经过期   | 1.25     |
| 缓存写入（1 小时档） | 同上，开了 1 小时缓存时   | 2        |

**用令牌接入时，Claude Code 的缓存默认只保留 5 分钟。** 通过 VibeAPI 使用就是这种情况；订阅账号是 1 小时。

也就是说，离开 5 分钟以上再回来，下一条消息会把整段会话重新写入一遍。

以一个 30 万 token 的会话为例：

| 回来时     | 下一步的输入相当于                     |
| ------- | ----------------------------- |
| 5 分钟内   | 3 万 token 的输入价                |
| 超过 5 分钟 | 37.5 万 token 的输入价，是前者的 12.5 倍 |

<Callout type="warn" title="auto 分组的令牌没有提示缓存">
  Claude 系模型只有在「Claude 官方满血版」分组上才有提示缓存。`auto` 分组的 `usage` 里不返回缓存字段，见 [Messages · 分组差异](https://docs.vibeapi.cn/zh/docs/messages#分组差异)。

  在 `auto` 上，长会话的每一步都按全价计算整段上下文，下面的做法对你更重要。
</Callout>

## 第 1 步：看清现在的会话

在 Claude Code 里运行两个命令：

* **`/context`**：当前上下文占了多少 token，哪些部分占得多。
* **`/usage`**：本次会话的用量。Session 一栏里有一行 `Prompt cache (main)`，需要 Claude Code v2.1.251 及以上。

`Prompt cache (main)` 这一行会告诉你：

* 命中率：多少输入是从缓存读的
* 缓存失效（miss）了几次，最近一次重写了多少 token
* 缓存现在是否还有效（warm / cold）

示例：

<div className="code-wrap">
  ```text
  Prompt cache (main):   14 requests · 91% of input tokens from cache · 2 misses (last 6m 10s ago, 310.2k tokens re-cached) · warm (5m TTL, last activity 40s ago)
  ```
</div>

在[控制台 · 使用日志](https://www.vibeapi.cn/console/log)里，每条请求也能看到缓存读、缓存写的 token 数。

缓存写得多、读得少，说明缓存经常失效。

## 第 2 步：按顺序调整

### 换一件事，就开新会话

一件事做完，下一件和它关系不大时，运行 `/clear` 开始新会话。

旧会话不会删除，想回去用 `/resume`。

为什么要清？旧会话里留着上一件事的工具输出。这些内容对新任务没有用，却会在之后的每一步里跟着发出去。

### 会话很长又放了一阵，开新会话接着做

满足这两条时，不要回原会话接着发：

* 会话已经很长，比如 `/context` 显示超过 20 万 token
* 离开的时间超过了缓存有效期

开一个新会话，在**同一个项目目录**里，把下面这段话发给它：

<div className="code-wrap">
  ```text
  接着做这个项目上一个会话没做完的事：
  1. 在 ~/.claude/projects 下找到这个目录对应的文件夹，按修改时间找到上一个会话的记录（不是你自己这个）。
  2. 只读其中用户和助手的文字，不读工具调用和工具输出。
  3. 用 git status、git log 和项目里的文件核对现在的状态。
  4. 然后接着做。
  ```
</div>

手上有旧会话 ID 的，把「上一个会话」换成这个 ID。

这样做为什么省？

* 会话记录里大部分是工具调用和输出，人和助手说的话只占一小部分。
* 只读文字，新会话花几万 token 就能补上背景，比把几十万 token 的旧会话整段重写便宜得多。
* 旧的工具输出是当时的快照。现在的状态以 `git status` 和文件为准，反而更可靠。

<Accordions>
  <Accordion title="想自己看旧会话说了什么">
    Claude Code 的会话记录在：

    ```text
    ~/.claude/projects/<项目目录>/<会话 ID>.jsonl
    ```

    `<项目目录>` 是把工作目录路径里的非字母数字字符换成 `-`，比如 `/Users/me/app` 对应 `-Users-me-app`。

    下面这条命令只取人和助手的文字，运行前把 `会话ID.jsonl` 换成实际的文件路径：

    ```bash
    jq -r 'select((.type=="user" or .type=="assistant") and (.isSidechain|not))
      | .type as $t | .message.content
      | if type=="string" then "\($t): \(.)"
        else (.[] | select(.type=="text") | "\($t): \(.text)") end' 会话ID.jsonl \
      | grep -v '^user: <'
    ```

    记录用的是 Claude Code 的内部格式，可能随版本变化。命令不再有效时，让助手自己去读，它会按当时的格式处理。

    只想给人看，用 `/export` 导出成纯文本。
  </Accordion>

  <Accordion title="Codex 也一样">
    Codex 的会话记录在：

    ```text
    ~/.codex/sessions/<年>/<月>/<日>/rollout-*.jsonl
    ```

    把上面那段话里的路径换成这个目录即可。

    人和助手的文字在 `type` 为 `response_item`、`payload.type` 为 `message` 的记录里。
  </Accordion>
</Accordions>

### 经常离开半小时左右再回来，改成 1 小时缓存

在 `~/.claude/settings.json` 里加一行，需要 Claude Code v2.1.242 及以上：

```json
{
  "promptCacheTtl": "1h"
}
```

怎么选：

* **改成 1 小时**：写入单价是 5 分钟档的 1.6 倍（2 对 1.25），适合经常停下来想一想、看一眼再回来的用法。
* **保持默认**：一次做完、不中途离开的，5 分钟档更省。

开启 1 小时缓存后还要注意一点：终端里的会话超过 20 万 token、闲置约 54 分钟时，Claude Code 会趁缓存没过期自动压缩一次。回来时会看到：

```text
Compacted while idle, before the prompt cache expired
```

打算按上一节的做法换新会话、不需要摘要的，在同一个文件里关掉它：

```json
{
  "promptCacheTtl": "1h",
  "idleCompaction": false
}
```

### 不要用 `/compact` 给长会话续命

`/compact` 会先把整段会话读一遍再写摘要：

* 压缩一个大会话，本身就是一次大请求。
* 缓存已经过期时，这一遍还要按写入价算。
* 摘要保留哪些内容，由不得你决定。

想保留进度，用上面「开新会话接着做」的做法；不需要保留，直接 `/clear`。

## 新会话靠什么接得上

新会话能顺利接手，靠的是旧会话留在项目里的内容：

* **提交说明写清改了什么、为什么。** 新会话第一件事就是看 `git log`。
* **定下来的约定写进 `CLAUDE.md`。** Codex 是 `AGENTS.md`。新会话启动时会自动读这个文件，不要只留在聊天里。
* **做到一半的状态写进文件**，比如一份待办清单。

这几样都在，换会话几乎没有损失。

## 确认省下来了

调整一两天后再看一次：

1. `/usage` 里 `Prompt cache (main)` 的命中率更高，misses 更少。
2. 控制台使用日志里，缓存写的 token 数占比下降。
3. 同样的工作量，控制台的消耗曲线更平，不再有回到旧会话时的尖峰。


# 各工具一览

| 工具                                                     | 命令里的名字           | `setup --key` 什么时候配置                     | 专属令牌选项         | 最低版本     | 修改后怎么生效          |
| ------------------------------------------------------ | ---------------- | ---------------------------------------- | -------------- | -------- | ---------------- |
| [Claude Code](https://docs.vibeapi.cn/zh/docs/coding-tools/claude-code)       | `claude-code`    | 令牌能用 Claude 模型                           | `--claudekey`  | 2.1.291  | 重开会话；清了环境变量时新开终端 |
| [Claude Desktop](https://docs.vibeapi.cn/zh/docs/coding-tools/claude-desktop) | `claude-desktop` | 令牌能用 Claude 模型（macOS / Windows 上没安装也先写好） | `--desktopkey` | 2.2553.0 | 完全退出再打开          |
| [Codex](https://docs.vibeapi.cn/zh/docs/coding-tools/codex)（命令行和桌面版）          | `codex`          | 令牌能用 GPT 模型                              | `--codexkey`   | 0.122.0  | 完全退出再打开          |
| [Grok Build](https://docs.vibeapi.cn/zh/docs/coding-tools/grok-build)         | `grok`           | 令牌能用 Grok 模型                             | `--grokkey`    | —        | 重新运行 `grok`      |
| [Antigravity CLI](https://docs.vibeapi.cn/zh/docs/coding-tools/antigravity)   | `agy`            | 令牌能用 Gemini 模型                           | `--agykey`     | 1.3.5    | 立即生效（思考档位要新开终端）  |

命令行工具还没有安装时，`setup` 会先问你是否安装，安装好才写配置。

## 各工具的共同规则

* **只改 VibeAPI 相关的部分。** 写入令牌、接入地址和模型；你自己的 hooks、MCP、插件、权限、主题等原样保留。
* **修改前先备份。** 每个配置文件旁边保留最近 10 份快照，`vibecli config <工具> restore` 回到上一次修改前。
* **模型菜单只列令牌能用的模型。** 按这个令牌的 `/v1/models` 生成。auto 分组的令牌看到的模型比官方分组少，这是正常的。网关上新的模型最多一小时后自动出现在菜单里。
* **版本过旧时提示。** 配置完成后检查工具版本，低于最低版本时提示运行 `vibecli upgrade`。
* **可以随时移除。** 运行 `vibecli config <工具> remove`，或在 `vibecli config <工具>` 的菜单里选「移除」，只删除 VibeAPI 写入的部分。卸载 VibeCLI 本身不影响已经配置好的工具。

背后的理由见[工作原理与设计](https://docs.vibeapi.cn/zh/docs/coding-tools/how-it-works)。


# 命令参考

{/* 由 scripts/sync-vibecli-commands.py 从 VibeCLI 仓库的 docs/commands.zh_CN.md 同步，请勿手改 */}

和终端里的 `vibecli --help`、`vibecli <命令> --help` 内容一致。

VibeCLI：在 Claude Code、Codex、Grok Build 等编码工具里统一配置 VibeAPI 的令牌和模型。

不带命令运行 vibecli 会打开主菜单。

<a id="global-options" />

## 全局选项

全局选项可以与任何命令一起使用。

| 选项                  | 说明                                                    |
| ------------------- | ----------------------------------------------------- |
| `-v, --version`     | 显示版本号                                                 |
| `--base <url>`      | 接入地址（setup、init、auth、config、enter 和主菜单会保存，其他命令只在本次生效） |
| `--non-interactive` | 不提出任何问题，需要确认的操作直接执行（用于脚本、CI）                          |
| `--json`            | 输出 JSON（仅限支持的命令）                                      |
| `-y, --yes`         | 需要确认时一律回答「是」（--non-interactive、--json 也是这样）           |
| `--dry-run`         | 只显示会修改什么，不写入（不支持预演的命令会直接拒绝）                           |
| `--no-color`        | 不使用颜色                                                 |
| `-h, --help`        | 显示帮助                                                  |

<a id="commands" />

## 命令

### 配置

| 命令                                  | 说明                         |
| ----------------------------------- | -------------------------- |
| [`vibecli setup`](#vibecli-setup)   | 一条命令完成工具配置（按令牌能用的模型自动选择工具） |
| [`vibecli init`](#vibecli-init)     | 首次使用的配置向导                  |
| [`vibecli auth`](#vibecli-auth)     | 保存或删除令牌                    |
| [`vibecli config`](#vibecli-config) | 按工具配置；管理 Profile、模型预设和备份   |
| [`vibecli base`](#vibecli-base)     | 查看、测速并切换接入地址               |

### 诊断

| 命令                                  | 说明            |
| ----------------------------------- | ------------- |
| [`vibecli status`](#vibecli-status) | 查看当前配置        |
| [`vibecli doctor`](#vibecli-doctor) | 检查配置和网络问题     |
| [`vibecli bench`](#vibecli-bench)   | 测试接入地址的延迟     |
| [`vibecli logs`](#vibecli-logs)     | 查看 VibeCLI 日志 |

### 维护

| 命令                                          | 说明                                     |
| ------------------------------------------- | -------------------------------------- |
| [`vibecli list`](#vibecli-list)             | 列出 vibecli 能装的运行环境、命令行工具和桌面应用，以及装了哪个版本 |
| [`vibecli install`](#vibecli-install)       | 安装运行环境（Node.js、Git、uv）、命令行工具或桌面应用      |
| [`vibecli upgrade`](#vibecli-upgrade)       | 升级编码工具、桌面应用和运行环境（Node.js、Git、uv）       |
| [`vibecli refresh`](#vibecli-refresh)       | 立即更新各工具的模型菜单                           |
| [`vibecli update`](#vibecli-update)         | 检查 VibeCLI 是否有新版本                      |
| [`vibecli codex`](#vibecli-codex)           | Codex 辅助功能                             |
| [`vibecli sessions`](#vibecli-sessions)     | 查看本机的编码会话                              |
| [`vibecli lang`](#vibecli-lang)             | 切换界面语言                                 |
| [`vibecli completion`](#vibecli-completion) | 输出命令补全脚本                               |
| [`vibecli enter`](#vibecli-enter)           | 直接打开某个配置菜单                             |

## 示例

| 命令                           | 说明                |
| ---------------------------- | ----------------- |
| `vibecli`                    | 打开主菜单             |
| `vibecli setup --key sk-xxx` | 用一个令牌配置它能用的全部工具   |
| `vibecli doctor`             | 检查配置和网络问题         |
| `vibecli base auto`          | 主域名无法连接时，切换到可用的地址 |
| `vibecli config codex`       | 打开 Codex 的配置菜单    |

<a id="vibecli-setup" />

## `vibecli setup`

不进入向导，一条命令写好配置。

\--key 先用令牌获取模型列表，按能用的模型配置对应工具（见下表）。

不同分组的令牌用 --claudekey、--codexkey、--grokkey、--desktopkey、--agykey 分别提供。

再次运行即可更换令牌，其他配置保留。

**用法**

```text
vibecli setup [options]
```

**选项**

| 选项                             | 说明                                               |
| ------------------------------ | ------------------------------------------------ |
| `--key <key>`                  | 一个令牌，按它能用的模型自动配置工具                               |
| `--claudekey <key>`            | Claude Code 专属令牌                                 |
| `--codexkey <key>`             | Codex 专属令牌                                       |
| `--grokkey <key>`              | Grok Build 专属令牌                                  |
| `--desktopkey <key>`           | Claude Desktop 专属令牌                              |
| `--agykey <key>`               | Antigravity CLI 专属令牌（需要能使用 Gemini 模型）            |
| `--1m`                         | 为 Codex 开启 1M 上下文                                |
| `--no-1m`                      | 为 Codex 关闭 1M 上下文                                |
| `--claude-official <on\|off>`  | Claude Desktop 是否显示 Claude.ai 登录入口（默认 off）       |
| `--desktop-registry <on\|off>` | Windows 版 Claude Desktop：始终写入注册表策略（on）或自动判断（off） |
| `--force`                      | 先备份，再用推荐配置整份重写（用于修复改坏的配置）                        |
| `--install`                    | 未安装的工具直接从国内镜像安装，不再询问                             |
| `--no-install`                 | 未安装的工具只给出安装命令，不安装                                |
| `--all`                        | 配置令牌能用的全部工具（默认行为）                                |
| `-h, --help`                   | 显示帮助                                             |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**--key 能用的模型和自动配置的工具**

| 写法       | 说明                                                                 |
| -------- | ------------------------------------------------------------------ |
| `Claude` | Claude Code、Claude Desktop（macOS、Windows 上未安装也会提前写好；Linux 上已安装才配置） |
| `GPT`    | Codex                                                              |
| `Grok`   | Grok Build                                                         |
| `Gemini` | Antigravity CLI                                                    |

**何时使用**

拿到令牌后第一次配置，或更换令牌、修复改坏的配置时。

**前提**

* 一个 VibeAPI 令牌（在控制台的「令牌」页新建）
* 工具可以之后再安装：未安装的命令行工具会先写好配置，再询问是否从国内镜像安装（加 --install 直接安装）；Claude Desktop 在 macOS、Windows 上未安装也会提前写好配置，安装后打开即可使用；Linux 版只配置已安装的

**替代方式**

| 命令                      | 什么情况下改用它     |
| ----------------------- | ------------ |
| `vibecli init`          | 想一步步选择工具和模型  |
| `vibecli config <tool>` | 只修改一个工具      |
| `vibecli auth <key>`    | 只保存令牌，不写工具配置 |

**示例**

| 命令                                                             | 说明                          |
| -------------------------------------------------------------- | --------------------------- |
| `vibecli setup --key sk-xxx`                                   | 用一个令牌配置它能用的全部工具             |
| `vibecli setup --install --key sk-xxx`                         | 配置完成后一起安装未安装的工具（国内镜像）       |
| `vibecli setup --claudekey sk-a --codexkey sk-b --agykey sk-g` | Claude、GPT、Gemini 分组的令牌分别配置 |
| `vibecli setup --force --key sk-xxx`                           | 配置被改坏时整份重写（会先备份）            |
| `vibecli setup --base https://www.vibeapi.si --key sk-xxx`     | 在备用地址上配置                    |

**另见**: `vibecli setup --help` · [命令列表](#commands)

<a id="vibecli-init" />

## `vibecli init`

一步步引导你填写令牌、选择工具并写好配置。

直接运行 vibecli（不带命令）会打开主菜单。

**用法**

```text
vibecli init [options]
```

**选项**

| 选项           | 说明   |
| ------------ | ---- |
| `-h, --help` | 显示帮助 |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**何时使用**

第一次使用，想一步步回答问题完成配置时。

**前提**

* 一个 VibeAPI 令牌

**替代方式**

| 命令                          | 什么情况下改用它       |
| --------------------------- | -------------- |
| `vibecli setup --key <key>` | 不想回答问题，或在脚本里配置 |
| `vibecli`                   | 已经配置过，只想修改某一项  |

**示例**

| 命令                                           | 说明         |
| -------------------------------------------- | ---------- |
| `vibecli init`                               | 运行配置向导     |
| `vibecli init --base https://www.vibeapi.si` | 在备用地址上运行向导 |
| `vibecli`                                    | 打开主菜单      |

**另见**: `vibecli init --help` · [命令列表](#commands)

<a id="vibecli-auth" />

## `vibecli auth`

不带参数：提示你输入令牌。

带令牌：验证后保存到 \~/.vibecli/config.yaml。

**用法**

```text
vibecli auth [options] [command] [token]
```

**参数**

| 参数      | 说明     |
| ------- | ------ |
| `token` | 要保存的令牌 |

**选项**

| 选项           | 说明   |
| ------------ | ---- |
| `-h, --help` | 显示帮助 |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**命令**

| 命令                                            | 说明                                            |
| --------------------------------------------- | --------------------------------------------- |
| [`vibecli auth revoke`](#vibecli-auth-revoke) | 删除已保存的令牌                                      |
| [`vibecli auth reload`](#vibecli-auth-reload) | 把已保存的令牌重新写入 Claude Code（claude / claude-code） |

**何时使用**

只想保存、更换或删除令牌，不改动工具配置时。

**替代方式**

| 命令                          | 什么情况下改用它      |
| --------------------------- | ------------- |
| `vibecli setup --key <key>` | 保存令牌并同时写好工具配置 |

**示例**

| 命令                                      | 说明                  |
| --------------------------------------- | ------------------- |
| `vibecli auth`                          | 提示输入令牌              |
| `vibecli auth sk-xxx --non-interactive` | 直接保存一个令牌            |
| `vibecli auth revoke --yes`             | 删除已保存的令牌，不再询问       |
| `vibecli auth reload claude-code`       | 把令牌重新写入 Claude Code |

**另见**: `vibecli auth --help` · [命令列表](#commands)

<a id="vibecli-auth-revoke" />

## `vibecli auth revoke`

删除已保存的令牌

**用法**

```text
vibecli auth revoke [options]
```

**选项**

| 选项           | 说明   |
| ------------ | ---- |
| `-h, --help` | 显示帮助 |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**示例**

| 命令                          | 说明             |
| --------------------------- | -------------- |
| `vibecli auth revoke`       | 删除已保存的令牌（会先确认） |
| `vibecli auth revoke --yes` | 删除已保存的令牌，不再询问  |

**另见**: `vibecli auth revoke --help` · [`vibecli auth`](#vibecli-auth) · [命令列表](#commands)

<a id="vibecli-auth-reload" />

## `vibecli auth reload`

把已保存的令牌重新写入 Claude Code（claude / claude-code）

**用法**

```text
vibecli auth reload [options] <tool>
```

**选项**

| 选项           | 说明   |
| ------------ | ---- |
| `-h, --help` | 显示帮助 |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**示例**

| 命令                                       | 说明                  |
| ---------------------------------------- | ------------------- |
| `vibecli auth reload claude-code`        | 把令牌重新写入 Claude Code |
| `vibecli auth reload claude-code --json` | 同上，输出 JSON          |

**另见**: `vibecli auth reload --help` · [`vibecli auth`](#vibecli-auth) · [命令列表](#commands)

<a id="vibecli-config" />

## `vibecli config`

不带参数：选择一个工具，打开它的配置菜单。

子命令和工具名见下表。

**用法**

```text
vibecli config [options] [args...]
```

**参数**

| 参数     | 说明          |
| ------ | ----------- |
| `args` | 子命令和参数（见下表） |

**选项**

| 选项            | 说明                   |
| ------------- | -------------------- |
| `-f, --force` | 先备份，再用推荐配置整份重写该工具的配置 |
| `-h, --help`  | 显示帮助                 |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**子命令**

| 写法                                     | 说明                                  |
| -------------------------------------- | ----------------------------------- |
| `<tool>`                               | 打开该工具的配置菜单                          |
| `<tool> --force`                       | 先备份，再用推荐配置整份重写                      |
| `<tool> --non-interactive`             | 不显示菜单，用已保存的令牌直接写入配置                 |
| `<tool> remove`                        | 移除 VibeAPI 写入的服务商、令牌和模型设置，其他设置保留    |
| `<tool> restore`                       | 还原该工具最近一次的备份                        |
| `<tool> backups`                       | 列出该工具的备份                            |
| `<tool> clear-model`                   | 只清除固定的模型设置，保留令牌、hooks、MCP 和插件       |
| `tool-model list`                      | 列出各工具单独设置的模型                        |
| `tool-model set <tool> [slot] <model>` | 为某个工具单独设置模型（slot 默认为 opus，即主模型）     |
| `tool-model clear <tool>`              | 清除某个工具单独设置的模型                       |
| `profile list`                         | 列出 Profile（每个 Profile 包含一套令牌、地址和模型） |
| `profile create <name>`                | 新建 Profile                          |
| `profile use <name>`                   | 切换到某个 Profile                       |
| `profile delete <name>`                | 删除 Profile                          |
| `preset list`                          | 列出模型预设                              |
| `preset save <name>`                   | 把当前的模型组合保存为预设                       |
| `preset use <name>`                    | 使用某个预设                              |
| `preset delete <name>`                 | 删除预设                                |
| `backup list`                          | 列出 VibeCLI 配置的备份                    |
| `backup create [label]`                | 备份 VibeCLI 配置（可以加标签）                |
| `backup restore <name>`                | 从备份还原 VibeCLI 配置                    |

**工具名**

| 写法               | 说明              |
| ---------------- | --------------- |
| `claude-code`    | Claude Code     |
| `codex`          | Codex           |
| `grok`           | Grok Build      |
| `claude-desktop` | Claude Desktop  |
| `agy`            | Antigravity CLI |

**何时使用**

调整单个工具（更换模型、重写或还原配置），或管理 Profile、模型预设和备份时。

**前提**

* 写入工具配置前，需要先保存令牌：vibecli auth \<你的令牌> 或 vibecli setup --key \<你的令牌>

**替代方式**

| 命令                                  | 什么情况下改用它    |
| ----------------------------------- | ----------- |
| `vibecli setup --force --key <key>` | 一次重写全部工具的配置 |
| `vibecli status`                    | 只查看当前配置，不修改 |

**示例**

| 命令                                                | 说明                                      |
| ------------------------------------------------- | --------------------------------------- |
| `vibecli config codex`                            | 打开 Codex 的配置菜单                          |
| `vibecli config claude-code --force`              | 把 Claude Code 的配置整份重写                   |
| `vibecli config tool-model set codex gpt-6-astra` | Codex 单独使用某个模型                          |
| `vibecli config profile create work`              | 新建一个名为 work 的 Profile                   |
| `vibecli config codex remove`                     | 不再让 Codex 使用 VibeAPI（例如改回 ChatGPT 订阅登录） |

**另见**: `vibecli config --help` · [命令列表](#commands)

<a id="vibecli-base" />

## `vibecli base`

主域名无法连接或证书报错时，切换到另一个接入地址。

切换后，用 VibeCLI 保存的令牌配置过的工具会一起改到新地址。

**用法**

```text
vibecli base [options] [target]
```

**参数**

| 参数       | 说明                      |
| -------- | ----------------------- |
| `target` | 切换到哪个地址（见下表），不填则列出地址并测试 |

**选项**

| 选项           | 说明   |
| ------------ | ---- |
| `-h, --help` | 显示帮助 |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**目标写法**

| 写法        | 说明                                                          |
| --------- | ----------------------------------------------------------- |
| `（不填）`    | 列出全部地址并逐个测试，标出当前地址                                          |
| `<序号>`    | 切换到列表里的第 n 个地址                                              |
| `<地址>`    | 切换到指定地址，例如：[https://www.vibeapi.si](https://www.vibeapi.si) |
| `auto`    | 按列表顺序切换到第一个可用的地址（不是最快的，优先连接主站）                              |
| `default` | 回到主站 [https://www.vibeapi.cn](https://www.vibeapi.cn)       |

**何时使用**

工具报告无法连接、超时或证书错误时。

**前提**

* 保存过令牌时，内置地址和当前地址会用它确认地址确实可用；其他地址，或没有保存令牌时，只测试网关是否在线

**替代方式**

| 命令               | 什么情况下改用它    |
| ---------------- | ----------- |
| `vibecli doctor` | 不确定是不是地址的问题 |
| `vibecli bench`  | 只测试延迟，不切换   |

**示例**

| 命令                                    | 说明             |
| ------------------------------------- | -------------- |
| `vibecli base`                        | 列出地址并测试        |
| `vibecli base auto`                   | 自动切换到第一个可用的地址  |
| `vibecli base 2`                      | 切换到列表里的第 2 个地址 |
| `vibecli base https://www.vibeapi.si` | 切换到指定地址        |
| `vibecli base default`                | 回到主站           |

**另见**: `vibecli base --help` · [命令列表](#commands)

<a id="vibecli-status" />

## `vibecli status`

显示当前的令牌和它的余额、接入地址、语言、模型，以及各工具是否已配置。

**用法**

```text
vibecli status [options]
```

**选项**

| 选项           | 说明   |
| ------------ | ---- |
| `-h, --help` | 显示帮助 |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**何时使用**

想确认现在使用的是哪个令牌、地址和模型时。

**替代方式**

| 命令               | 什么情况下改用它           |
| ---------------- | ------------------ |
| `vibecli doctor` | 要检查配置能否正常使用，而不只是查看 |

**示例**

| 命令                      | 说明            |
| ----------------------- | ------------- |
| `vibecli status`        | 查看当前配置        |
| `vibecli status --json` | 输出 JSON，供脚本读取 |

**另见**: `vibecli status --help` · [命令列表](#commands)

<a id="vibecli-doctor" />

## `vibecli doctor`

检查令牌、余额、网络、代理、已安装的工具和它们的配置，并给出处理办法。

**用法**

```text
vibecli doctor [options]
```

**选项**

| 选项           | 说明                                                    |
| ------------ | ----------------------------------------------------- |
| `--deep`     | 已安装 Claude Code 时，再用它实际发送一条请求（消耗少量额度）                 |
| `--report`   | 检查后上传诊断信息（检查结果、工具版本、设置和最近的运行记录，不含令牌和对话内容），得到一个诊断码发给客服 |
| `-h, --help` | 显示帮助                                                  |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**何时使用**

工具报错（401、无法连接、找不到模型）又不清楚原因时。

**替代方式**

| 命令                  | 什么情况下改用它      |
| ------------------- | ------------- |
| `vibecli base auto` | 已经确定是接入地址无法连接 |
| `vibecli logs tail` | 需要把出错细节发给客服   |

**示例**

| 命令                        | 说明                             |
| ------------------------- | ------------------------------ |
| `vibecli doctor`          | 运行一次检查                         |
| `vibecli doctor --deep`   | 已安装 Claude Code 时，连同它的实际请求一起检查 |
| `vibecli doctor --report` | 上传诊断信息，得到诊断码发给客服               |

**另见**: `vibecli doctor --help` · [命令列表](#commands)

<a id="vibecli-bench" />

## `vibecli bench`

用已保存的令牌向当前接入地址请求几次模型列表，统计耗时；加上 --stream 会再发送一条真实的流式请求，查看首字时间和流能否正常结束。

**用法**

```text
vibecli bench [options]
```

**选项**

| 选项                | 说明                                  |
| ----------------- | ----------------------------------- |
| `--samples <n>`   | 请求次数（1–50）（默认 5）                    |
| `--stream`        | 再发送一条真实的流式请求，查看首字时间和流能否正常结束（消耗极少额度） |
| `--model <model>` | 流式请求使用的模型（默认按令牌能用的模型自动选择）           |
| `-h, --help`      | 显示帮助                                |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**何时使用**

感觉变慢，或想查看当前地址的延迟时。

**前提**

* 已保存令牌（vibecli auth \<你的令牌>）

**替代方式**

| 命令             | 什么情况下改用它       |
| -------------- | -------------- |
| `vibecli base` | 一次测试全部地址，并可以切换 |

**示例**

| 命令                                           | 说明             |
| -------------------------------------------- | -------------- |
| `vibecli bench`                              | 请求 5 次         |
| `vibecli bench --samples 3`                  | 只请求 3 次        |
| `vibecli bench --stream`                     | 测试延迟，再测试一次流式请求 |
| `vibecli bench --stream --model gpt-6-astra` | 用指定模型测试流式请求    |
| `vibecli bench --json`                       | 输出 JSON        |

**另见**: `vibecli bench --help` · [命令列表](#commands)

<a id="vibecli-logs" />

## `vibecli logs`

日志按天保存在 \~/.vibecli 目录。出现问题时，可以把 tail 的输出发给客服。

**用法**

```text
vibecli logs [options] [action] [file]
```

**参数**

| 参数       | 说明                        |
| -------- | ------------------------- |
| `action` | list、tail 或 path（默认 list） |
| `file`   | tail 时要查看的日志文件            |

**选项**

| 选项           | 说明   |
| ------------ | ---- |
| `-h, --help` | 显示帮助 |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**操作**

| 写法            | 说明               |
| ------------- | ---------------- |
| `list`        | 列出日志文件           |
| `tail [file]` | 显示最新日志的末尾（或指定文件） |
| `path`        | 显示日志目录           |

**何时使用**

命令出错需要查看细节，或客服需要日志时。

**替代方式**

| 命令               | 什么情况下改用它  |
| ---------------- | --------- |
| `vibecli doctor` | 先自行检查常见问题 |

**示例**

| 命令                  | 说明     |
| ------------------- | ------ |
| `vibecli logs`      | 列出日志文件 |
| `vibecli logs tail` | 查看最新日志 |
| `vibecli logs path` | 显示日志目录 |

**另见**: `vibecli logs --help` · [命令列表](#commands)

<a id="vibecli-list" />

## `vibecli list`

列出 Node.js、Git、uv、Claude Code、Codex、Grok Build、Antigravity CLI、Claude Desktop、ChatGPT：装了没有、当前版本、最新版本、用什么方式装的、从哪下载。最新版本缓存一小时，加 --refresh 立即重新查。

**用法**

```text
vibecli list [options]
```

**选项**

| 选项           | 说明           |
| ------------ | ------------ |
| `--refresh`  | 不用缓存，重新查最新版本 |
| `-h, --help` | 显示帮助         |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**何时使用**

想知道这台电脑上装了哪些工具、哪些可以升级时。

**替代方式**

| 命令               | 什么情况下改用它    |
| ---------------- | ----------- |
| `vibecli doctor` | 检查令牌和各工具的配置 |

**示例**

| 命令                       | 说明           |
| ------------------------ | ------------ |
| `vibecli list`           | 列出全部组件       |
| `vibecli list --refresh` | 重新查最新版本      |
| `vibecli list --json`    | 输出 JSON，给脚本用 |

**另见**: `vibecli list --help` · [命令列表](#commands)

<a id="vibecli-install" />

## `vibecli install`

从国内镜像安装缺少的组件，下载后核对校验值（桌面应用还核对厂商签名）。已经装过的不覆盖：只显示当前版本，落后时给出升级命令；加 --force 重新安装。

Node.js、Git、uv 用 VibeAPI 的安装脚本装进当前用户目录，不需要管理员权限；不要加 sudo。可以写多个组件，有依赖的先装依赖。

**用法**

```text
vibecli install [options] <components...>
```

**参数**

| 参数           | 说明                                                                   |
| ------------ | -------------------------------------------------------------------- |
| `components` | node、git、uv、claude-code、codex、grok、agy、claude-desktop、chatgpt，可以填写多个 |

**选项**

| 选项           | 说明        |
| ------------ | --------- |
| `--force`    | 已经装过也重新安装 |
| `-h, --help` | 显示帮助      |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**何时使用**

要在这台电脑上补装某个工具时；别的应用的安装脚本也可以调用它（npx @vibeapi/api-helper install …）。

**前提**

* 这台电脑已有 Node.js（vibecli 本身要 Node）；还没有 Node 时先用一键安装脚本

**替代方式**

| 命令                           | 什么情况下改用它      |
| ---------------------------- | ------------- |
| `vibecli upgrade`            | 升级已经装好的组件     |
| `vibecli setup --key <你的令牌>` | 装好后写入令牌并配置各工具 |

**示例**

| 命令                                     | 说明                       |
| -------------------------------------- | ------------------------ |
| `vibecli install node uv`              | 安装 Node.js 和 uv          |
| `vibecli install claude-code codex`    | 安装 Claude Code 和 Codex   |
| `vibecli install chatgpt`              | 安装 ChatGPT 桌面版（内含 Codex） |
| `vibecli install uv --force`           | uv 已经装过也重新安装             |
| `vibecli install node uv --yes --json` | 在脚本里安装，输出 JSON           |

**另见**: `vibecli install --help` · [命令列表](#commands)

<a id="vibecli-upgrade" />

## `vibecli upgrade`

按每份工具当初的安装方式升级：原生安装用工具自带的更新，npm 安装从国内镜像（npmmirror）重新安装，Homebrew 安装用 brew upgrade；原生或 Homebrew 方式无法升级时，改用 VibeAPI 一键安装脚本（程序取自国内镜像）。指定了但还没有安装的工具，也用这个脚本安装。

Claude Desktop 和 ChatGPT（内含 Codex；macOS / Windows）比高速下载站上的版本旧时，从高速下载站下载官方安装包，核对校验值和厂商（Anthropic / OpenAI）的签名后安装；它们自带的自动更新照常开着，vibecli 只在没跟上时补上。应用正在运行时，在终端里问过才关掉它升级，带 --yes 或没有终端时只提示、不关。已是最新时加 --force 重新安装。ChatGPT 的 Mac 版只支持 Apple 芯片。

Node.js、Git、uv 只升级由 VibeAPI 安装脚本管理的那一份（fnm 装的 Node、\~/.local/bin 里的 uv、装在当前用户下的 Git for Windows）；用 Homebrew、nvm、系统包管理器等装的，给出对应的升级命令、不改动它，加 --force 另装一份由 vibecli 管理的。fnm 的 Node 升级后，原来全局安装的 npm 包会按原版本装到新版里。

不填名字则升级已安装的全部编码工具和桌面应用，并提示可以升级的运行环境。

升级 VibeCLI 本身请用 vibecli update。

**用法**

```text
vibecli upgrade [options] [tools...]
```

**参数**

| 参数      | 说明                                                                   |
| ------- | -------------------------------------------------------------------- |
| `tools` | claude-code、codex、grok、agy、claude-desktop、chatgpt、node、git、uv，可以填写多个 |

**选项**

| 选项           | 说明                                               |
| ------------ | ------------------------------------------------ |
| `--force`    | 桌面应用和运行环境已是最新也重新安装；运行环境由别的方式装的，另装一份由 vibecli 管理的 |
| `-h, --help` | 显示帮助                                             |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**何时使用**

vibecli doctor 提示版本过低，或工具自带的更新无法完成时。

**前提**

* 不填工具名时，只升级已经安装的工具

**替代方式**

| 命令               | 什么情况下改用它      |
| ---------------- | ------------- |
| `vibecli update` | 升级 VibeCLI 本身 |

**示例**

| 命令                                | 说明                               |
| --------------------------------- | -------------------------------- |
| `vibecli upgrade`                 | 升级已安装的全部工具                       |
| `vibecli upgrade codex agy`       | 升级 Codex 和 Antigravity CLI       |
| `vibecli upgrade claude-desktop`  | 安装 Claude Desktop，或升到高速下载站上的最新版  |
| `vibecli upgrade chatgpt --force` | ChatGPT 已是最新也重新安装一遍（应用损坏时）       |
| `vibecli upgrade node`            | 升级 Node.js（fnm 安装的；别的方式装的给出升级命令） |

**另见**: `vibecli upgrade --help` · [命令列表](#commands)

<a id="vibecli-refresh" />

## `vibecli refresh`

按网关当前的模型配置和令牌现在能用的模型，重写各工具的模型菜单，不必等待每小时一次的自动同步。

**用法**

```text
vibecli refresh [options]
```

**选项**

| 选项           | 说明   |
| ------------ | ---- |
| `-h, --help` | 显示帮助 |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**何时使用**

令牌换了分组、能用的模型有变化，或网关刚上架、下架模型时。

**替代方式**

| 命令                           | 什么情况下改用它     |
| ---------------------------- | ------------ |
| `vibecli setup --key <你的令牌>` | 要更换令牌或重新配置工具 |

**示例**

| 命令                                             | 说明                    |
| ---------------------------------------------- | --------------------- |
| `vibecli refresh`                              | 立即更新模型菜单              |
| `vibecli refresh --base https://hk.vibeapi.cn` | 按另一个接入地址的配置更新（只在本次生效） |

**另见**: `vibecli refresh --help` · [命令列表](#commands)

<a id="vibecli-update" />

## `vibecli update`

依次查询这些来源：高速下载站、npmjs、npmmirror、Yarn。有新版本时给出安装命令。

全局安装的 VibeCLI 每次启动时也会检查，有新版本时自动安装并重新运行当前命令。

**用法**

```text
vibecli update [options]
```

**选项**

| 选项           | 说明   |
| ------------ | ---- |
| `-h, --help` | 显示帮助 |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**何时使用**

想确认 VibeCLI 是否为最新版本时。

**替代方式**

| 命令                | 什么情况下改用它                 |
| ----------------- | ------------------------ |
| `vibecli upgrade` | 升级 Claude Code、Codex 等工具 |

**示例**

| 命令                      | 说明      |
| ----------------------- | ------- |
| `vibecli update`        | 检查新版本   |
| `vibecli update --json` | 输出 JSON |

**另见**: `vibecli update --help` · [命令列表](#commands)

<a id="vibecli-codex" />

## `vibecli codex`

Codex 相关的辅助命令。

**用法**

```text
vibecli codex [options] [command]
```

**选项**

| 选项           | 说明   |
| ------------ | ---- |
| `-h, --help` | 显示帮助 |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**命令**

| 命令                                                  | 说明                  |
| --------------------------------------------------- | ------------------- |
| [`vibecli codex sessions`](#vibecli-codex-sessions) | 让旧会话重新出现在 Codex 列表里 |

**何时使用**

Codex 出现 VibeCLI 能处理的问题时（目前是会话列表变空）。

**示例**

| 命令                                    | 说明               |
| ------------------------------------- | ---------------- |
| `vibecli codex sessions`              | 把全部会话改到当前服务商     |
| `vibecli codex sessions --undo <dir>` | 撤销上一次修改（目录见上次输出） |

**另见**: `vibecli codex --help` · [命令列表](#commands)

<a id="vibecli-codex-sessions" />

## `vibecli codex sessions`

Codex 按服务商筛选会话，更换登录方式或服务商后，旧会话会被隐藏。

这个命令把本地会话改到当前服务商；会先备份，可以用 --undo 撤销。

运行前请先退出 Codex。

**用法**

```text
vibecli codex sessions [options]
```

**选项**

| 选项                | 说明                          |
| ----------------- | --------------------------- |
| `--to <provider>` | 改到哪个服务商（默认为 Codex 当前使用的服务商） |
| `--undo <dir>`    | 按这个备份目录把会话改回去               |
| `-h, --help`      | 显示帮助                        |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**何时使用**

Codex 的历史会话列表变空或缺少会话时。

**前提**

* 先退出 Codex（运行时会拒绝修改）

**替代方式**

| 命令                                    | 什么情况下改用它 |
| ------------------------------------- | -------- |
| `vibecli codex sessions --undo <dir>` | 修改后想改回去  |

**示例**

| 命令                                    | 说明               |
| ------------------------------------- | ---------------- |
| `vibecli codex sessions`              | 把全部会话改到当前服务商     |
| `vibecli codex sessions --to custom`  | 把会话改到 custom 服务商 |
| `vibecli codex sessions --undo <dir>` | 撤销上一次修改（目录见上次输出） |

**另见**: `vibecli codex sessions --help` · [`vibecli codex`](#vibecli-codex) · [命令列表](#commands)

<a id="vibecli-sessions" />

## `vibecli sessions`

列出 Claude Code、Codex 和 Claude Desktop（Cowork、Code）保存在本机的会话，按最后更新时间排序。

可以查看会话内容、打印或直接运行继续对话的命令、导出为 Markdown。只读，不修改任何会话文件。

**用法**

```text
vibecli sessions [options] [command]
```

**选项**

| 选项           | 说明   |
| ------------ | ---- |
| `-h, --help` | 显示帮助 |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**命令**

| 命令                                                    | 说明              |
| ----------------------------------------------------- | --------------- |
| [`vibecli sessions list`](#vibecli-sessions-list)     | 列出会话（默认）        |
| [`vibecli sessions show`](#vibecli-sessions-show)     | 显示一个会话的信息和前几条消息 |
| [`vibecli sessions resume`](#vibecli-sessions-resume) | 打印或运行继续对话的命令    |
| [`vibecli sessions export`](#vibecli-sessions-export) | 把会话导出为 Markdown |

**何时使用**

想找回以前的对话、继续对话，或保存对话时。

**替代方式**

| 命令                       | 什么情况下改用它                    |
| ------------------------ | --------------------------- |
| `vibecli codex sessions` | Codex 列表里看不到旧会话时，把它们改到当前服务商 |

**示例**

| 命令                                                        | 说明                  |
| --------------------------------------------------------- | ------------------- |
| `vibecli sessions`                                        | 列出最近 20 个会话         |
| `vibecli sessions --tool codex --here`                    | 只查看当前目录的会话          |
| `vibecli sessions show 01a0f5fe`                          | 查看一个会话（ID 写前几位即可）   |
| `vibecli sessions resume 01a0f5fe --run`                  | 在会话原来的目录里继续对话       |
| `vibecli sessions export 01a0f5fe 7c2e9d41 -o ./sessions` | 把两个会话导出到 ./sessions |

**另见**: `vibecli sessions --help` · [命令列表](#commands)

<a id="vibecli-sessions-list" />

## `vibecli sessions list`

列出会话（默认）

**用法**

```text
vibecli sessions list [options]
```

**选项**

| 选项                    | 说明                                           |
| --------------------- | -------------------------------------------- |
| `--tool <tool>`       | 只查看这个工具的会话（claude-code、codex、claude-desktop） |
| `--dir <path>`        | 只查看在这个目录或其子目录中开始的会话                          |
| `--here`              | 只查看在当前目录或其子目录中开始的会话                          |
| `-n, --limit <count>` | 最多列出多少个（默认 20）                               |
| `--all`               | 全部列出                                         |
| `-h, --help`          | 显示帮助                                         |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**示例**

| 命令                                   | 说明            |
| ------------------------------------ | ------------- |
| `vibecli sessions list`              | 列出最近 20 个会话   |
| `vibecli sessions list --tool codex` | 只查看 Codex 的会话 |
| `vibecli sessions list --here --all` | 只查看当前目录的会话    |
| `vibecli sessions list --json`       | 输出 JSON，供脚本读取 |

**另见**: `vibecli sessions list --help` · [`vibecli sessions`](#vibecli-sessions) · [命令列表](#commands)

<a id="vibecli-sessions-show" />

## `vibecli sessions show`

显示一个会话的信息和前几条消息

**用法**

```text
vibecli sessions show [options] <id>
```

**选项**

| 选项                       | 说明            |
| ------------------------ | ------------- |
| `-m, --messages <count>` | 显示前几条消息（默认 6） |
| `-h, --help`             | 显示帮助          |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**示例**

| 命令                                     | 说明                |
| -------------------------------------- | ----------------- |
| `vibecli sessions show 01a0f5fe`       | 查看一个会话（ID 写前几位即可） |
| `vibecli sessions show 01a0f5fe -m 20` | 显示前 20 条消息        |

**另见**: `vibecli sessions show --help` · [`vibecli sessions`](#vibecli-sessions) · [命令列表](#commands)

<a id="vibecli-sessions-resume" />

## `vibecli sessions resume`

打印或运行继续对话的命令

**用法**

```text
vibecli sessions resume [options] <id>
```

**选项**

| 选项           | 说明                 |
| ------------ | ------------------ |
| `--run`      | 直接运行继续对话的命令（默认只打印） |
| `-h, --help` | 显示帮助               |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**示例**

| 命令                                       | 说明                |
| ---------------------------------------- | ----------------- |
| `vibecli sessions resume 01a0f5fe`       | 只打印继续对话的命令，自行复制运行 |
| `vibecli sessions resume 01a0f5fe --run` | 在会话原来的目录里继续对话     |

**另见**: `vibecli sessions resume --help` · [`vibecli sessions`](#vibecli-sessions) · [命令列表](#commands)

<a id="vibecli-sessions-export" />

## `vibecli sessions export`

把会话导出为 Markdown

**用法**

```text
vibecli sessions export [options] <ids...>
```

**选项**

| 选项                   | 说明                        |
| -------------------- | ------------------------- |
| `-o, --output <dir>` | 导出到这个目录（不存在时会新建，不覆盖已有文件）  |
| `--tools`            | 附上工具调用的参数和输出（各截取前 2000 字） |
| `-h, --help`         | 显示帮助                      |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**示例**

| 命令                                                        | 说明                  |
| --------------------------------------------------------- | ------------------- |
| `vibecli sessions export 01a0f5fe 7c2e9d41 -o ./sessions` | 把两个会话导出到 ./sessions |
| `vibecli sessions export 01a0f5fe -o ./sessions --tools`  | 导出时附上工具调用的参数和输出     |

**另见**: `vibecli sessions export --help` · [`vibecli sessions`](#vibecli-sessions) · [命令列表](#commands)

<a id="vibecli-lang" />

## `vibecli lang`

查看或设置 VibeCLI 的界面语言（zh\_CN、en\_US）。

**用法**

```text
vibecli lang [options] [command]
```

**选项**

| 选项           | 说明   |
| ------------ | ---- |
| `-h, --help` | 显示帮助 |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**命令**

| 命令                                        | 说明                   |
| ----------------------------------------- | -------------------- |
| [`vibecli lang show`](#vibecli-lang-show) | 显示当前语言               |
| [`vibecli lang set`](#vibecli-lang-set)   | 设置语言：zh\_CN 或 en\_US |

**何时使用**

界面语言不对时。

**替代方式**

| 命令                   | 什么情况下改用它 |
| -------------------- | -------- |
| `vibecli enter lang` | 用菜单选择语言  |

**示例**

| 命令                       | 说明     |
| ------------------------ | ------ |
| `vibecli lang show`      | 显示当前语言 |
| `vibecli lang set en_US` | 切换为英文  |
| `vibecli lang set zh_CN` | 切换为中文  |

**另见**: `vibecli lang --help` · [命令列表](#commands)

<a id="vibecli-lang-show" />

## `vibecli lang show`

显示当前语言

**用法**

```text
vibecli lang show [options]
```

**选项**

| 选项           | 说明   |
| ------------ | ---- |
| `-h, --help` | 显示帮助 |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**示例**

| 命令                         | 说明              |
| -------------------------- | --------------- |
| `vibecli lang show`        | 显示当前语言          |
| `vibecli lang show --json` | 输出 JSON，包括可选的语言 |

**另见**: `vibecli lang show --help` · [`vibecli lang`](#vibecli-lang) · [命令列表](#commands)

<a id="vibecli-lang-set" />

## `vibecli lang set`

设置语言：zh\_CN 或 en\_US

**用法**

```text
vibecli lang set [options] <locale>
```

**选项**

| 选项           | 说明   |
| ------------ | ---- |
| `-h, --help` | 显示帮助 |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**示例**

| 命令                       | 说明    |
| ------------------------ | ----- |
| `vibecli lang set en_US` | 切换为英文 |
| `vibecli lang set zh_CN` | 切换为中文 |

**另见**: `vibecli lang set --help` · [`vibecli lang`](#vibecli-lang) · [命令列表](#commands)

<a id="vibecli-completion" />

## `vibecli completion`

输出 bash、zsh、fish 的补全脚本。保存到文件后，在 shell 配置里 source 它（fish 放进补全目录即可）。

**用法**

```text
vibecli completion [options] <shell>
```

**参数**

| 参数      | 说明              |
| ------- | --------------- |
| `shell` | bash、zsh 或 fish |

**选项**

| 选项           | 说明   |
| ------------ | ---- |
| `-h, --help` | 显示帮助 |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**何时使用**

想用 Tab 键补全 VibeCLI 的命令时。

**前提**

* 使用 bash、zsh 或 fish

**示例**

| 命令                                                                  | 说明         |
| ------------------------------------------------------------------- | ---------- |
| `vibecli completion bash > ~/.vibecli-completion.bash`              | 生成 bash 补全 |
| `vibecli completion zsh > ~/.vibecli-completion.zsh`                | 生成 zsh 补全  |
| `vibecli completion fish > ~/.config/fish/completions/vibecli.fish` | 生成 fish 补全 |

**另见**: `vibecli completion --help` · [命令列表](#commands)

<a id="vibecli-enter" />

## `vibecli enter`

不经过主菜单，直接打开指定的配置菜单。

**用法**

```text
vibecli enter [options] [option]
```

**参数**

| 参数       | 说明          |
| -------- | ----------- |
| `option` | 要打开的菜单（见下表） |

**选项**

| 选项           | 说明   |
| ------------ | ---- |
| `-h, --help` | 显示帮助 |

另可使用[全局选项](#global-options)：`-v, --version` `--base <url>` `--non-interactive` `--json` `-y, --yes` `--dry-run` `--no-color`

**菜单**

| 写法       | 说明                                    |
| -------- | ------------------------------------- |
| `（不填）`   | 主菜单                                   |
| `lang`   | 语言设置                                  |
| `apikey` | 令牌设置                                  |
| `models` | 模型设置                                  |
| `<tool>` | 该工具的配置菜单（与 vibecli config \<tool> 相同） |

**何时使用**

知道要修改哪一项，想跳过主菜单时。

**替代方式**

| 命令                      | 什么情况下改用它    |
| ----------------------- | ----------- |
| `vibecli`               | 从主菜单开始选择    |
| `vibecli config <tool>` | 直接用命令配置某个工具 |

**示例**

| 命令                     | 说明             |
| ---------------------- | -------------- |
| `vibecli enter`        | 打开主菜单          |
| `vibecli enter models` | 打开模型设置         |
| `vibecli enter codex`  | 打开 Codex 的配置菜单 |

**另见**: `vibecli enter --help` · [命令列表](#commands)


# 鉴权体系说明（Auth）

## 说明

后台管理接口采用多级鉴权机制，常见为：**公开**、**用户**、**管理员**、**Root**。

## 认证方式（二选一）

### Session

通过登录接口获取 Session：

* `POST /api/user/login`

### Access Token（推荐）

在请求头中携带：

```text
Authorization: Bearer {token}
```

Token 可在「个人设置 - 安全设置 - 系统访问令牌」中生成。

## 必需请求头

部分接口要求携带用户标识请求头：

```text
New-Api-User: {user_id}
```

其中 `{user_id}` 必须与当前登录用户匹配。

## 权限级别

* **公开（Public）**：无需鉴权
* **用户（User）**：需要登录或 Access Token
* **管理员（Admin）**：需要管理员权限
* **Root**：最高权限


# 管理接口

import { Card, Cards } from 'fumadocs-ui/components/card';

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/default" title="default" description="查看该分区下的接口" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/logs" title="日志" description="查看该分区下的接口" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/oauth" title="OAuth" description="查看该分区下的接口" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/payment" title="充值" description="查看该分区下的接口" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/security-verification" title="安全验证" description="查看该分区下的接口" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/statistics" title="数据统计" description="查看该分区下的接口" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/system" title="系统" description="查看该分区下的接口" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/tasks" title="任务" description="查看该分区下的接口" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/token-management" title="令牌管理" description="查看该分区下的接口" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/two-factor-auth" title="两步验证" description="查看该分区下的接口" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-auth" title="用户登陆注册" description="查看该分区下的接口" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-management" title="用户管理" description="查看该分区下的接口" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/auth" title="鉴权体系说明（Auth）" description=" · " />
</Cards>


# default

import { Card, Cards } from 'fumadocs-ui/components/card';

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/default/user-topup-post" title="使用兑换码" description="POST · 创建/提交" />
</Cards>


# 使用兑换码

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/default/post-api-user-topup-post-api-user-topup-396792892.json"} operations={[{"path":"/api/user/topup","method":"post"}]} />


# 日志

import { Card, Cards } from 'fumadocs-ui/components/card';

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/logs/log-self-get" title="获取个人日志" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/logs/log-self-search-get" title="搜索个人日志" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/logs/log-self-stat-get" title="获取个人日志统计" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/logs/log-token-get" title="通过令牌获取日志" description="GET · 查询" />
</Cards>


# 获取个人日志

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/日志/get-api-log-self-get-api-log-self-384083933.json"} operations={[{"path":"/api/log/self","method":"get"}]} />


# 搜索个人日志

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/日志/get-api-log-self-search-get-api-log-self-search-384083934.json"} operations={[{"path":"/api/log/self/search","method":"get"}]} />


# 获取个人日志统计

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/日志/get-api-log-self-stat-get-api-log-self-stat-384083931.json"} operations={[{"path":"/api/log/self/stat","method":"get"}]} />


# 通过令牌获取日志

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权（通过令牌查询）

<APIPage document={"openapi/generated/management/日志/get-api-log-token-get-api-log-token-384083935.json"} operations={[{"path":"/api/log/token","method":"get"}]} />


# 安全验证

import { Card, Cards } from 'fumadocs-ui/components/card';

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/security-verification/verify-post" title="通用安全验证" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/security-verification/verify-status-get" title="获取验证状态" description="GET · 查询" />
</Cards>


# 通用安全验证

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/安全验证/post-api-verify-post-api-verify-384083886.json"} operations={[{"path":"/api/verify","method":"post"}]} />


# 获取验证状态

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/安全验证/get-api-verify-status-get-api-verify-status-384083887.json"} operations={[{"path":"/api/verify/status","method":"get"}]} />


# 充值

import { Card, Cards } from 'fumadocs-ui/components/card';

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/payment/user-amount-post" title="获取支付金额" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/payment/user-creem-pay-post" title="发起Creem支付" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/payment/user-pay-post" title="发起易支付" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/payment/user-stripe-amount-post" title="获取Stripe支付金额" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/payment/user-stripe-pay-post" title="发起Stripe支付" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/payment/user-topup-info-get" title="获取充值信息" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/payment/user-topup-self-get" title="获取用户充值记录" description="GET · 查询" />
</Cards>


# 获取支付金额

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/充值/post-api-user-amount-post-api-user-amount-384083873.json"} operations={[{"path":"/api/user/amount","method":"post"}]} />


# 发起Creem支付

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/充值/post-api-user-creem-pay-post-api-user-creem-pay-384083876.json"} operations={[{"path":"/api/user/creem/pay","method":"post"}]} />


# 发起易支付

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/充值/post-api-user-pay-post-api-user-pay-384083872.json"} operations={[{"path":"/api/user/pay","method":"post"}]} />


# 获取Stripe支付金额

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/充值/post-api-user-stripe-amount-post-api-user-stripe-amount-384083875.json"} operations={[{"path":"/api/user/stripe/amount","method":"post"}]} />


# 发起Stripe支付

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/充值/post-api-user-stripe-pay-post-api-user-stripe-pay-384083874.json"} operations={[{"path":"/api/user/stripe/pay","method":"post"}]} />


# 获取充值信息

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/充值/get-api-user-topup-info-get-api-user-topup-info-384083870.json"} operations={[{"path":"/api/user/topup/info","method":"get"}]} />


# 获取用户充值记录

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/充值/get-api-user-topup-self-get-api-user-topup-self-384083871.json"} operations={[{"path":"/api/user/topup/self","method":"get"}]} />


# 获取个人额度数据

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/数据统计/get-api-data-self-get-api-data-self-384083937.json"} operations={[{"path":"/api/data/self","method":"get"}]} />


# 数据统计

import { Card, Cards } from 'fumadocs-ui/components/card';

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/statistics/data-self-get" title="获取个人额度数据" description="GET · 查询" />
</Cards>


# OAuth

import { Card, Cards } from 'fumadocs-ui/components/card';

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/oauth/oauth-discord-get" title="Discord OAuth登录" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/oauth/oauth-email-bind-get" title="绑定邮箱" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/oauth/oauth-github-get" title="GitHub OAuth登录" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/oauth/oauth-linuxdo-get" title="LinuxDO OAuth登录" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/oauth/oauth-oidc-get" title="OIDC登录" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/oauth/oauth-state-get" title="生成OAuth State" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/oauth/oauth-telegram-bind-get" title="绑定Telegram" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/oauth/oauth-telegram-login-get" title="Telegram登录" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/oauth/oauth-wechat-bind-get" title="绑定微信" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/oauth/oauth-wechat-get" title="微信OAuth登录" description="GET · 查询" />
</Cards>


# Discord OAuth登录

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权（OAuth回调）

<APIPage document={"openapi/generated/management/OAuth/get-api-oauth-discord-get-api-oauth-discord-384083835.json"} operations={[{"path":"/api/oauth/discord","method":"get"}]} />


# 绑定邮箱

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/OAuth/get-api-oauth-email-bind-get-api-oauth-email-bind-384083841.json"} operations={[{"path":"/api/oauth/email/bind","method":"get"}]} />


# GitHub OAuth登录

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权（OAuth回调）

<APIPage document={"openapi/generated/management/OAuth/get-api-oauth-github-get-api-oauth-github-384083834.json"} operations={[{"path":"/api/oauth/github","method":"get"}]} />


# LinuxDO OAuth登录

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权（OAuth回调）

<APIPage document={"openapi/generated/management/OAuth/get-api-oauth-linuxdo-get-api-oauth-linuxdo-384083837.json"} operations={[{"path":"/api/oauth/linuxdo","method":"get"}]} />


# OIDC登录

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权（OAuth回调）

<APIPage document={"openapi/generated/management/OAuth/get-api-oauth-oidc-get-api-oauth-oidc-384083836.json"} operations={[{"path":"/api/oauth/oidc","method":"get"}]} />


# 生成OAuth State

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/OAuth/get-api-oauth-state-get-api-oauth-state-384083838.json"} operations={[{"path":"/api/oauth/state","method":"get"}]} />


# 绑定Telegram

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/OAuth/get-api-oauth-telegram-bind-get-api-oauth-telegram-bind-384083843.json"} operations={[{"path":"/api/oauth/telegram/bind","method":"get"}]} />


# Telegram登录

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权（OAuth回调）

<APIPage document={"openapi/generated/management/OAuth/get-api-oauth-telegram-login-get-api-oauth-telegram-login-384083842.json"} operations={[{"path":"/api/oauth/telegram/login","method":"get"}]} />


# 绑定微信

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/OAuth/get-api-oauth-wechat-bind-get-api-oauth-wechat-bind-384083840.json"} operations={[{"path":"/api/oauth/wechat/bind","method":"get"}]} />


# 微信OAuth登录

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权（OAuth回调）

<APIPage document={"openapi/generated/management/OAuth/get-api-oauth-wechat-get-api-oauth-wechat-384083839.json"} operations={[{"path":"/api/oauth/wechat","method":"get"}]} />


# 获取关于信息

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/系统/get-api-about-get-api-about-384083819.json"} operations={[{"path":"/api/about","method":"get"}]} />


# 获取首页内容

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/系统/get-api-home-page-content-get-api-home-page-content-384083820.json"} operations={[{"path":"/api/home_page_content","method":"get"}]} />


# 系统

import { Card, Cards } from 'fumadocs-ui/components/card';

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/system/about-get" title="获取关于信息" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/system/home_page_content-get" title="获取首页内容" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/system/models-get" title="获取模型列表" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/system/notice-get" title="获取公告" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/system/pricing-get" title="获取定价信息" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/system/privacy-policy-get" title="获取隐私政策" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/system/ratio_config-get" title="获取倍率配置" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/system/setup-get" title="获取初始化状态" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/system/setup-post" title="初始化系统" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/system/status-get" title="获取系统状态" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/system/uptime-status-get" title="获取Uptime Kuma状态" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/system/user-agreement-get" title="获取用户协议" description="GET · 查询" />
</Cards>


# 获取模型列表

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/系统/get-api-models-get-api-models-384083822-384083822.json"} operations={[{"path":"/api/models","method":"get"}]} />


# 获取公告

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/系统/get-api-notice-get-api-notice-384083816.json"} operations={[{"path":"/api/notice","method":"get"}]} />


# 获取定价信息

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权（可选登录）

<APIPage document={"openapi/generated/management/系统/get-api-pricing-get-api-pricing-384083821.json"} operations={[{"path":"/api/pricing","method":"get"}]} />


# 获取隐私政策

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/系统/get-api-privacy-policy-get-api-privacy-policy-384083818.json"} operations={[{"path":"/api/privacy-policy","method":"get"}]} />


# 获取倍率配置

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/系统/get-api-ratio-config-get-api-ratio-config-384083823.json"} operations={[{"path":"/api/ratio_config","method":"get"}]} />


# 获取初始化状态

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/系统/get-api-setup-get-api-setup-384083811.json"} operations={[{"path":"/api/setup","method":"get"}]} />


# 初始化系统

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/系统/post-api-setup-post-api-setup-384083812.json"} operations={[{"path":"/api/setup","method":"post"}]} />


# 获取系统状态

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/系统/get-api-status-get-api-status-384083813.json"} operations={[{"path":"/api/status","method":"get"}]} />


# 获取Uptime Kuma状态

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/系统/get-api-uptime-status-get-api-uptime-status-384083815.json"} operations={[{"path":"/api/uptime/status","method":"get"}]} />


# 获取用户协议

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/系统/get-api-user-agreement-get-api-user-agreement-384083817.json"} operations={[{"path":"/api/user-agreement","method":"get"}]} />


# 两步验证

import { Card, Cards } from 'fumadocs-ui/components/card';

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/two-factor-auth/user-2fa-backup_codes-post" title="重新生成备用码" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/two-factor-auth/user-2fa-disable-post" title="禁用2FA" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/two-factor-auth/user-2fa-enable-post" title="启用2FA" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/two-factor-auth/user-2fa-setup-post" title="设置2FA" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/two-factor-auth/user-2fa-status-get" title="获取2FA状态" description="GET · 查询" />
</Cards>


# 重新生成备用码

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/两步验证/post-api-user-2fa-backup-codes-post-api-user-2fa-backup-codes-384083884.json"} operations={[{"path":"/api/user/2fa/backup_codes","method":"post"}]} />


# 禁用2FA

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/两步验证/post-api-user-2fa-disable-post-api-user-2fa-disable-384083883.json"} operations={[{"path":"/api/user/2fa/disable","method":"post"}]} />


# 启用2FA

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/两步验证/post-api-user-2fa-enable-post-api-user-2fa-enable-384083882.json"} operations={[{"path":"/api/user/2fa/enable","method":"post"}]} />


# 设置2FA

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/两步验证/post-api-user-2fa-setup-post-api-user-2fa-setup-384083881.json"} operations={[{"path":"/api/user/2fa/setup","method":"post"}]} />


# 获取2FA状态

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/两步验证/get-api-user-2fa-status-get-api-user-2fa-status-384083880.json"} operations={[{"path":"/api/user/2fa/status","method":"get"}]} />


# 令牌管理

import { Card, Cards } from 'fumadocs-ui/components/card';

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/token-management/token-batch-post" title="批量删除令牌" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/token-management/token-get" title="获取所有令牌" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/token-management/token-id-delete" title="删除令牌" description="DELETE · 删除" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/token-management/token-id-get" title="获取指定令牌" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/token-management/token-post" title="创建令牌" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/token-management/token-put" title="更新令牌" description="PUT · 更新" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/token-management/token-search-get" title="搜索令牌" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/token-management/usage-token-get" title="获取令牌使用情况" description="GET · 查询" />
</Cards>


# 批量删除令牌

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/令牌管理/post-api-token-batch-post-api-token-batch-384083919.json"} operations={[{"path":"/api/token/batch","method":"post"}]} />


# 获取所有令牌

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/令牌管理/get-api-token-get-api-token-384083913.json"} operations={[{"path":"/api/token/","method":"get"}]} />


# 删除令牌

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/令牌管理/delete-api-token-id-delete-api-token-id-384083918.json"} operations={[{"path":"/api/token/{id}","method":"delete"}]} />


# 获取指定令牌

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/令牌管理/get-api-token-id-get-api-token-id-384083917.json"} operations={[{"path":"/api/token/{id}","method":"get"}]} />


# 创建令牌

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/令牌管理/post-api-token-post-api-token-384083914.json"} operations={[{"path":"/api/token/","method":"post"}]} />


# 更新令牌

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/令牌管理/put-api-token-put-api-token-384083915.json"} operations={[{"path":"/api/token/","method":"put"}]} />


# 搜索令牌

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/令牌管理/get-api-token-search-get-api-token-search-384083916.json"} operations={[{"path":"/api/token/search","method":"get"}]} />


# 获取令牌使用情况

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔑 需要令牌认证（TokenAuth）

<APIPage document={"openapi/generated/management/令牌管理/get-api-usage-token-get-api-usage-token-384083920.json"} operations={[{"path":"/api/usage/token/","method":"get"}]} />


# 用户管理

import { Card, Cards } from 'fumadocs-ui/components/card';

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-management/user-aff-get" title="获取邀请码" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-management/user-aff_transfer-post" title="转换邀请额度" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-management/user-models-get" title="获取用户可用模型" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-management/user-passkey-delete" title="删除Passkey" description="DELETE · 删除" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-management/user-passkey-get" title="获取Passkey状态" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-management/user-passkey-register-begin-post" title="开始注册Passkey" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-management/user-passkey-register-finish-post" title="完成注册Passkey" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-management/user-passkey-verify-begin-post" title="开始验证Passkey" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-management/user-passkey-verify-finish-post" title="完成验证Passkey" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-management/user-self-delete" title="注销当前用户" description="DELETE · 删除" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-management/user-self-get" title="获取当前用户信息" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-management/user-self-groups-get" title="获取当前用户分组" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-management/user-self-put" title="更新当前用户信息" description="PUT · 更新" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-management/user-setting-put" title="更新用户设置" description="PUT · 更新" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-management/user-token-get" title="生成访问令牌" description="GET · 查询" />
</Cards>


# 获取邀请码

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/用户管理/get-api-user-aff-get-api-user-aff-384083856.json"} operations={[{"path":"/api/user/aff","method":"get"}]} />


# 转换邀请额度

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/用户管理/post-api-user-aff-transfer-post-api-user-aff-transfer-384083857.json"} operations={[{"path":"/api/user/aff_transfer","method":"post"}]} />


# 获取用户可用模型

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/用户管理/get-api-user-models-get-api-user-models-384083848.json"} operations={[{"path":"/api/user/models","method":"get"}]} />


# 删除Passkey

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/用户管理/delete-api-user-passkey-delete-api-user-passkey-384083851.json"} operations={[{"path":"/api/user/passkey","method":"delete"}]} />


# 获取Passkey状态

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/用户管理/get-api-user-passkey-get-api-user-passkey-384083850.json"} operations={[{"path":"/api/user/passkey","method":"get"}]} />


# 开始注册Passkey

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/用户管理/post-api-user-passkey-register-begin-post-api-user-passkey-register-begin-384083852.json"} operations={[{"path":"/api/user/passkey/register/begin","method":"post"}]} />


# 完成注册Passkey

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/用户管理/post-api-user-passkey-register-finish-post-api-user-passkey-register-finish-384083853.json"} operations={[{"path":"/api/user/passkey/register/finish","method":"post"}]} />


# 开始验证Passkey

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/用户管理/post-api-user-passkey-verify-begin-post-api-user-passkey-verify-begin-384083854.json"} operations={[{"path":"/api/user/passkey/verify/begin","method":"post"}]} />


# 完成验证Passkey

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/用户管理/post-api-user-passkey-verify-finish-post-api-user-passkey-verify-finish-384083855.json"} operations={[{"path":"/api/user/passkey/verify/finish","method":"post"}]} />


# 注销当前用户

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/用户管理/delete-api-user-self-delete-api-user-self-384083847.json"} operations={[{"path":"/api/user/self","method":"delete"}]} />


# 获取当前用户信息

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/用户管理/get-api-user-self-get-api-user-self-384083845.json"} operations={[{"path":"/api/user/self","method":"get"}]} />


# 获取当前用户分组

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/用户管理/get-api-user-self-groups-get-api-user-self-groups-384083844.json"} operations={[{"path":"/api/user/self/groups","method":"get"}]} />


# 更新当前用户信息

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/用户管理/put-api-user-self-put-api-user-self-384083846.json"} operations={[{"path":"/api/user/self","method":"put"}]} />


# 更新用户设置

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/用户管理/put-api-user-setting-put-api-user-setting-384083858.json"} operations={[{"path":"/api/user/setting","method":"put"}]} />


# 生成访问令牌

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/用户管理/get-api-user-token-get-api-user-token-384083849.json"} operations={[{"path":"/api/user/token","method":"get"}]} />


# 用户登陆注册

import { Card, Cards } from 'fumadocs-ui/components/card';

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-auth/reset_password-get" title="发送密码重置邮件" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-auth/user-groups-get" title="获取用户分组列表" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-auth/user-login-2fa-post" title="两步验证登录" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-auth/user-login-post" title="用户登录" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-auth/user-logout-get" title="用户登出" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-auth/user-passkey-login-begin-post" title="开始Passkey登录" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-auth/user-passkey-login-finish-post" title="完成Passkey登录" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-auth/user-register-post" title="用户注册" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-auth/user-reset-post" title="重置密码" description="POST · 创建/提交" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/user-auth/verification-get" title="发送邮箱验证码" description="GET · 查询" />
</Cards>


# 发送密码重置邮件

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/用户登陆注册/get-api-reset-password-get-api-reset-password-384083825.json"} operations={[{"path":"/api/reset_password","method":"get"}]} />


# 获取用户分组列表

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/用户登陆注册/get-api-user-groups-get-api-user-groups-384083831.json"} operations={[{"path":"/api/user/groups","method":"get"}]} />


# 两步验证登录

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权（登录流程）

<APIPage document={"openapi/generated/management/用户登陆注册/post-api-user-login-2fa-post-api-user-login-2fa-384083829.json"} operations={[{"path":"/api/user/login/2fa","method":"post"}]} />


# 用户登录

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/用户登陆注册/post-api-user-login-post-api-user-login-384083828.json"} operations={[{"path":"/api/user/login","method":"post"}]} />


# 用户登出

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/用户登陆注册/get-api-user-logout-get-api-user-logout-384083830.json"} operations={[{"path":"/api/user/logout","method":"get"}]} />


# 开始Passkey登录

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/用户登陆注册/post-api-user-passkey-login-begin-post-api-user-passkey-login-begin-384083832.json"} operations={[{"path":"/api/user/passkey/login/begin","method":"post"}]} />


# 完成Passkey登录

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/用户登陆注册/post-api-user-passkey-login-finish-post-api-user-passkey-login-finish-384083833.json"} operations={[{"path":"/api/user/passkey/login/finish","method":"post"}]} />


# 用户注册

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/用户登陆注册/post-api-user-register-post-api-user-register-384083827.json"} operations={[{"path":"/api/user/register","method":"post"}]} />


# 重置密码

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/用户登陆注册/post-api-user-reset-post-api-user-reset-384083826.json"} operations={[{"path":"/api/user/reset","method":"post"}]} />


# 发送邮箱验证码

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔓 无需鉴权

<APIPage document={"openapi/generated/management/用户登陆注册/get-api-verification-get-api-verification-384083824.json"} operations={[{"path":"/api/verification","method":"get"}]} />


# 任务

import { Card, Cards } from 'fumadocs-ui/components/card';

<Cards>
  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/tasks/mj-self-get" title="获取个人Midjourney任务" description="GET · 查询" />

  <Card href="https://docs.vibeapi.cn/zh/docs/api/management/tasks/task-self-get" title="获取个人任务" description="GET · 查询" />
</Cards>


# 获取个人Midjourney任务

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/任务/get-api-mj-self-get-api-mj-self-384083944.json"} operations={[{"path":"/api/mj/self","method":"get"}]} />


# 获取个人任务

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

🔐 需要登录（User权限）

<APIPage document={"openapi/generated/management/任务/get-api-task-self-get-api-task-self-384083946.json"} operations={[{"path":"/api/task/self","method":"get"}]} />