Rivo API 使用文档

快速开始

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

API 信息

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

验证你的 Key 是否正常

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

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

如果返回一大串 JSON（里面有模型名字），说明 Key 没问题。如果报错，看下面的错误排查。

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

一键接入脚本

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

API 调用示例

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

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": "你好"}]
  }'

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)

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);

API 端点

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

核心接口

对话与推理

常规 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。

生图（文生图 + 改图）

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

① 文生图

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。字段支持三种命名方式，自由选用：

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

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

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

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

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

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
  }'

curl https://api.rivoapi.com/v1/images/edits \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -F "model=gpt-image-2" \
  -F "[email protected]" \
  -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 小时内有效）

视频

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

# 1. 提交任务
curl https://api.rivoapi.com/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-YOUR_API_KEY" \
  -d '{
    "model": "sora-2",
    "prompt": "一只猫在草地上奔跑，电影镜头",
    "seconds": "8",
    "size": "1280x720"
  }'
# 返回里取出 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

音频

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

Claude Code 配置

Claude Code 是 Anthropic 官方出的命令行 AI 编程助手，在终端里用，非常强大。

安装 Claude Code

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

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

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

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

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

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

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

$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 推理强度（effort）

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

/effort high

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

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

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

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

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

{
  "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 切换。

WebSearch 显示 Did 0 searches

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

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

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

# 查看 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 的配置，重新用官方账号登录：

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

Codex CLI 配置

Codex CLI 是 OpenAI 官方的终端 AI 编程助手。

安装

npm install -g @openai/codex

写配置文件

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

文件 1：~/.codex/config.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
http_headers = { "x-openai-actor-authorization" = "local-image-extension" }

[features]
image_generation = true

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

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

启动验证

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

想切回 ChatGPT 自己的订阅？

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

# 重新走 ChatGPT 官方登录
codex login

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

Codex Desktop 配置

Codex Desktop 是桌面版，和 Codex CLI 共用同一份配置文件。按上面 Codex CLI 配好就行。

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

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

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：

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

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

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

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

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

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

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

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

Cursor 配置

Cursor 是很多人用的 AI 代码编辑器。接入 Rivo 后，Chat / Agent / Cmd+K 都能用自定义模型。

配置步骤

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

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

遇到问题？

想切回 Cursor 自带的额度？

在 Settings → Cursor Settings → Models 里：

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

Kiro IDE 配置

Kiro 是 AWS 出的 AI IDE。它本身不支持改 Base URL，但可以在它的内置终端里用 Claude Code。

在 Kiro 内置终端里运行 claude（前提是你按上面 Claude Code 教程配好了环境变量或 settings.json）。

Windsurf 配置

Windsurf（原 Codeium）原生不支持自定义 API，需要装 Roo Code 扩展来接入 Rivo。步骤见 Roo Code 配置。

Cline 配置

Cline 是 VS Code 上很火的 AI 编程扩展。

Roo Code 配置

Roo Code（原 Roo Cline）是 VS Code / Cursor / Windsurf 通用的 AI 扩展。

Continue.dev 配置

Continue 是 VS Code / JetBrains 的开源 AI 编程扩展。

安装后点 ⚙️ 打开 config.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 配置

Aider 是终端 AI 结对编程工具。

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

然后用 openai/ 前缀跑：

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

OpenCode 配置

OpenCode 是终端 TUI AI 编程工具。

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

或者直接编辑配置文件 ~/.config/opencode/opencode.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 配置

OpenClaw 是可自部署的 AI 助手网关，能接 WhatsApp、Telegram、Slack 等。

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

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

openclaw onboard

openclaw doctor && openclaw status && openclaw dashboard

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

编辑 ~/.openclaw/openclaw.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" }
        ]
      }
    }
  }
}

Cherry Studio 配置

Cherry Studio 是多模型 AI 桌面客户端，支持 Windows / macOS / Linux。

ChatBox 配置

ChatBox 多平台 AI 桌面客户端。

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

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

Open WebUI 配置

Open WebUI 自部署 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 配置

LobeChat 开源 AI 聊天框架。

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

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

点 检查 按钮验证。

NextChat 配置

NextChat（ChatGPT Next Web）开源 Web 聊天客户端。

左下角 设置：

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

沉浸式翻译 配置

沉浸式翻译 浏览器翻译扩展。

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

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

OpenAI SDK 接入

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

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

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 || '');
}

环境变量配置（通用）

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

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

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

Anthropic 兼容工具（Claude Code 等）

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

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

Windows（PowerShell 永久设置）

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

支持的模型

下面是主推模型，完整列表在控制台的模型价格页面。

Claude 系列（Anthropic）

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

原生模型名：

GPT 系列（OpenAI）

Gemini 系列（Google）

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

错误排查

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

连接类问题实战案例（一直重试 / 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。

常见问题

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 顶掉了——见错误排查·案例一。

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/*