# Rivo API

> 一个 Key，调用所有主流 AI 模型。兼容 OpenAI / Anthropic / Gemini 格式，5 分钟接入。
>
> Rivo API is an OpenAI- and Anthropic-compatible API gateway. The docs are written in Chinese; endpoints, model IDs and configuration keys are language-neutral.

## 给 AI 助手的说明

帮用户接入 Rivo API 时请遵守以下规则：

- OpenAI 兼容接口（OpenAI SDK、Codex、Cursor 和大多数客户端）的 Base URL 是 `https://api.rivoapi.com/v1`；Anthropic 兼容接口（Claude Code 等）的 Base URL 是 `https://api.rivoapi.com`，不带 `/v1`。
- 使用直连地址 `api.rivoapi.com`，不要把主域名 `rivoapi.com` 当作 Base URL：主域名经过 CDN，长时间的流式请求可能被中断。
- 鉴权方式是 `Authorization: Bearer <API Key>`。Claude Code 用环境变量 `ANTHROPIC_AUTH_TOKEN`，不是 `ANTHROPIC_API_KEY`。
- Rivo 的 API Key 以 `sk-` 开头，由用户在控制台 https://rivoapi.com/console/keys 创建。不要让用户把真实密钥发给你；示例一律用 `sk-YOUR_API_KEY` 占位，提醒用户自己填入。
- 模型 ID 以实时列表为准：https://rivoapi.com/models.md 。不要凭记忆填写模型名。在 Cursor 等客户端里优先使用 `rivo-*` 别名。
- 遇到报错先查错误排查：https://rivoapi.com/docs/errors.md
- 不清楚用户用的是什么工具、什么系统时，直接问用户，不要让用户去填表。

---

# 快速开始

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#quickstart · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

不管你用什么工具，接入 Rivo 只需要做三件事：

1. **注册账号**
   打开 [Rivo API 控制台](https://rivoapi.com/login?mode=register&returnTo=%2Fconsole%2Fkeys)，用邮箱注册并登录。
2. **创建 API Key**
   登录后点左边的 **API 密钥** → **创建新密钥**。创建成功后你会看到一串以 `sk-` 开头的密钥，点"复制"保存好。  
   **这个 Key 只显示一次**，关了就看不到了，请立刻复制。
3. **填到你的工具里**
   在你用的 AI 工具（Cursor、Claude Code、Codex 等）的设置里，找到"API Base URL"和"API Key"两项，分别填入：

   - **API Base URL**：`https://api.rivoapi.com`（部分工具要加 `/v1`，下面各工具教程会说明）
   - **API Key**：刚才复制的 `sk-...`

> **CC Switch 快捷导入**：在控制台的 API 密钥页面，每个 Key 那一行都有 **CC Switch 一键导入**按钮。如果你安装了 [CC Switch](https://github.com/nicepkg/cc-switch)（免费开源工具，支持一键切换多个 API 配置），直接点那个按钮就能把 Key 导入到 Claude Code / Codex，不用手动填。

---

# API 信息

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#api-info · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

下面是你填配置时会用到的地址。如果只是跟着教程走，不用记这些，直接看对应工具的教程复制就行。

| 配置项 | 值 |
|---|---|
| API Base URL | `https://api.rivoapi.com` |
| Chat Completions | `https://api.rivoapi.com/v1/chat/completions` |
| Responses API | `https://api.rivoapi.com/v1/responses` |
| 模型列表 | `https://api.rivoapi.com/v1/models` |
| API Key 格式 | `sk-xxxxxxxx`（在控制台「API 密钥」页面获取） |

## 验证你的 Key 是否正常

拿到 Key 后，打开终端（Mac 的"终端"app / Windows 的 PowerShell），粘贴下面这条命令（把 `sk-YOUR_API_KEY` 换成你的真实 Key）：

```bash
curl https://api.rivoapi.com/v1/models -H "Authorization: Bearer sk-YOUR_API_KEY"
```

如果返回一大串 JSON（里面有模型名字），说明 Key 没问题。如果报错，看下面的[错误排查](https://rivoapi.com/docs/errors.md)。

我们可能会使用您的服务使用数据（包括请求和响应内容）用于服务改进、模型优化及相关研究目的。我们会采取合理措施保护您的信息安全。

---

# 一键接入脚本

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#oneclick · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

懒得手动改配置文件？用下面的一键脚本，复制到终端跑一下就搞定。把 `sk-YOUR_API_KEY` 换成你的真实 Key。

## Claude Code

Anthropic 官方 CLI 编程工具

macOS / Linux：

```bash
curl -fsSL https://rivoapi.com/docs/scripts/claude-code.sh | bash -s -- sk-YOUR_KEY
```

Windows（PowerShell）：

```powershell
& ([scriptblock]::Create((irm https://rivoapi.com/docs/scripts/claude-code.ps1))) -ApiKey sk-YOUR_KEY
```

## Codex CLI

OpenAI 官方终端编程工具

macOS / Linux：

```bash
curl -fsSL https://rivoapi.com/docs/scripts/codex.sh | bash -s -- sk-YOUR_KEY
```

Windows（PowerShell）：

```powershell
& ([scriptblock]::Create((irm https://rivoapi.com/docs/scripts/codex.ps1))) -ApiKey sk-YOUR_KEY
```

## 免梯子装 Codex（CLI+Desktop+自动更新）

国内直连装最新 Codex CLI 与桌面端、自动配好 Rivo，并**持续自动更新**（无需梯子、无需人工；镜像自 rivoapi）

macOS：

```bash
curl -fsSL https://rivoapi.com/docs/scripts/install-mac.sh | bash -s -- sk-YOUR_KEY
```

Windows（PowerShell）：

```powershell
irm https://rivoapi.com/docs/scripts/install-win.ps1 -OutFile i.ps1; .\i.ps1 -ApiKey sk-YOUR_KEY
```

CLI 与桌面端(Win MSIX / Mac dmg)全部从 rivoapi 镜像直下；Win 桌面走 .appinstaller 原生自动更新，CLI 与 Mac 桌面走后台定时更新。完整性由包签名兜底。

## cc-switch（Claude+Codex）

一条命令同时配好 Claude Code 与 Codex（可选 GPT-5.6）

macOS / Linux：

```bash
curl -fsSL https://rivoapi.com/docs/scripts/cc-switch.sh | bash -s -- sk-YOUR_KEY
```

Windows（PowerShell）：

```powershell
& ([scriptblock]::Create((irm https://rivoapi.com/docs/scripts/cc-switch.ps1))) -ApiKey sk-YOUR_KEY
```

## Cursor（半自动）

会复制 Key 到剪贴板并打开设置引导

macOS / Linux：

```bash
curl -fsSL https://rivoapi.com/docs/scripts/cursor.sh | bash -s -- sk-YOUR_KEY
```

Windows（PowerShell）：

```powershell
& ([scriptblock]::Create((irm https://rivoapi.com/docs/scripts/cursor.ps1))) -ApiKey sk-YOUR_KEY
```

## Claude VSCode 扩展

配置 VS Code 内嵌终端环境变量

macOS / Linux：

```bash
curl -fsSL https://rivoapi.com/docs/scripts/claude-vscode.sh | bash -s -- sk-YOUR_KEY
```

Windows（PowerShell）：

```powershell
& ([scriptblock]::Create((irm https://rivoapi.com/docs/scripts/claude-vscode.ps1))) -ApiKey sk-YOUR_KEY
```

> **脚本做了什么**？每个脚本只做一件事：把 Rivo 的地址和你的 Key 写到对应工具的配置文件里。写之前会自动备份原配置。脚本内容完全公开，[点这里查看源码](https://rivoapi.com/docs/scripts/)。

> **Cursor 为什么是"半自动"**？因为 Cursor 把设置存在内部数据库里，没办法通过文件直接写入。脚本会把信息复制到剪贴板，你按提示在 Cursor 设置界面粘贴就行。

---

# 让 AI 帮你接入

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#ai-prompts · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

不想自己看教程？把下面对应的一句话复制给 ChatGPT、Claude、豆包、Kimi，或者你正在用的 AI 编程工具。它会自己打开链接读文档，一步步带你配好，需要的信息会直接问你。

> **不要把密钥发给 AI**：文档会让 AI 用 `sk-YOUR_API_KEY` 占位。让它告诉你填在哪里，再自己把真实 Key 填进去。

## 通用：任意工具

```
按这个帮我把正在用的工具接入 Rivo：https://rivoapi.com/llms.txt
```

## Claude Code

```
按这个帮我把 Claude Code 接入 Rivo：https://rivoapi.com/docs/claude-code.md
```

## Codex CLI / Codex Desktop

```
按这个帮我把 Codex 接入 Rivo：https://rivoapi.com/docs/codex.md
```

## Cursor

```
按这个帮我把 Cursor 接入 Rivo：https://rivoapi.com/docs/cursor.md
```

## 聊天客户端（Cherry Studio、ChatBox、LobeChat 等）

```
按这个帮我把聊天客户端接入 Rivo：https://rivoapi.com/llms.txt
```

## 在自己的代码里调用

```
按这个帮我在代码里调用 Rivo：https://rivoapi.com/docs/openai-sdk.md
```

> **想把可用模型一起告诉 AI**？在控制台「API 密钥」页面，点某个密钥的「使用方法」→「交给 AI」→「复制详细版」，会写好这个密钥能用的模型。

只想让 AI 读某一节？点每一节标题右侧的「复制给 AI」。AI 工具也可以直接读取 [/llms.txt](https://rivoapi.com/llms.txt)（文档目录）和 [/llms-full.txt](https://rivoapi.com/llms-full.txt)（全文）。

---

# API 调用示例

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#examples · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

如果你是开发者，想在自己的程序里调用 Rivo API，参考下面的代码：

**cURL**

```bash
curl https://api.rivoapi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{
    "model": "claude-sonnet-4-6",
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

**Python**

```python
from openai import OpenAI

client = OpenAI(
    api_key="sk-YOUR_API_KEY",
    base_url="https://api.rivoapi.com/v1"
)

response = client.chat.completions.create(
    model="claude-sonnet-4-6",
    messages=[{"role": "user", "content": "你好"}]
)
print(response.choices[0].message.content)
```

> **先装依赖**：`pip install openai`

**Node.js**

```javascript
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-YOUR_API_KEY',
  baseURL: 'https://api.rivoapi.com/v1',
});

const res = await client.chat.completions.create({
  model: 'claude-sonnet-4-6',
  messages: [{ role: 'user', content: '你好' }],
});
console.log(res.choices[0].message.content);
```

> **先装依赖**：`npm install openai`

---

# API 端点

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#endpoints · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

所有接口共用 Base URL `https://api.rivoapi.com` 和同一把 API Key。新项目优先使用核心接口，旧 SDK 或厂商原生协议再展开兼容接口。

## 核心接口

| 方法与路径 | 用途 |
|---|---|
| `POST /v1/chat/completions` | OpenAI 兼容对话，绝大多数 SDK 和工具优先使用 |
| `POST /v1/responses` | OpenAI Responses API，Codex 与推理型客户端使用 |
| `POST /v1/messages` | Anthropic Messages，可直接使用 Anthropic SDK |
| `POST /v1/images/generations` | 文生图，支持同步与异步任务 |
| `POST /v1/images/edits` | 改图、多图合成与扩图，使用 multipart 表单 |
| `POST /v1/videos` | 创建异步视频任务，随后轮询并下载 |
| `GET /v1/models` | 列出当前密钥实际可调用的模型 |

## 兼容与专项接口

| 方法与路径 | 用途 |
|---|---|
| `POST /v1/responses/compact` | 为支持该能力的 Responses 模型压缩上下文 |
| `POST /v1/completions` | 旧版文本补全协议 |
| `POST /v1/embeddings` | 文本向量化 |
| `POST /v1/audio/transcriptions` | 语音转文字 |
| `POST /v1/audio/translations` | 语音转英文文本 |
| `POST /v1/audio/speech` | 文字转语音 |
| `POST /v1/rerank` | 检索结果重排序 |
| `POST /v1/decisions` | 结构化决策（TypeSafe Jev），按次计费，见[决策模型](https://rivoapi.com/docs/endpoints.md) |
| `POST /v1/moderations` | 内容审核 |
| `WS /v1/realtime` | 实时模型 WebSocket |
| `POST /v1/video/generations` | 通用视频任务兼容格式 |
| `POST /v1beta/models/{model}:generateContent` | Gemini 原生协议 |

> **明确不支持**：`/v1/images/variations`、`/v1/files` 和 `/v1/fine-tunes` 尚未实现，请勿按可用能力接入。

> **模型可用性**：接口存在不代表每把密钥都有对应模型。调用前请用 `GET /v1/models` 查询当前密钥实际可用的模型。

## 对话与推理

常规 OpenAI SDK 使用 `/v1/chat/completions`；Codex 或 Responses 客户端使用 `/v1/responses`；Anthropic SDK 使用 `/v1/messages`。

**开启推理模式**：把模型名加 `-thinking` 后缀即可，请求体不用改。例如 `claude-sonnet-4-6-thinking`、`claude-opus-4-6-thinking`、`claude-haiku-4-5-20251001-thinking`。

> **OpenAI 风格的 `reasoning_effort`**：支持把模型名写成 `gpt-5.5-high` / `gpt-5.5-medium` / `gpt-5.5-low` / `gpt-5.5-xhigh`，会自动转成 `reasoning_effort` 参数发给上游；如果你的 SDK 已经能直接传 `reasoning_effort` 字段也可以。

## 生图（文生图 + 改图）

生图模型用 `gpt-image-2`。生图有两个端点，**用途完全不同**，下面分开说：

| 端点 | 用途 | 请求格式 |
|---|---|---|
| `POST /v1/images/generations` | **文生图**：只靠文字描述生成图 | JSON |
| `POST /v1/images/edits` | **改图 / 多图合成 / 扩图**：上传 1～N 张参考图 + 文字描述 | multipart/form-data |
| `GET /v1/images/generations/:task_id` `GET /v1/images/edits/:task_id` | **异步轮询**：取异步任务结果（见下方④） | — |

### ① 文生图

```bash
curl https://api.rivoapi.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只穿着宇航服的橘猫在月球表面，电影质感",
    "size": "1024x1024",
    "n": 1
  }'
```

### ② 改图 / 多图合成（重要）

注意请求格式是 **multipart/form-data**，不是 JSON。字段支持三种命名方式，自由选用：

单张参考图：

```bash
curl https://api.rivoapi.com/v1/images/edits \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@photo.png" \
  -F "prompt=把背景换成沙滩" \
  -F "size=1024x1024"
```

多张参考图（用 image[]）：

```bash
curl https://api.rivoapi.com/v1/images/edits \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image[]=@cat.png" \
  -F "image[]=@dog.png" \
  -F "image[]=@background.png" \
  -F "prompt=把这只猫和这只狗放在这个背景里"
```

> **模型选择**：请以 `GET /v1/models` 返回的图像模型为准。DALL-E 2 时代的 `/v1/images/variations` 不受支持，类似效果请使用 `/v1/images/edits`。

### ③ 支持的参数（质量 / 尺寸 / 比例 / 背景）

下列参数**文生图（JSON 字段）和改图（multipart 表单字段 `-F`）通用**。除 `prompt` 外都可选；不传则用各自默认值（多数默认 `auto`，即由模型自动决定）。

| 参数 | 可选值 | 说明 |
|---|---|---|
| `model` | `gpt-image-2` | 必填，固定填 `gpt-image-2` |
| `prompt` | 文字 | 必填。文生图=画面描述；改图=修改指令 |
| `n` | 1 ~ N 的整数 | 一次生成几张，默认 1 |
| `size` | 常用 `1024x1024` / `1536x1024` / `1024x1536` / `auto`；也支持**任意 `宽x高`**（约束见下方说明） | 出图**尺寸 / 分辨率**，同时决定画面比例（清晰度由它决定），默认 `auto` |
| `quality` | `low` / `medium` / `high` / `auto` | 渲染质量（出图**精细度**，不是分辨率）。`high` 出图最精细、计费为基础价 **1.5 倍**；`low` / `medium` / `auto` 均按基础价（**不分档加价**）。`auto`（默认，不传即此值）由模型自动选择，性价比最高 |
| `background` | `transparent` / `opaque` / `auto` | 背景：透明 / 不透明 / 自动。透明需配合 `png` 或 `webp` |
| `output_format` | `png` / `jpeg` / `webp` | 输出图片格式，默认 `png` |
| `output_compression` | 0 ~ 100 | 仅 `jpeg`/`webp` 生效，压缩质量百分比 |
| `moderation` | `auto` / `low` | 内容审核强度，默认 `auto` |
| `async` | `true` / `false` | 异步模式（见下方④），默认 `false` |

**常用尺寸 ↔ 比例**（下面是推荐值，**不是全部**—— `gpt-image-2` 支持任意自定义分辨率，见再下方）：

| `size` | 比例 | 方向 | 适合 |
|---|---|---|---|
| `1024x1024` | 1:1 | 方形 | 头像、图标、商品图 |
| `1536x1024` | 3:2 | 横向 / 宽幅 | 横版海报、Banner、风景 |
| `1024x1536` | 2:3 | 竖向 / 长图 | 手机壁纸、竖版海报、人物全身 |
| `2880x2880` | 1:1 | 大方图（≈4K） | 高分辨率方图（已到像素上限） |
| `3840x2160` | 16:9 | 横向 4K | 桌面壁纸、视频封面 |
| `auto` | — | 自动 | 模型按 `prompt` 自己挑（不想纠结时用） |

> **自定义分辨率（`gpt-image-2`**）：可以传任意 `宽x高`，只要满足：① 宽、高都能被 **16 整除**；② 最长边 ≤ **3840**；③ 总像素在 **655,360（640×1024）~ 8,294,400（≈4K，如 3840×2160 / 2880×2880**） 之间；④ 比例在 **1:3 ~ 3:1** 之间。合法尺寸原样出图、不降级。也接受 `16:9` / `16x9` / `1920×1080` 这类写法。仅因边长不是 16 的倍数（或略超长边/像素上限）而不合法的尺寸，会被**保持原始宽高比**就近吸附到最近的合法尺寸（如 `1086x1448` → `1088x1456`、`1920x1080` → `1920x1088`），**不会压成正方形**，也不会报错。局部重绘（`/v1/images/edits`）传原图尺寸即可让输出跟随原图比例。只有比例本身超出 1:3~3:1 才会回退到最接近的常用比例尺寸。

> **关于 `auto`**：不传 `size`/`quality`/`background` 就等于传 `auto`，由模型自动决定。**计费**：按出图尺寸的像素面积计（尺寸越大越贵），`size=auto` 按 1K 基准价；`quality=high` 约为基础价的 1.5 倍。默认 `auto` 即最省档，按需要再调大尺寸或提高质量。

> **返回格式**：同步请求默认返回 base64（`b64_json`）；异步（`async:true`）轮询返回的是对象存储**下载 URL**（不占内存，1 小时内有效）。

完整参数示例（文生图，JSON）：

```json
curl https://api.rivoapi.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "一只穿宇航服的橘猫在月球表面，电影质感",
    "size": "1536x1024",
    "quality": "high",
    "background": "auto",
    "output_format": "png",
    "n": 1
  }'
```

完整参数示例（改图，注意是表单字段 -F）：

```bash
curl https://api.rivoapi.com/v1/images/edits \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@photo.png" \
  -F "prompt=把背景换成沙滩，保留人物" \
  -F "size=1024x1536" \
  -F "quality=high" \
  -F "background=transparent" \
  -F "output_format=png"
```

### ④ 异步模式（生图慢、批量时强烈推荐）

生图通常要 **1～4 分钟**。异步模式下**提交即拿 `task_id`**，无需一直挂着连接等待，更适合批量生成、慢图和自动化脚本，也避免长连接超时。用法：请求里加 `"async": true`（文生图是 JSON 字段，改图是 multipart 表单字段 `-F "async=true"`），秒回 `task_id`，再 GET 轮询取结果。和视频是同一套思路。

异步三步走：

```
# 1. 提交（文生图加 "async":true；改图用 -F "async=true"）
curl https://api.rivoapi.com/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{"model":"gpt-image-2","prompt":"一只在窗台晒太阳的橘猫","size":"1024x1024","n":1,"async":true}'
# 返回: {"id":"imggen_123","object":"image.generation.task","status":"queued",...}

# 2. 轮询任务（改图同理用 /v1/images/edits/<task_id>）
curl https://api.rivoapi.com/v1/images/generations/<task_id> \
  -H "Authorization: Bearer sk-YOUR_API_KEY"
# 处理中: {"status":"processing"}
# 成功:   {"status":"succeeded","data":[{"url":"<图片下载链接>"}]}
# 失败:   {"status":"failed","error":{...}}    (HTTP 200，错误在 body 里)

# 3. 成功后直接下载 data[].url（对象存储链接，1 小时内有效）
```

> **异步说明**：按成功出图计费、失败不计费、轮询不计费；图片存对象存储，轮询返回的是**下载 URL**（不是 base64，不占内存，1 小时内有效）。`n>1` 时提交返回 `data` 数组、每张一个 `task_id`，各自轮询。

### 统一生图模型与计费

生图模型使用 canonical 名称，按图片标准 / 图片稳定分组路由。当前公开模型为 `gpt-image-2`、`nano-banana-2`、`nano-banana-pro` 和 `grok-imagine-image`（仅 1K）。

| 模型 | 规格 | 图片标准 | 图片稳定 |
|---|---|---|---|
| `gpt-image-2` | 1K / 2K / 4K，`quality=standard` | ¥0.06 / ¥0.08 / ¥0.12 / 张 | ¥0.10 / ¥0.15 / ¥0.22 / 张 |
| `gpt-image-2` | 1K / 2K / 4K，`quality=high` | ¥0.09 / ¥0.12 / ¥0.18 / 张 | ¥0.15 / ¥0.22 / ¥0.32 / 张 |
| `nano-banana-2` | 1K / 2K / 4K | ¥0.10 / ¥0.14 / ¥0.18 / 张 | ¥0.12 / ¥0.17 / ¥0.22 / 张 |
| `nano-banana-pro` | 1K / 2K / 4K | ¥0.12 / ¥0.17 / ¥0.24 / 张 | ¥0.15 / ¥0.21 / ¥0.30 / 张 |
| `grok-imagine-image` | 1K | — | ¥0.06 / 张 |

兼容别名仍可路由，但不会出现在模型列表。图片同步返回通常是 `b64_json`；异步模式返回任务 URL。

## 视频

视频生成**都是异步任务**：先 POST 提交任务拿到 `task_id`，再 GET 轮询拉结果。我们提供 4 套端点，按需选一套：

| 端点 | 协议 / 上游 | 说明 |
|---|---|---|
| `POST /v1/videos` + `GET /v1/videos/:id` | OpenAI Sora 兼容 | 推荐起步用这套（最简单） |
| `POST /v1/video/generations` + `GET /v1/video/generations/:id` | 通用 task | 对接 Runway / fal.ai 等聚合上游 |
| `POST /kling/v1/videos/text2video` `POST /kling/v1/videos/image2video` | 可灵原生 | 需要可灵原生字段时使用 |
| `POST /jimeng/` | 即梦原生 | 字节即梦 Action API 格式 |
| `GET /v1/videos/:task_id/content` | 通用 | 任务完成后下载视频文件（mp4） |

### 图生视频：单图、首尾帧与多参考图

`seedance-2.5` 支持多张参考图，但“首尾帧”和“多参考图融合”是两种不同模式：

| 想要的效果 | 请求字段 | 说明 |
|---|---|---|
| 单图生视频 | `image` | 传 1 个公网 HTTP(S) 图片 URL，作为起始画面或主体参考 |
| 指定首帧 + 尾帧 | `image` + `last_image` | `image` 是首帧，`last_image` 是尾帧；模型生成中间过渡 |
| 多张参考图融合 | `images` + `reference_images` | 两个数组必须放完全相同的 URL，并保持相同顺序；参考图用于人物、物体、服装、场景或风格融合 |

> **不要混用两种模式**：需要严格控制开头和结尾时，用 `image` + `last_image`；需要融合多个主体或风格时，用多参考图数组。只要传了 `reference_images`，就不要再传 `image` 或 `last_image`。

> **尺寸写法**：`size` 推荐传 OpenAI 风格像素尺寸，例如 `1280x720`、`720x1280`、`1920x1080`；历史写法 `480p`、`720p`、`1080p`、`2k`、`4k` 继续兼容。需要显式拆开时，也可以传 `resolution` + `aspect_ratio`，例如 `"resolution":"720p","aspect_ratio":"16:9"`。

Seedance 2.5：首帧 + 尾帧：

```bash
curl https://api.rivoapi.com/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "镜头从雨天街道自然过渡到日落海边，主体动作连贯",
    "seconds": "4",
    "size": "1920x1080",
    "image": "https://example.com/first-frame.jpg",
    "last_image": "https://example.com/last-frame.jpg"
  }'
```

Seedance 2.5：多张参考图融合：

```bash
curl https://api.rivoapi.com/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "让第一张图的人物穿上第二张图的服装，出现在第三张图的场景中，自然转身",
    "seconds": "4",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "images": [
      "https://example.com/person.jpg",
      "https://example.com/outfit.jpg",
      "https://example.com/scene.jpg"
    ],
    "reference_images": [
      "https://example.com/person.jpg",
      "https://example.com/outfit.jpg",
      "https://example.com/scene.jpg"
    ]
  }'
```

> **Seedance 多图注意**：参考图顺序会原样传给模型，但多参考图模式不保证第一张就是成片首帧、最后一张就是成片尾帧。`seedance-2.5` 最多接受 30 张参考图，目前已实测双图融合；多参考图请求请使用 `1080p`。图片必须是模型能直接访问的公网 HTTP(S) URL，不能传本机路径（如 `C:\a.jpg` 或 `/Users/me/a.jpg`）。

### 统一对外模型名与计费

模型名只使用 canonical 名称；供应商代号、分辨率后缀和渠道 SKU（例如 `dvc-*`、`seedance-2.5-480p`）只保留兼容路由，不出现在模型广场和标准模型列表。标准 / 稳定是供货池档位，不代表画质差异；同一模型和规格的输出要求相同。

| 模型 | 支持规格 | 标准档 | 稳定档 |
|---|---|---|---|
| `seedance-2.0` | 480p / 720p / 1080p / 4K，4–15 秒 | ¥0.27 / ¥0.55 / ¥1.45 / ¥2.95 每秒 | ¥0.50 / ¥0.78 / ¥1.60 / ¥3.50 每秒 |
| `seedance-2.0-fast` | 480p / 720p，4–15 秒 | ¥0.36 / ¥0.73 每秒 | ¥0.40 / ¥0.80 每秒 |
| `seedance-2.0-mini` | 480p / 720p，4–15 秒 | ¥0.16 / ¥0.38 每秒 | ¥0.18 / ¥0.46 每秒 |
| `seedance-2.5` | 480p / 720p / 1080p，4–30 秒 | ¥0.40 / ¥0.65 / ¥1.45 每秒 | ¥0.90 / ¥1.95 / ¥1.70 每秒 |
| `seedance-2.5` | 480p / 720p，31–180 秒长时平台扩展 | ¥1.15 / ¥2.25 每秒 | 暂未开放 |
| `seedance-1.5` | 480p / 720p / 1080p | ¥0.15 / ¥0.22 / ¥0.32 每秒 | 暂未开放 |
| `grok-imagine-video` | 文生 / 图生，1–15 秒 | ¥0.10 每秒 | 暂未开放 |
| `wan2.7` | 720p / 1080p | ¥0.30 / ¥0.32 每秒 | 暂未开放 |
| `wan3.0` | 文生视频，480p / 720p / 1080p，5–30 秒 | ¥0.35 / ¥0.70 / ¥1.40 每秒 | 暂未开放 |
| `wan3.0` | 图生视频，480p / 720p / 1080p，5–30 秒 | ¥0.36 / ¥0.44 / ¥0.58 每秒 | 暂未开放 |
| `happyhouse` | 文生 / 图生，按条计费 | ¥3.40 每条 | 暂未开放 |
| `minimax-h3` | 768p / 2K / 4K，按条计费 | ¥3.40 / ¥4.50 / ¥6.50 每条 | 暂未开放 |
| `omni-video` | 文生 / 图生，含水印 | ¥0.80 每秒 | 暂未开放 |
| `omni-video` | 文生 / 图生，`watermark=false` | ¥0.95 每秒 | 暂未开放 |
| `omni-video` | 视频转视频，含水印 | ¥1.05 每秒 | 暂未开放 |
| `omni-video` | 视频转视频，`watermark=false` | ¥1.20 每秒 | 暂未开放 |

> **计费说明**：多数视频模型按秒计费，最终费用 = 对应档位单价 × `seconds`；`happyhouse` 与 `minimax-h3` 按条计费，与时长无关。轮询和下载不重复收费，任务失败自动退款。`size` 可使用像素尺寸（如 `1280x720`）或 `480p`、`720p`、`1080p`、`2k`、`4k`；具体可用档位以模型表和能力接口为准。`seconds` ≤ 30 为普通规格，31–180 为长时平台扩展，模型名仍统一使用 `seedance-2.5`。单图、首尾帧和多参考图字段见上方示例；视频转视频使用 `videos`。`audio=false` 已统一映射为无音频参数。`omni-video` 的价格按 `watermark` 与是否视频转视频区分，四档规格相同、仅供货与水印不同。上述“暂未开放”的稳定档表示该规格目前只有单一供货池，未发布第二档。

### 视频接口三步走

OpenAI 视频兼容三步走：

```
# 1. 提交任务（文生 / 图生 / 视频转视频共用标准接口）
curl https://api.rivoapi.com/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{
    "model": "seedance-2.5",
    "prompt": "一只猫在草地上奔跑，电影镜头",
    "seconds": "4",
    "size": "720p",
    "audio": true
  }'
# 返回里取出 id（即 task_id）

# 2. 轮询任务状态
curl https://api.rivoapi.com/v1/videos/<task_id> \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

# 3. 状态 completed 后下载视频
curl https://api.rivoapi.com/v1/videos/<task_id>/content \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -o output.mp4
```

## 音乐生成

`gemini-music` 按次生成约 30 秒音乐，当前价格为 **¥1.20/条**。接口为异步任务：

Gemini Music 提交与轮询：

```
# 1. 提交
curl https://api.rivoapi.com/v1/audio/generations \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-music","prompt":"轻柔钢琴与弦乐，无人声"}'

# 2. 使用返回的 id 轮询
curl https://api.rivoapi.com/v1/audio/generations/<task_id> \
  -H "Authorization: Bearer sk-YOUR_API_KEY"

# completed 后从 data[0].url 下载 m4a
```

## 音频

| 端点 | 用途 | 常用模型 |
|---|---|---|
| `POST /v1/audio/transcriptions` | 语音转文字（可保留原语言） | `whisper-1` |
| `POST /v1/audio/translations` | 语音转文字并翻译成英文 | `whisper-1` |
| `POST /v1/audio/speech` | 文字转语音（TTS） | `tts-1`、`tts-1-hd` |

文字转语音示例：

```bash
curl https://api.rivoapi.com/v1/audio/speech \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{
    "model": "tts-1",
    "input": "你好，世界",
    "voice": "alloy"
  }' \
  --output speech.mp3
```

## 决策模型（TypeSafe Jev）

`jev` 是 TypeSafe 的「System One」决策模型：不生成文字，只对你给的 `state` 回答带类型的问题并返回**校准过的概率**，典型响应 70–500ms。适合工单分诊、路由、审核过滤、规则判断等「要一个可靠的判定而不是一段话」的场景。**按次计费 ¥0.03/次**，与 token 数无关；一次请求里可以放多个问题，一并评估只算一次。

| 问题类型 | 含义 | 返回 |
|---|---|---|
| `noul` | 是 / 否 | `noul`：为“是”的概率 0–1 |
| `choice` | 从 `criteria` 里选一项 | `choice` + `confidence` + 各选项 `probabilities` |
| `score` | 在有序等级（2–10 级）上打分 | `score`（期望等级）+ 各等级概率 |

Jev 决策示例：

```bash
curl https://api.rivoapi.com/v1/decisions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{
    "model": "jev",
    "state": "支付连续失败三天了，客服没人回，明天就要上线！",
    "questions": {
      "is_urgent": {"type": "noul", "instructions": "这条消息是否紧急？"},
      "department": {
        "type": "choice",
        "instructions": "应该交给哪个团队处理？",
        "criteria": {"billing": "支付、发票、退款", "technical": "故障、集成问题", "sales": "价格、升级、开户"}
      }
    }
  }'

# 返回示例
# {"model":"typesafe/jev-1.13-20260917",
#  "answers":{"is_urgent":{"type":"noul","noul":0.96},
#             "department":{"type":"choice","choice":"billing","confidence":0.97,
#                           "probabilities":{"billing":0.98,"technical":0.02,"sales":0}}},
#  "usage":{"input_tokens":403,"output_tokens":73}}
```

> **注意**：Jev 只走 `/v1/decisions`，用 `/v1/chat/completions` 调它会报模型不可用；`state` 可以是字符串、JSON 对象或数组，上下文上限 32K tokens。

---

# Claude Code 配置

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#claude-code · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[Claude Code](https://docs.anthropic.com/en/docs/claude-code) 是 Anthropic 官方出的命令行 AI 编程助手，在终端里用，非常强大。

> **前提**：需要先装 Node.js（版本 18 以上）。Mac/Linux 终端输入 `node --version` 能看到版本号就行。没装的话去 [nodejs.org](https://nodejs.org) 下载安装。

## 安装 Claude Code

```bash
npm install -g @anthropic-ai/claude-code
```

Mac/Linux 如果提示权限不够，前面加 `sudo`。装完输入 `claude --version` 确认能出版本号。

## 方式一：配置文件（推荐，永久生效）

编辑 `~/.claude/settings.json`（没有这个文件就新建一个），写入：

`~/.claude/settings.json`：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.rivoapi.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-YOUR_API_KEY"
  }
}
```

> **注意两个坑**：  
> 1. 变量名是 `ANTHROPIC_AUTH_TOKEN` 不是 `ANTHROPIC_API_KEY`，用错了会认证失败。  
> 2. 如果你之前用过官方 Anthropic 账号登录，先跑 `claude /logout` 退出，否则会冲突。

## 方式二：环境变量（临时用一下）

**Mac / Linux**

```bash
export ANTHROPIC_BASE_URL="https://api.rivoapi.com"
export ANTHROPIC_AUTH_TOKEN="sk-YOUR_API_KEY"
claude
```

**Windows**

```powershell
$env:ANTHROPIC_BASE_URL = "https://api.rivoapi.com"
$env:ANTHROPIC_AUTH_TOKEN = "sk-YOUR_API_KEY"
claude
```

## 验证

启动 Claude Code 后输入 `/status`，看到 **Anthropic base URL** 显示 `https://api.rivoapi.com` 就成功了。

## 在 Claude Code 里使用 GPT 模型

完成上面的 Rivo Base URL 和 Key 配置后，Claude Code 也可以直接使用 GPT 模型。Rivo 会接收 Claude Code 的 Anthropic 格式请求，并自动路由到对应的 GPT 上游，**Base URL 和 Key 不需要修改**。

### 方法一：在 Claude Code 中用 `/model` 切换（推荐）

启动 Claude Code 后直接输入完整模型名：

```
/model gpt-5.6-sol
```

也可以只输入 `/model` 打开模型选择器。如果列表里暂时没有显示 GPT 模型，直接输入上面的完整命令即可。切换后用 `/status` 确认当前模型。

> **其它 GPT-5.6 档位**：`gpt-5.6-sol` 是旗舰档；需要更高性价比或更快响应时，可切换为 `gpt-5.6-terra` 或 `gpt-5.6-luna`。可用模型见下方[模型列表](https://rivoapi.com/docs/models.md)。

### 调整 GPT 推理强度（effort）

切换到 GPT 模型后，可以用 `/effort` 调整速度和推理深度：

```
/effort high
```

可选档位为 `low`、`medium`、`high`、`xhigh`、`max`。档位越高，复杂任务通常推理更充分，但响应更慢、消耗也更高。只输入 `/effort` 可以打开交互式选择器。

也可以在启动时同时指定模型和 effort。普通 Claude Code 使用第一行；如果你的 `ccp` 快捷命令会把参数透传给 Claude Code，则使用第二行：

```bash
claude --model gpt-5.6-sol --effort high
ccp --model gpt-5.6-sol --effort high
```

> Rivo 会把 Claude Code 发出的 `output_config.effort` 转换为 GPT 上游使用的 `reasoning_effort`。日常编码建议从 `high` 开始，特别复杂的重构或调研再使用 `xhigh` / `max`。

### 方法二：在配置文件中设为默认模型

想让以后每次启动都默认使用 GPT，在 Claude Code 配置文件的**顶层**加入 `model`：

`~/.claude/settings.json`：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.rivoapi.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-YOUR_API_KEY"
  },
  "model": "gpt-5.6-sol",
  "effortLevel": "high"
}
```

`effortLevel` 是可选项，用来设置新会话的默认推理强度。改完后重启 Claude Code，再输入 `/status` 验证。之后仍然可以随时用 `/model` 和 `/effort` 切换。

> **使用 `ccp` 等自定义快捷命令时**：如果快捷命令设置了 `CLAUDE_CONFIG_DIR`，应修改该目录下的 `settings.json`。例如 `CLAUDE_CONFIG_DIR=~/.claude-solo` 时，实际配置文件是 `~/.claude-solo/settings.json`，修改普通的 `~/.claude/settings.json` 不会生效。

> **想保留 `/model` 自由切换时，不要在 `env` 中固定 `ANTHROPIC_MODEL`**。环境变量的优先级高于配置文件顶层的 `model`，会导致新会话再次被锁回环境变量指定的模型。推荐使用上面的顶层 `"model": "gpt-5.6-sol"` 写法。

### WebSearch 显示 `Did 0 searches`

如果 Claude Code 能发起 WebSearch，但最后显示搜索 0 次，通常不是 API Key 失效，而是搜索所用的后台模型被自定义配置强制改成了 GPT。主对话仍然可以使用 GPT，但 WebSearch 后台任务需要使用支持 Anthropic 搜索工具的 Claude 模型。

> **检查模型覆盖**：在当前实际生效的 `settings.json`、Shell 启动脚本或快捷命令中查找 `CLAUDE_CODE_SUBAGENT_MODEL` 和 `ANTHROPIC_DEFAULT_HAIKU_MODEL`。如果它们被设置为 `gpt-*`，请删除该覆盖，或改成 Claude 模型。

**Mac / Linux**

终端排查：

```bash
# 查看 Claude Code 实际使用的配置目录
echo "${CLAUDE_CONFIG_DIR:-$HOME/.claude}"

# 查看当前进程继承到的后台模型覆盖
env | grep -E 'CLAUDE_CODE_SUBAGENT_MODEL|ANTHROPIC_DEFAULT_HAIKU_MODEL'
```

**Windows**

PowerShell 排查：

```powershell
# 查看 Claude Code 实际使用的配置目录
if ($env:CLAUDE_CONFIG_DIR) { $env:CLAUDE_CONFIG_DIR } else { "$HOME\.claude" }

# 查看当前进程继承到的后台模型覆盖
Get-ChildItem Env: | Where-Object Name -Match 'CLAUDE_CODE_SUBAGENT_MODEL|ANTHROPIC_DEFAULT_HAIKU_MODEL'
```

例如可以把后台模型改为 `claude-haiku-4-5-20251001`。修改后需要完全退出并重新启动 Claude Code；已经运行的会话不会自动读取新配置。

## 想切回官方 Anthropic 订阅？

删掉 Rivo 的配置，重新用官方账号登录：

```bash
# 打开 ~/.claude/settings.json，删掉 env 里的 ANTHROPIC_BASE_URL 和 ANTHROPIC_AUTH_TOKEN
# 然后重新登录官方账号
claude /login
```

---

# Codex CLI 配置

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#codex · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[Codex CLI](https://github.com/openai/codex) 是 OpenAI 官方的终端 AI 编程助手。

> **前提**：需要 Node.js 22 以上版本。终端输入 `node --version` 确认。没装去 [nodejs.org](https://nodejs.org) 下载 LTS 版。

## 安装

```bash
npm install -g @openai/codex
```

## 写配置文件

需要创建两个文件。先创建目录：Mac/Linux 是 `~/.codex/`，Windows 是 `%USERPROFILE%\.codex\`。

**文件 1：`~/.codex/config.toml`**

`~/.codex/config.toml`：

```toml
model_provider = "OpenAI"
model = "gpt-5.6-sol"

[model_providers.OpenAI]
name = "OpenAI"
base_url = "https://api.rivoapi.com/v1"
wire_api = "responses"
requires_openai_auth = false
experimental_bearer_token = "sk-YOUR_API_KEY"
http_headers = { "x-openai-actor-authorization" = "local-image-extension" }

[features]
image_generation = true
```

**文件 2：`~/.codex/auth.json`**

`~/.codex/auth.json`：

```json
{
  "auth_mode": "apikey",
  "OPENAI_API_KEY": "sk-YOUR_API_KEY"
}
```

> **一个 Rivo Key 同时用于对话和生图**。上面的配置会开启 Codex 原生 `image_gen`，图片请求仍发送到 `api.rivoapi.com`，不需要另配 OpenAI Key 或安装生图插件。

> **别手打 key，一定要从控制台「令牌」页面用复制按钮复制**。 key 里的小写字母 `l` 和数字 `1`、大写 `O` 和数字 `0` 长得几乎一样，手打极易输错，结果就是 `401 Unauthorized: Invalid token`。复制后可先粘到记事本确认开头是 `sk-`、前后无空格、无断行，再填进命令。

> **不要**把 `requires_openai_auth` 改回 `true`，也不要删除 `x-openai-actor-authorization`。否则 API Key 会话不会注册原生生图工具，Codex 会错误地要求配置官方 `OPENAI_API_KEY`。

> **Codex 0.149 起必须写 `experimental_bearer_token`**。从这个版本开始，自定义供应商**不再读取 `auth.json`**（`requires_openai_auth = false` 且没有配 key 时，Codex 一个 `Authorization` 头都不发），表现就是**一直 401**。把这一行填成你的 Key 即可；它同时会覆盖被 ChatGPT 桌面端改回登录态的 `auth.json`。`auth.json` 仍然要写，旧版本 Codex 靠它。

> **这份 config.toml 现在含明文 Key**。发给客服或贴到群里排查问题前，请先把 `experimental_bearer_token` 和 `auth.json` 里的 Key 打码。

> **Codex Desktop 用户注意活动 Provider**。桌面端会按 `model_provider` 标识保存和筛选本地历史。不要为了换 Key 把已有 `custom` 强改成 `OpenAI`，否则会话文件仍在，但侧边栏会像“全部丢失”。最新版一键脚本会优先复用原有 Rivo Provider，并同步修补它的配置。

## 启动验证

**完全退出** Codex Desktop（Mac 用 `Cmd+Q`，不能只关窗口）或结束旧 CLI 进程，再重新打开并**新建会话**。旧会话不会热刷新工具列表。输入“调用 `image_gen` 生成一张绿苹果图片”，看到图片保存并展示才算验证成功。

## 想切回 ChatGPT 自己的订阅？

```bash
# 删掉指向 Rivo 的配置
rm -f ~/.codex/auth.json ~/.codex/config.toml

# 重新走 ChatGPT 官方登录
codex login
```

看到 `"auth_mode": "chatgpt"` 就切回去了。

---

# Codex Desktop 配置

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#codex-desktop · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[Codex Desktop](https://openai.com/index/codex/) 是桌面版，和 Codex CLI **共用同一份配置文件**。按上面 [Codex CLI](https://rivoapi.com/docs/codex.md) 配好就行。

配置后需要**完全退出 Codex Desktop 并新建会话**：macOS 用 **⌘Q**，Windows 从任务栏托盘退出。Codex 在会话启动时注册 `image_gen`，旧会话不会自动获得新工具。

> 如果对话仍提示配置官方 `OPENAI_API_KEY`，说明当前还是旧配置或旧会话。重新运行 Rivo 一键脚本，完全退出 Codex Desktop 后再新建会话。

---

# cc-switch 一键切换（含 GPT-5.6）

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#cc-switch · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[cc-switch](https://github.com/farion1231/cc-switch) 是一款跨平台桌面工具，用来管理多家 API 供应商、在 Claude Code / Codex / Gemini CLI 等之间一键切换。把 Rivo 加进去有两种方式：

## 方式一：一键脚本（推荐）

先跑下面的脚本——它会把 **Claude Code**（`~/.claude/settings.json`）和 **Codex**（`~/.codex/config.toml` + `auth.json`）这两个 cc-switch 托管的真实配置文件都写好（自动备份、幂等合并，不覆盖你已有的其它设置）。把 `sk-YOUR_KEY` 换成你的 Key：

Mac / Linux：

```bash
curl -fsSL https://rivoapi.com/docs/scripts/cc-switch.sh | bash -s -- sk-YOUR_KEY
```

Windows (PowerShell)：

```powershell
& ([scriptblock]::Create((irm https://rivoapi.com/docs/scripts/cc-switch.ps1))) -ApiKey sk-YOUR_KEY
```

跑完后打开 cc-switch，在对应工具下点 **「从当前配置导入 / Import current」**，就会生成一个 Rivo 供应商，之后随时一键切换。

## 方式二：在 cc-switch 里手动添加供应商

| 工具（预设） | Base URL | Auth / API Key | 备注 |
|---|---|---|---|
| Claude Code | `https://api.rivoapi.com` | 你的 Rivo Key（sk-…） | 用 claude-* 模型 |
| Codex | `https://api.rivoapi.com/v1` | 你的 Rivo Key（sk-…） | `wire_api = responses`；用 gpt-* 模型 |

> **Base URL 结尾不要带 `/`**——cc-switch 对末尾斜杠敏感，多一个斜杠会导致 401 / 连接失败。

## GPT-5.6 全系列（Sol / Terra / Luna）

GPT-5.6 走 **OpenAI / Codex** 通道。三个档位按官方价对齐计费：

| 模型 | 定位 | 官方价（输入 / 输出，每 1M tokens） |
|---|---|---|
| `gpt-5.6-sol` | 旗舰，最强推理 | $5 / $30 |
| `gpt-5.6-terra` | 均衡，性价比高 | $2.5 / $15 |
| `gpt-5.6-luna` | 轻量高速 | $1 / $6 |

在 Codex 里把 `config.toml` 的 `model` 改成对应名字即可；或用一键脚本直接指定模型（第 2 个参数）：

```bash
curl -fsSL https://rivoapi.com/docs/scripts/codex.sh | bash -s -- sk-YOUR_KEY gpt-5.6-sol
```

> Codex、CC Switch 和控制台统一使用 `gpt-5.6-sol`。历史配置中的 `gpt-sol-5.6` 仍可兼容，无需重装。

---

# Cursor 配置

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#cursor · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[Cursor](https://cursor.com) 是很多人用的 AI 代码编辑器。接入 Rivo 后，Chat / Agent / Cmd+K 都能用自定义模型。

> **前置要求**：Cursor 仅 **Pro 订阅及以上**（Pro / Business / Enterprise）支持自定义 API Base URL 与第三方 Key。Free 版没有 `Override OpenAI Base URL` 开关，无法接入 Rivo。可在 **Cursor → Settings → 账户**页查看订阅状态。

## 配置步骤

1. **打开设置**
   Cursor 顶部菜单 → **Settings** → **Cursor Settings** → 左边选 **Models**
2. **填 API Key**
   展开 **API Keys** → 打开 **OpenAI API Key** 开关 → 粘贴你的 Rivo Key（`sk-` 开头，注意不要有空格）
3. **填 Base URL**
   打开 **Override OpenAI Base URL** → 填：`https://api.rivoapi.com/v1`  
   **必须带 `/v1`**，不带的话 Cursor 会请求错误的地址
4. **添加模型**
   在搜索框输入 `rivo-5.5-xhigh`（GPT-5.5 高推理强度，**推荐**）或其他 `rivo-*` 模型 → 点 **Add Custom Model** → 确认开关是开的。  
   **别填原生模型名**（`claude-*` / `gpt-*` / `o1-*`），Cursor 会按这些前缀走它自己的限速 / 内置模型，请求可能根本不发到 Rivo。
5. **测试**
   回到聊天面板，**关掉顶部的 Auto 开关**，在模型下拉里选你刚加的模型，发一条消息试试。

## Rivo 可用模型（在 Cursor 里填这些名字）

推荐用 `rivo-*` 别名。原因：填 `claude-sonnet-4-6` 这种原生名，Cursor 可能识别到同名内置模型、走它自己的额度，不经过你的 Rivo Key；填 `gpt-*` / `o1-*` 还会被 Cursor 客户端按"OpenAI 桶"本地限速，请求可能根本发不出来。

| Cursor 里填 | 实际模型 |
|---|---|
| 实时别名列表见 https://rivoapi.com/models.md |  |

> **想调推理强度**？在别名后面加后缀就行，Rivo 会自动注入 `reasoning_effort`：  
> `rivo-5.5-xhigh`（最强，推荐 GPT-5.5 配它）/ `rivo-5.5-high` / `rivo-5.5-medium` / `rivo-5.5-low` / `rivo-5.5-minimal`  
> 后缀对所有 `rivo-*` 别名通用，不需要再加额外配置；客户端如果自己传了 `reasoning_effort`，则以客户端为准。

## 遇到问题？

| 你看到的 | 原因和解法 |
|---|---|
| "Rate Limit Exceeded" / "User Provided API Key Rate Limit Exceeded" | Cursor 把很多错误都显示成这个，**多数情况下请求根本没发出去**。按顺序查：① 模型名是不是含 `gpt` / `o1` / `o3` / `chatgpt`（Cursor 会按这些关键字本地限速）→ 改用 `rivo-5.5-xhigh` 这种不含上述关键字的别名 ② Base URL 是否带了 `/v1` ③ Key 是否完整 ④ 余额是否充足 ⑤ 令牌是否被禁用 |
| "Model name is not valid" | Cursor 客户端不认这个模型名。换成 `rivo-*` 别名就行 |
| 聊天面板找不到模型 | ① 关掉 Auto 开关 ② 确认 Models 页里该模型的开关是开的 |
| 回复只有一两个字 | 检查项目里是否有 `.cursor/rules/*.mdc` 且 `alwaysApply: true`，Cursor 会把 rule 注入 prompt，可能影响输出 |

## 想切回 Cursor 自带的额度？

在 **Settings → Cursor Settings → Models** 里：

- 关掉 **OpenAI API Key** 开关
- 清空 **Override OpenAI Base URL**
- 删掉你添加的 `rivo-*` 自定义模型
- 打开 **Auto** 开关，回到 Cursor 内置模型

---

# Kiro IDE 配置

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#kiro · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[Kiro](https://kiro.dev) 是 AWS 出的 AI IDE。它本身不支持改 Base URL，但可以在它的内置终端里用 Claude Code。

在 Kiro 内置终端里运行 `claude`（前提是你按上面 [Claude Code](https://rivoapi.com/docs/claude-code.md) 教程配好了环境变量或 settings.json）。

---

# Windsurf 配置

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#windsurf · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[Windsurf](https://windsurf.com)（原 Codeium）原生不支持自定义 API，需要装 **Roo Code** 扩展来接入 Rivo。步骤见 [Roo Code 配置](https://rivoapi.com/docs/roo-code.md)。

---

# Cline 配置

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#cline · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[Cline](https://cline.bot) 是 VS Code 上很火的 AI 编程扩展。

1. **打开设置**
   VS Code 里点 Cline 面板的 ⚙️ 图标
2. **选 Provider**
   下拉选 **OpenAI**（或 **OpenAI Compatible**）
3. **填配置**
   - **Base URL**：`https://api.rivoapi.com/v1`
   - **API Key**：`sk-YOUR_API_KEY`
   - **Model**：`claude-sonnet-4-6` 或 `gpt-5.4`

---

# Roo Code 配置

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#roo-code · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[Roo Code](https://roocode.com)（原 Roo Cline）是 VS Code / Cursor / Windsurf 通用的 AI 扩展。

1. **装扩展**
   扩展市场搜 **Roo Code**，装上
2. **打开设置**
   点 Roo Code 面板右上角 ⚙️
3. **选 Provider**
   API Provider 选 **OpenAI Compatible**
4. **填配置**
   - **Base URL**：`https://api.rivoapi.com/v1`
   - **API Key**：`sk-YOUR_API_KEY`
   - **Model ID**：`claude-sonnet-4-6`

---

# Continue.dev 配置

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#continue · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[Continue](https://continue.dev) 是 VS Code / JetBrains 的开源 AI 编程扩展。

安装后点 ⚙️ 打开 `config.yaml`，加入：

`~/.continue/config.yaml`：

```yaml
models:
  - name: Rivo Claude
    provider: openai
    model: claude-sonnet-4-6
    apiBase: https://api.rivoapi.com/v1
    apiKey: sk-YOUR_API_KEY
  - name: Rivo GPT
    provider: openai
    model: gpt-5.4
    apiBase: https://api.rivoapi.com/v1
    apiKey: sk-YOUR_API_KEY
```

---

# Aider 配置

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#aider · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[Aider](https://aider.chat) 是终端 AI 结对编程工具。

`~/.zshrc 或 ~/.bashrc`：

```bash
export OPENAI_API_KEY="sk-YOUR_API_KEY"
export OPENAI_API_BASE="https://api.rivoapi.com/v1"
```

然后用 `openai/` 前缀跑：

```bash
aider --model openai/claude-sonnet-4-6
```

---

# OpenCode 配置

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#opencode · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[OpenCode](https://opencode.ai) 是终端 TUI AI 编程工具。

启动后输入 `/connect` → 选 **Other** → Provider ID 填 `rivo` → 粘贴 Key。

或者直接编辑配置文件 `~/.config/opencode/opencode.json`：

`opencode.json`：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "rivo": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Rivo API",
      "options": {
        "baseURL": "https://api.rivoapi.com/v1",
        "apiKey": "sk-YOUR_API_KEY"
      }
    }
  },
  "model": "rivo/claude-sonnet-4-6"
}
```

---

# OpenClaw 配置

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#openclaw · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[OpenClaw](https://openclaw.com) 是可自部署的 AI 助手网关，能接 WhatsApp、Telegram、Slack 等。

> **前提**：Node.js 22.16+ 或 24+。Windows 用户建议用 WSL2。

## 方式一：向导接入（推荐新手）

1. **安装 OpenClaw**
   ```bash
   curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard
   ```

   装完跑 `openclaw --help` 确认能用。
2. **跑向导**
   ```bash
   openclaw onboard
   ```
3. **在向导里选"Custom provider"**
   按提示填入：

   - **兼容类型**：选 `OpenAI-compatible`
   - **Base URL**：`https://api.rivoapi.com/v1`
   - **Model**：`gpt-5.4` 或 `claude-sonnet-4-6`
   - **Provider ID**：`rivo`
   - **API Key**：你的 Rivo Key

   如果选 `Anthropic-compatible`，Base URL 填 `https://api.rivoapi.com`（不带 /v1）。
4. **验证**
   ```bash
   openclaw doctor && openclaw status && openclaw dashboard
   ```

   浏览器打开后发一条消息，能回复就成功了。

## 方式二：直接编辑配置文件

编辑 `~/.openclaw/openclaw.json`：

`~/.openclaw/openclaw.json`：

```json
{
  "env": { "RIVO_API_KEY": "sk-YOUR_API_KEY" },
  "agents": {
    "defaults": {
      "model": { "primary": "rivo/claude-sonnet-4-6" }
    }
  },
  "models": {
    "providers": {
      "rivo": {
        "baseUrl": "https://api.rivoapi.com/v1",
        "apiKey": "${RIVO_API_KEY}",
        "api": "openai-completions",
        "models": [
          { "id": "claude-sonnet-4-6", "name": "Claude Sonnet 4.6" },
          { "id": "gpt-5.4", "name": "GPT-5.4" }
        ]
      }
    }
  }
}
```

> **最容易写错的地方**：默认模型必须写成 `rivo/模型名`（有斜杠），不能只写模型名。

---

# Cherry Studio 配置

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#cherry-studio · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[Cherry Studio](https://cherry-ai.com) 是多模型 AI 桌面客户端，支持 Windows / macOS / Linux。

1. **添加服务商**
   **设置** → **模型服务** → **添加服务商** → 选 **OpenAI** 类型
2. **填配置**
   - **服务商名称**：随便填，比如 `Rivo`
   - **API 地址**：`https://api.rivoapi.com`
   - **API Key**：`sk-YOUR_API_KEY`
3. **拉模型列表**
   点 **获取模型** 按钮，会自动列出所有可用模型
4. **开始聊天**
   新建对话，选刚加的模型，发一条验证

> **想用 Claude 原生格式**？再加一个 **Anthropic** 类型服务商，API 地址同样填 `https://api.rivoapi.com`，Key 相同。Rivo 的一个 Key 同时支持 OpenAI 和 Anthropic 两种格式，不需要分开建。

---

# ChatBox 配置

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#chatbox · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[ChatBox](https://chatboxai.app) 多平台 AI 桌面客户端。

**设置** → **AI 模型提供商** → **OpenAI API**：

- **API Host**：`https://api.rivoapi.com`
- **API Key**：`sk-YOUR_API_KEY`
- **API Path**：保持默认

---

# Open WebUI 配置

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#open-webui · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[Open WebUI](https://openwebui.com) 自部署 AI 聊天界面。

管理员登录 → 右上角头像 → **管理员面板** → **设置** → **连接**：

- **OpenAI API base URL**：`https://api.rivoapi.com/v1`
- **API Key**：`sk-YOUR_API_KEY`

Docker 部署时加环境变量也行：`-e OPENAI_API_BASE_URL=https://api.rivoapi.com/v1 -e OPENAI_API_KEY=sk-YOUR_API_KEY`

---

# LobeChat 配置

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#lobechat · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[LobeChat](https://lobechat.com) 开源 AI 聊天框架。

左下角头像 → **设置** → **语言模型** → **OpenAI**：

- **API Key**：`sk-YOUR_API_KEY`
- **API 代理地址**：`https://api.rivoapi.com/v1`

点 **检查** 按钮验证。

---

# NextChat 配置

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#nextchat · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[NextChat](https://github.com/ChatGPTNextWeb/ChatGPT-Next-Web)（ChatGPT Next Web）开源 Web 聊天客户端。

左下角 **设置**：

- **接口地址**：`https://api.rivoapi.com`
- **API Key**：`sk-YOUR_API_KEY`

---

# 沉浸式翻译 配置

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#immersive · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

[沉浸式翻译](https://immersivetranslate.com) 浏览器翻译扩展。

扩展 → **设置** → **翻译服务** → 选 **OpenAI**：

- **API Key**：`sk-YOUR_API_KEY`
- **自定义接口地址**：`https://api.rivoapi.com/v1/chat/completions`
- **模型**：`gpt-5.4-mini`（推荐，翻译够用又便宜）

---

# OpenAI SDK 接入

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#openai-sdk · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

Rivo 完全兼容 OpenAI SDK，改两行就行：`base_url` 和 `api_key`。

## Python（流式输出）

```python
from openai import OpenAI

client = OpenAI(api_key="sk-YOUR_API_KEY", base_url="https://api.rivoapi.com/v1")

stream = client.chat.completions.create(
    model="claude-opus-4-6",
    messages=[{"role": "user", "content": "Hello"}],
    stream=True
)
for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

## Node.js / TypeScript

```typescript
import OpenAI from 'openai';

const client = new OpenAI({ apiKey: 'sk-YOUR_API_KEY', baseURL: 'https://api.rivoapi.com/v1' });

const stream = await client.chat.completions.create({
  model: 'claude-opus-4-6',
  messages: [{ role: 'user', content: 'Hello' }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}
```

---

# 环境变量配置（通用）

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#env-vars · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

很多工具都支持通过环境变量配置，设一次到处生效。

## OpenAI 兼容工具（Codex、Aider、LangChain 等）

`~/.zshrc 或 ~/.bashrc`：

```bash
export OPENAI_API_KEY="sk-YOUR_API_KEY"
export OPENAI_BASE_URL="https://api.rivoapi.com/v1"
```

## Anthropic 兼容工具（Claude Code 等）

`~/.zshrc 或 ~/.bashrc`：

```bash
export ANTHROPIC_BASE_URL="https://api.rivoapi.com"
export ANTHROPIC_AUTH_TOKEN="sk-YOUR_API_KEY"
```

注意：Anthropic 格式的 Base URL **不加** `/v1`。

## Windows（PowerShell 永久设置）

PowerShell（管理员）：

```powershell
[System.Environment]::SetEnvironmentVariable("OPENAI_API_KEY", "sk-YOUR_API_KEY", "User")
[System.Environment]::SetEnvironmentVariable("OPENAI_BASE_URL", "https://api.rivoapi.com/v1", "User")
```

> **设完重启终端才生效**。

---

# 支持的模型

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#models · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

下面是主推模型，完整列表在控制台的[模型价格](https://rivoapi.com/pricing)页面。

## Claude 系列（Anthropic）

**Rivo 预置别名**（推荐，避开 Cursor 校验问题）：

| 别名 | 实际模型 |
|---|---|
| 实时别名列表见 https://rivoapi.com/models.md |  |

**原生模型名**：

| 模型 | 说明 |
|---|---|
| `claude-opus-4-7` | 最强推理 |
| `claude-opus-4-6` | 上一代 Opus |
| `claude-sonnet-4-6` | 均衡首选 |
| `claude-haiku-4-5` | 快速轻量 |

## 决策模型（TypeSafe）

| 模型 | 说明 |
|---|---|
| `jev` | 结构化决策（是/否、单选、打分），仅 `/v1/decisions`，按次 ¥0.03 |

## GPT 系列（OpenAI）

| 模型 | 说明 |
|---|---|
| `gpt-5.4` | 最新旗舰 |
| `gpt-5.4-mini` | 高性价比 |
| `gpt-5.3-codex` | 编程专用 |
| `gpt-5.1-codex-max` | 编程能力天花板 |

## Gemini 系列（Google）

| 模型 | 说明 |
|---|---|
| `gemini-3.1-pro-preview` | 最新 Pro |
| `gemini-3-flash` | 快速 |
| `gemini-2.5-pro` | 百万级上下文 |

获取全部模型列表：

```bash
curl https://api.rivoapi.com/v1/models -H "Authorization: Bearer sk-YOUR_API_KEY"
```

---

# 错误排查

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#errors · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

遇到报错？对照下表找原因：

| 错误信息 | 含义 | 解决方法 |
|---|---|---|
| 401 / Invalid token / 无效的令牌 | Key 不对或已失效 | 去控制台重新复制 Key，确认完整（sk- 开头）且没有多余空格；新建的 Key 也一直 401？见[案例一](https://rivoapi.com/docs/errors.md)、[案例三](https://rivoapi.com/docs/errors.md) |
| 403 / Forbidden | Key 没有权限访问该模型 | 检查令牌是否绑定了模型白名单，或分组是否正确；codex 用户见[案例四](https://rivoapi.com/docs/errors.md) |
| 429 / Rate Limit | 请求太频繁 | 稍等几秒重试，或在控制台调整令牌的速率限制 |
| Insufficient balance / 余额不足 | 额度用完了 | 控制台充值 |
| No available channel / 无可用渠道 | 该模型暂时没有上游可用 | 等几分钟重试，或换一个模型 |
| 502 Bad Gateway | 连接上游失败 | 通常是临时性问题，1-2 分钟后重试；若报错来自 `127.0.0.1`（CC Switch 本地代理）见[案例五](https://rivoapi.com/docs/errors.md) |
| 连接失败 / 发送请求时出错 / error sending request（本地代理） | 你本机网络连不出去，请求没到服务器 | 重启网络代理或换个网络；见[案例五](https://rivoapi.com/docs/errors.md) |
| 正在重新连接 1/5…5/5，URL 已是 `api.rivoapi.com` | API 长连接可能被 Clash/Surge 等再次转发到境外代理 | 重跑一键配置，或在代理规则中添加 `DOMAIN,api.rivoapi.com,DIRECT`；见[案例六](https://rivoapi.com/docs/errors.md) |
| 503 Service Unavailable | 上游过载或维护中 | 切换模型或稍后重试 |
| 返回 HTML 而不是 JSON | Base URL 填错了 | 确认 URL 是 `https://api.rivoapi.com/v1`（该带 /v1 的要带） |

> **万能排查法**：用 curl 直接请求试试（命令在[上面](https://rivoapi.com/docs/api-info.md)）。如果 curl 正常但工具报错，说明问题在工具的配置，不是 Rivo 的问题。

## 连接类问题实战案例（一直重试 / 401 / stream disconnected）

以下案例来自真实用户排障，覆盖了绝大多数「客户端一直重试，最后失败」的情况。对号入座，一般 3 分钟能修好。

### 案例一：Claude Code 一直 401，但 Key 明明是新建的、也没填错

**症状**：新建了 Key、地址也配对了，Claude Code 仍然「正在重新连接」然后失败；控制台用量里完全看不到你的请求。

**原因**：电脑上残留了 `ANTHROPIC_API_KEY` 环境变量（常见是以前配 DeepSeek、阿里百炼等其他平台时留下的）。Claude Code 会把它和 `ANTHROPIC_AUTH_TOKEN` **同时**发出去，而服务端**优先校验 `ANTHROPIC_API_KEY` 那一把**——你新配的 Key 永远轮不到被校验，于是永远 401。

**自查**：在 Claude Code 里输入 `/status`——如果同时看到 `Auth token: ANTHROPIC_AUTH_TOKEN` 和 `API key: ANTHROPIC_API_KEY` 两行，就是这个问题。

**修复（Windows**）：

1. PowerShell 运行 `echo $env:ANTHROPIC_API_KEY`，有输出就是它在捣乱
2. 系统设置 → 搜「编辑账户的环境变量」→ 删除 `ANTHROPIC_API_KEY`（用户变量和系统变量都检查）
3. 再看 `C:\Users\你的用户名\.claude\settings.json`，`"env"` 段里若有 `ANTHROPIC_API_KEY` 也删掉
4. 完全退出 Claude Code 重新打开，`/status` 只剩 Auth token 一行即修好

**修复（macOS / Linux**）：终端运行 `echo $ANTHROPIC_API_KEY`，有值就到 `~/.zshrc`、`~/.bashrc`、`~/.claude/settings.json` 里删掉对应行，重开终端和 Claude Code。

### 案例二：codex 报「stream disconnected before completion: error sending request」，重连 5 次失败

**症状**：报错里的 URL 是 `https://rivoapi.com/...`（注意——**没有 api. 前缀**）。

**原因**：Base URL 配成了主域名。主域名走 Cloudflare 代理，长流式请求（模型思考期长时间不吐字）在部分网络环境下会被中间层掐断。

**修复**：把 Base URL 改成直连地址——codex 填 `https://api.rivoapi.com/v1`，Claude Code 填 `https://api.rivoapi.com`。改完立即恢复。

### 案例三：一直 401，后台却查不到你的任何请求记录

**要点**：401/403 的请求**不会**出现在用量日志里——「后台没记录」不代表请求没发出去，恰恰说明 Key 没通过认证。

**常见原因**：Key 在控制台被删除或重置过（客户端还存着旧的）；复制时带了空格、少了字符；或贴成了别家平台的 Key（Rivo 的 Key 是 `sk-` 开头 + 48 位字母数字混合；`sk-` + 32 位纯十六进制的是别家平台的）。

**修复**：到控制台重新完整复制一次 Key 并替换客户端里的旧值。

### 案例四：403「该令牌无权访问模型 gpt-5.5-codex」

**原因**：令牌开了「模型白名单」但只勾了 `gpt-5.5`。codex 客户端默认请求的是 `gpt-5.5-codex`，不在白名单里就 403，客户端表现同样是反复重试。

**修复**：编辑令牌，把 `gpt-5.5-codex` 一起加入白名单（或干脆不限制模型）。

### 案例五：CC Switch 报「502 网关错误 / 转发失败：连接失败：发送请求时出错」

**症状**：报错来自 CC Switch 本地代理（`127.0.0.1:15721`），Base URL 是对的（带 `api.` 前缀，如 `https://api.rivoapi.com/v1/responses`），提示「连接失败 / 发送请求时出错 / error sending request」。

**原因**：这是**你本机的网络连接问题**——CC Switch 往上游转发时连不出去，请求还没到 Rivo 服务器。**不是账号或余额问题**，我们后台也查不到这条请求。

**修复**：依次尝试 ① 重启 CC Switch / 你的网络代理或 VPN ② 换一个网络（如手机热点）。codex 一般会自动重连，任务通常不会坏。

### 案例六：URL 已是 api.rivoapi.com，Codex / Cursor 仍反复重连

**症状**：Codex 显示「正在重新连接 1/5…5/5」，最后报 `stream disconnected before completion: error sending request`；报错 URL 已经是正确的 `https://api.rivoapi.com/v1/responses`。

**原因**：Clash、Surge、Shadowrocket 等系统代理把 `api.rivoapi.com` 又送进了境外代理节点。这样实际链路会变成「本机 → 境外代理 → Rivo 国内入口 → 美西服务」，多出一个容易中断的长连接跳点；某次断开会触发 1/5 重试，连续 5 次失败就是最终报错。

**修复**：重新运行本页的一键配置脚本，它会自动追加系统代理例外和 `NO_PROXY`。也可在代理软件规则顶部手动添加 `DOMAIN,api.rivoapi.com,DIRECT`。修改后完全退出并重开 Codex / Cursor / Claude Code。

---

# 常见问题

> Rivo API 文档 · 网页版：https://rivoapi.com/docs/#faq · 文档索引：https://rivoapi.com/llms.txt

> **给 AI**：请按本文一步步帮用户完成操作。API Key 用 `sk-YOUR_API_KEY` 占位，让用户自己填，不要索要真实密钥；模型 ID 以 https://rivoapi.com/models.md 为准；不清楚用户的工具或系统时直接问。

### Q: Rivo 和直接用 OpenAI / Anthropic 官方 API 有什么区别？

接口格式完全一样，只是换了个地址和 Key。额外好处：一个 Key 能调所有厂商的模型、有用量统计和负载均衡。

### Q: 支持流式输出吗？

支持。请求里加 `"stream": true` 就行。

### Q: Claude Code 提示认证失败？

先跑 `claude /logout`，确认用的是 `ANTHROPIC_AUTH_TOKEN`（不是 `ANTHROPIC_API_KEY`），重启。如果一直 401，大概率是电脑上残留了旧的 `ANTHROPIC_API_KEY` 环境变量把新 Key 顶掉了——见[错误排查·案例一](https://rivoapi.com/docs/errors.md)。

### Q: Cursor 里 Base URL 要不要加 /v1？

**要加**。填 `https://api.rivoapi.com/v1`。

### Q: 为什么 Cursor 提示 "Model name is not valid"？

换 `rivo-*` 别名就行，Cursor 对非内置模型名不做校验。

### Q: 支持哪些 API 格式？

- **OpenAI 格式**：`/v1/chat/completions`、`/v1/responses`、`/v1/embeddings`、`/v1/images/generations`
- **Anthropic 格式**：`/v1/messages`
- **Gemini 格式**：`/v1beta/models/*`