曜智枢 中转服务使用指南#

本文面向使用曜智枢 API 中转服务的用户：把曜智枢当作一个兼容 OpenAI / Claude / Gemini 协议的模型接口地址，接入自己的客户端、插件或代码。

阅读顺序建议：只想尽快跑通，看第一章；要接入工具，看第六章；要接 Agent，看第七章；报错不清楚原因，直接查第九章和第十章。

站点地址：https://www.yotopivot.top 本文只写接口怎么调。模型名称、可用范围与账号额度请在站内的「模型广场」和「控制台」查看。

一、五分钟快速开始#

第 1 步：注册并登录#

1. 打开 https://www.yotopivot.top。
2. 注册账号：填写用户名、密码、邮箱，并在邮箱验证码一栏点击发送验证码，填入收到的验证码完成注册。
3. 注册后登录，进入控制台。

第 2 步：创建 API 密钥#

1. 在控制台左侧进入「API 密钥」（地址 https://www.yotopivot.top/keys）。
2. 点击新建密钥，填写名称，按需设置分组、模型限制、IP 白名单、过期时间与额度，保存。
3. 在列表里点该条目的「复制密钥」，得到形如 sk-xxxxxxxx... 的密钥；点「复制连接信息」可以一次拿到接口地址与密钥。

密钥只在创建时方便复制，请立即保存。一个应用配一枚密钥，出问题可以单独禁用，不必影响其他工具。

第 3 步：接进你用的工具#

先分清你是哪一类，两条路的做法不一样：

• 图形客户端（Cherry Studio、Chatbox、NextChat、沉浸式翻译、Cursor 等）：自己填「接口地址 + 密钥」两项，见下面。
• 命令行工具（Claude Code、Codex、Gemini CLI）：不用手抄，直接在「API 密钥」页对着目标密钥点「CC Switch」一键写入，细节见第六章第 1 节。

图形客户端只需要填两样东西：

不管走哪条路，都建议先用命令行确认密钥可用（把 sk-xxxxxxxx 换成你的密钥）：

curl https://www.yotopivot.top/v1/models \
  -H "Authorization: Bearer sk-xxxxxxxx"

返回里 data 数组就是这枚密钥当前可以调用的模型名。接着发一条最小的对话请求（把 模型名 换成返回列表里的任意一个）：

curl https://www.yotopivot.top/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "模型名",
    "messages": [{"role": "user", "content": "你好"}]
  }'

能拿到正常回答，说明这一章已经完成，后面按需选读。

二、API 基本信息#

服务地址#

客户端里通常要求填「Base URL / 接口地址」，填到 /v1 为止；少数插件要求填完整的请求地址，这时要带上具体端点，例如 https://www.yotopivot.top/v1/chat/completions。

鉴权方式#

所有中转接口都需要 API 密钥，支持以下几种写法：

密钥被当作敏感信息处理：不要写进会公开的代码仓库、前端页面或截图里。

响应头与请求追踪#

每个响应都会带一个请求编号：

X-Oneapi-Request-Id: 202609200202124569850508268d9d6Ub6AWfdu

报错时，响应体里的 message 也会带上同一个编号，例如 ... (request id: 2026092...Ub6AWfdu)。反馈问题时把这个编号一起贴上，能最快定位到具体那一次请求。

关于报错语言#

同一类错误，服务端会按客户端声明的语言返回中文或英文文案，例如密钥无效在中文环境下是「无效的令牌」，在英文环境（或未声明语言，如大多数 curl 默认请求）下是 Invalid token。判断错误请以 HTTP 状态码 + 错误码 为主，文案仅作参考。

三、支持的接口#

OpenAI 兼容#

Claude 兼容#

Gemini 兼容#

任务类#

绘画与音乐属于异步任务型接口，提交后需要再查询结果：

暂不支持#

以下端点会返回「接口未实现」，请不要在客户端里配置：

• POST /v1/images/variations
• GET /v1/files、POST /v1/files、GET /v1/files/{id}、GET /v1/files/{id}/content、DELETE /v1/files/{id}
• POST /v1/fine-tunes、GET /v1/fine-tunes、GET /v1/fine-tunes/{id}、POST /v1/fine-tunes/{id}/cancel、GET /v1/fine-tunes/{id}/events
• DELETE /v1/models/{模型名}

四、查询可用模型#

不要凭记忆猜模型名，直接问接口：

curl https://www.yotopivot.top/v1/models \
  -H "Authorization: Bearer sk-xxxxxxxx"

返回结构：

{
  "success": true,
  "object": "list",
  "data": [
    {
      "id": "模型名",
      "object": "model",
      "created": 1700000000,
      "owned_by": "...",
      "supported_endpoint_types": ["openai", "openai-response"]
    }
  ]
}

有两点值得注意：

1. 这个列表是「按密钥」算出来的，不是全站模型清单。密钥所属分组、以及密钥自身的模型限制，都会收窄这里的结果。
2. supported_endpoint_types 表示该模型支持哪些调用形式，客户端里选错端点类型会报模型不可用；以它为准，不要硬套。

站内的「模型广场」（https://www.yotopivot.top/pricing）可以按模型查看说明与调用示例，点进任意模型详情即可看到可直接复制的 cURL、Python、TypeScript、JavaScript 片段。

模型规格以 Codex 客户端为准#

本站的 ChatGPT / Codex 系列模型是把 Codex 客户端的链路反代出来的，不是官方 API 直连。所以涉及模型规格时，请对照 Codex 客户端，而不是 OpenAI 官方 API 文档——尤其是上下文长度：

在客户端或代码里照抄官方 API 的数字来配上下文预算，很容易和实际可用长度对不上；拿不准时以上表为准，表里没列出的模型可在「模型广场」看该模型的说明，或直接咨询站点管理员。

五、API 密钥与分组#

API 密钥上可以设置什么#

创建密钥时可配置的字段，对应到实际行为：

API 密钥页的常用操作#

在「API 密钥」页每一行的操作菜单里可以：

• 复制密钥：拿到 sk- 开头的完整密钥。
• 复制连接信息：一次拿到接口地址与密钥，方便粘贴到客户端。
• Chat / 一键导入：把地址和密钥直接推送到本机已安装的客户端，免手填。当前支持 Cherry Studio、AionUI、DeepChat、Lobe Chat、AI as Workspace、AMA 问天、OpenCat、流畅阅读、CC Switch 等。
• 启用 / 禁用：临时停用某枚密钥，不必删除。
• 编辑、删除：调整配置或彻底作废。

推荐做法#

• 一个工具 / 一个项目用一枚密钥，命名写清用途（例如「公司服务器-报表脚本」）。
• 只在明确需要时打开模型限制与 IP 白名单；限制越严，排查越容易。
• 密钥疑似泄露时，直接禁用该密钥再新建一枚，不要继续使用旧密钥。

六、客户端配置教程#

以下每个客户端的通用逻辑都一样：接口地址填 https://www.yotopivot.top/v1，API 密钥填你在控制台创建的那串 sk- 密钥，模型名从 /v1/models 的返回里挑。不同版本界面用词略有差异，以你当前版本为准。

0. 先试站内一键导入#

在控制台「API 密钥」页对应密钥的操作菜单里选择「Chat」，如果本机装了受支持的客户端，会直接拉起并写入地址与密钥，省去手填。一键导入失败时，按下面的手动方式配置。

同一个操作菜单里还有另一个入口「CC Switch」，服务的是 Claude Code / Codex / Gemini 这类命令行工具——两条路径分工不同：图形客户端走「Chat」，命令行工具走「CC Switch」。

「Chat」子菜单当前支持的客户端，以及自动导入失败时手动该怎么填：

表里带链接的都是各客户端的官方站点或发布页；AMA 问天目前没有稳定的公开下载页，用站内一键导入即可。

下面详细写的 Cherry Studio、Chatbox、NextChat、沉浸式翻译、Cursor / Cline、Claude Code，是使用量最大、也最容易填错地址的几款；其余客户端按上表填写即可，界面用词以你当前版本为准。

1. CC Switch（Claude Code / Codex / Gemini 一键写入）#

如果你用 Claude Code、Codex 或 Gemini 这类命令行工具，这是最省事的一条路：站内直接生成配置并拉起 CC Switch 导入，不用手抄地址和密钥。

• 下载：CC Switch 发布页，装到本机。

• 配置（推荐走站内一键写入）：

  1. 控制台「API 密钥」页 → 目标密钥的操作菜单 → 选「CC Switch」，打开导入弹窗；
  2. 选择应用：Claude / Codex / Gemini；
  3. 填名称（默认 My Claude、My Codex、My Gemini）；
  4. 选模型：主模型必填；选 Claude 时还可以分别指定 Haiku / Sonnet / Opus 使用的模型，留空则跟随默认；
  5. 点「打开 CC Switch」，浏览器会请求打开 ccswitch:// 链接，允许后 CC Switch 会写入该供应商；
  6. 回到 CC Switch 启用并切换到刚导入的供应商，再启动 Claude Code / Codex。

• 手动配置时对应的值（自动导入失败时用，注意两种地址写法不同）：

  应用	接口地址
  Claude	https://www.yotopivot.top（不带 /v1）
  Gemini	https://www.yotopivot.top（不带 /v1）
  Codex	https://www.yotopivot.top/v1（要带 /v1）

• 易错点：模型下拉里只列你账号当前可用的模型，密钥开了模型限制就只列允许的那些；没装 CC Switch 时链接点不开；浏览器询问「是否允许打开外部应用」时要选允许。

2. Cherry Studio#

• 下载：Cherry Studio 官网（或 GitHub 发布页）。
• 配置：设置 → 模型服务 → 添加服务商，类型选 OpenAI 兼容；API 地址填 https://www.yotopivot.top/v1，API 密钥填你的密钥；在「模型」里手动添加你要用的模型名。
• 易错点：地址末尾是否少了 / 多了 /v1——只有一处 /v1；添加完模型后要回聊天界面把默认模型切换过去。

3. Chatbox#

• 下载：Chatbox 官网（或 GitHub 发布页）。
• 配置：设置 → 模型 → 添加自定义提供方（OpenAI API 兼容），API 域名填 https://www.yotopivot.top，API 路径保留 /v1/chat/completions，API 密钥填你的密钥，模型名手动填写。
• 易错点：Chatbox 把「域名」和「路径」分开填，域名里不要再带 /v1，否则会拼成 /v1/v1/...。

4. NextChat#

• 下载：NextChat 发布页。
• 配置：设置 → 自定义接口，接口地址填 https://www.yotopivot.top，API Key 填你的密钥，模型列表里填入你要用的模型名（可多行），勾选自定义模型。
• 易错点：NextChat 会自己补 /v1/chat/completions，所以接口地址只填到域名。

5. 沉浸式翻译#

• 下载：沉浸式翻译官网，或直接在浏览器扩展商店搜索安装。
• 配置：设置 → 翻译服务 → 选择 OpenAI 或「自定义 AI 翻译服务」，API 地址填完整端点 https://www.yotopivot.top/v1/chat/completions，密钥填你的密钥，模型名填可用的对话模型。
• 易错点：该类插件通常要求完整请求地址，只填域名或只填 /v1 都会失败；另外翻译会高频发请求，建议单独建一枚密钥并适当放宽限流。

6. 编码类工具（Agent）#

Cursor、Cline 这类能读写代码、自己跑命令的工具单独成章，见第七章；Claude Code、Codex CLI、Gemini CLI 等命令行工具也在那一章。

七、主流 Agent 接入#

这一章讲的是能自己读写代码、执行任务的工具（Agent）：既有带界面的桌面应用与编辑器插件，也有跑在终端里的命令行工具。每个工具的写法定死为「安装 → 配置 → 验证 → 易错点」，配置字段都对照各自的官方文档核对过（来源列在本章末尾）。

先按协议对号入座，再跳到对应小节：

先提醒一句：Agent 会自己发起多轮请求、带上长上下文，额度与限流消耗远高于聊天。建议一个 Agent 配一枚密钥（见第五章），并在密钥上打开模型限制，避免它误用高价模型。

7.1 带界面的 Agent#

7.1.1 DeepSeek Harness（dsh，DeepSeek 官方开源）#

dsh 是 DeepSeek 官方开源的 Agent 执行框架，跑在你自己机器上，通过浏览器里的控制台操作。

• 安装与启动（一行命令拉起本地 Web 控制台）：

npx @deepseek-ai/dsh web

• 配置：打开命令行提示的本地地址进入控制台 → 左下角 Settings（设置） → Providers（模型提供商） → 服务商选择「自定义兼容端点」→ 填入 Base URL https://www.yotopivot.top/v1 与你的密钥，保存后把默认模型切到从 /v1/models 查到的名字。
• 验证：让它做一件只读的小事（例如「列出当前目录有哪些文件」），能正常返回就说明通了。
• 易错点：服务在本机运行，但模型调用要联网；官方文档明确「自定义兼容端点」适用于自建转发网关这类场景，所以填本站地址是它的正规用法，不需要改任何系统设置。

7.1.2 ZCode（智谱，桌面应用）#

• 下载与文档：zcode.z.ai，连接模型的说明见 官方文档。

• 配置：进入「连接模型」→ 选择「使用 API Key」→ 在供应商页切到 API Key 模式，会出现两个地址字段：

  字段	填什么
  OpenAI 接口地址	https://www.yotopivot.top/v1
  Anthropic 接口地址	https://www.yotopivot.top

  两个字段都用同一枚 sk- 开头的密钥，然后选一个站内可用的模型。

• 说明：ZCode 官方文档明确支持「第三方供应商：接入兼容 Anthropic / OpenAI 协议的模型服务，包括团队自建通道」，所以这是它设计内的用法。

• 易错点：两个地址字段要分别填，Anthropic 那一栏不要带 /v1。

7.1.3 Trae#

• 下载：见 Trae 官网（字节跳动的 AI IDE）。
• 配置：设置 → 模型 → 添加自定义模型，协议选 OpenAI 兼容；Trae 要求填完整接口地址，填 https://www.yotopivot.top/v1/chat/completions，密钥填你的 sk- 密钥，模型名手填。
• 验证：新建对话问一句，有正常回答即可。
• 易错点：不同版本对地址的容忍度不同——如果界面提示只能填到 /v1，就改成 https://www.yotopivot.top/v1；以你当前版本的界面提示为准。

7.1.4 Cursor#

• 下载：cursor.com。
• 配置：设置 → Models → 填入 API Key，并打开 Override OpenAI Base URL，填 https://www.yotopivot.top/v1；随后关闭不需要的官方模型开关，在自定义模型里添加你要用的模型名。
• 验证：新建一个对话问一句，能返回即成功。
• 易错点：官方模型开关不关掉的话，部分请求仍会走官方通道，看起来像「配置没生效」。

7.1.5 Cline / Roo Code#

• 下载：Cline 见 cline.bot（或 GitHub 发布页）；Roo Code 见其官网或编辑器插件市场。
• 配置（两者一致）：在设置里把 API Provider 选为 OpenAI Compatible，Base URL 填 https://www.yotopivot.top/v1，API Key 填你的密钥，Model ID 手动填写模型名。
• 验证：让它读取项目里的一个文件。
• 易错点：这类工具默认会自动执行命令，第一次接入建议在只读目录或测试项目里验证，确认无误再放到工作目录。

7.1.6 Continue#

• 下载与文档：见 Continue 官方站点。
• 配置：在模型配置里新增一个 OpenAI 兼容模型，Base URL 指向 https://www.yotopivot.top/v1，填入 API Key 与模型名。
• 易错点：Continue 的配置文件格式在版本之间调整过，字段名以你当前版本的官方文档为准；改完记得重载窗口。

7.2 命令行 Agent#

7.2.1 Codex CLI（Responses 协议）#

本站的 ChatGPT / Codex 系列本身就是 Codex 链路，所以 Codex CLI 属于「原生对口」的用法。

• 安装：按 Codex 官方方式安装 CLI。
• 编辑 ~/.codex/config.toml：

model_provider = "yotopivot"
model = "模型名"
disable_response_storage = true

[model_providers.yotopivot]
name = "YOTOPIVOT"
base_url = "https://www.yotopivot.top/v1"
wire_api = "responses"
requires_openai_auth = false
env_key = "YOTOPIVOT_API_KEY"

• 填密钥（二选一）：设置环境变量 YOTOPIVOT_API_KEY=sk-xxxxxxxx；或把 experimental_bearer_token = "sk-xxxxxxxx" 直接写进上面的 [model_providers.yotopivot] 段。
• 验证：进入 codex 后随便问一句，或用 codex exec "列出当前目录" 跑一次性任务。
• 易错点：
  • wire_api 必须是 responses——本站的 Codex 链路走 Responses 协议；
  • disable_response_storage = true 建议保留，否则可能因为上游不保存响应而报错；
  • 自定义 provider 的名字不能占用保留 id（openai、ollama、lmstudio）；
  • 上下文长度按第四章的说明算，不要照抄官方 API 文档。

7.2.2 Claude Code（Claude 协议）#

• 下载：见 Claude Code 官方页。
• 配置：它走 Claude 协议（/v1/messages），通过环境变量改指向：

export ANTHROPIC_BASE_URL="https://www.yotopivot.top"
export ANTHROPIC_AUTH_TOKEN="sk-xxxxxxxx"
export ANTHROPIC_MODEL="模型名"

Windows PowerShell：

$env:ANTHROPIC_BASE_URL = "https://www.yotopivot.top"
$env:ANTHROPIC_AUTH_TOKEN = "sk-xxxxxxxx"
$env:ANTHROPIC_MODEL = "模型名"

• 验证：启动后问一句，能正常回答即可。
• 易错点：ANTHROPIC_BASE_URL 只到域名，不要带 /v1（客户端会自己拼 /v1/messages）；模型名必须能在 /v1/models 里查到，否则会报模型不可用。

7.2.3 Gemini CLI（Gemini 协议）#

• 安装：按 Gemini CLI 官方方式安装（Node.js 环境）。
• 配置：编辑 ~/.gemini/settings.json，把接口地址指向本站、并填入密钥：

{
  "baseUrl": "https://www.yotopivot.top",
  "apiKey": "sk-xxxxxxxx"
}

也可以改用环境变量提供密钥：GEMINI_API_KEY=sk-xxxxxxxx。

• 验证：运行 gemini "你好"，能返回即成功。
• 易错点：本站的 Gemini 协议端点在 /v1beta 下，所以 baseUrl 只填域名、不要填 /v1；地址末尾也不要多写斜杠。

7.2.4 Qwen Code#

• 安装：按 Qwen Code 官方文档安装（npm 全局包）。
• 配置：官方给出的环境变量写法：

export OPENAI_BASE_URL="https://www.yotopivot.top/v1"
export OPENAI_API_KEY="sk-xxxxxxxx"
export OPENAI_MODEL="模型名"

也可以写进 ~/.qwen/settings.json 的 provider 条目（baseUrl + envKey），效果一致。

• 验证：启动 qwen 问一句。
• 易错点：OPENAI_BASE_URL 要带 /v1；OPENAI_MODEL 必须是 /v1/models 里查得到的名字。

7.2.5 iFlow CLI#

• 安装：按 iFlow CLI 仓库 的说明安装。
• 配置：官方说明原文是「iFlow CLI can connect to any OpenAI-compatible API」，改配置文件 ~/.iflow/settings.json 即可——首次运行会自动生成该文件，把其中的模型服务地址改成 https://www.yotopivot.top/v1，密钥填你的 sk- 密钥。
• 验证：启动后让它读一个文件或问一句。
• 易错点：settings.json 是 JSON 格式，改完注意不要留下多余的逗号，否则启动会直接报解析错误。

7.2.6 Kimi Code CLI#

• 安装：按 Kimi Code CLI 官方文档安装。
• 配置：编辑配置文件 config.toml，新增一个 provider 与对应模型（官方支持 kimi / anthropic / openai / openai_responses 四种协议类型）：

[providers.yotopivot]
type = "openai"
base_url = "https://www.yotopivot.top/v1"
api_key = "sk-xxxxxxxx"

[models."模型名"]
provider = "yotopivot"
model = "模型名"
max_context_size = 400000

• 说明：接站内的普通对话模型用 type = "openai"；如果要走 Claude 协议，把 type 换成 "anthropic" 并把 base_url 改成 https://www.yotopivot.top（不带 /v1）。
• 验证：启动后问一句，或让它读一个文件。
• 易错点：max_context_size 按本站实际填写（见第四章），填太大会被上游截断；type 与 base_url 的写法必须匹配。

7.3 暂未确认支持自定义端点的工具#

下面这些工具在官方文档里没有找到自定义 Base URL / 第三方端点的配置项（核对日期见文末），目前建议直接使用它们的官方账号。如果你在官方文档里找到了接入方式，欢迎反馈给我们补充：

7.4 Agent 场景的常见问题#

• 频繁 429：Agent 一轮任务会连发很多请求，比聊天更容易触发限流；降低并发、放慢节奏，或把任务拆小。
• 上下文长度：按第四章的口径算，别照抄官方 API 文档的数字。
• 工具调用与推理参数报错：不同 Agent 会下发各自的工具定义和推理参数，上游不支持的部分可能报错或被忽略；反馈时把 X-Oneapi-Request-Id 一起贴上。
• 额度消耗异常：先看「使用日志」里是哪个模型在跑；一个 Agent 一枚密钥能让这类问题一眼定位。
• 先验证密钥再配 Agent：按第一章第 3 步用 curl 确认密钥和模型可用，再配 Agent——一旦出问题，就能立刻分清是密钥、模型还是 Agent 配置的问题。

本章配置字段的官方依据#

• Codex 自定义模型提供商：https://learn.chatgpt.com/docs/config-file/config-advanced#custom-model-providers
• DeepSeek Harness 快速开始：https://deepseekharness.wiki/tutorials/quickstart
• ZCode 连接模型：https://zcode.z.ai/cn/docs/configuration
• Qwen Code 配置：https://qwenlm.github.io/qwen-code-docs/zh/users/configuration/settings/
• iFlow CLI 仓库说明：https://github.com/iflow-ai/iflow-cli
• Kimi Code CLI 平台与模型：https://moonshotai.github.io/kimi-code/zh/configuration/providers.html
• Claude Code / Gemini CLI：以各自官方文档为准（字段多年未变，仍建议对照一次当前版本）

八、SDK 与 curl 示例#

curl（非流式）#

curl https://www.yotopivot.top/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "模型名",
    "messages": [
      {"role": "system", "content": "你是一个简洁的助手"},
      {"role": "user", "content": "用三句话解释什么是 API 中转"}
    ],
    "temperature": 0.7
  }'

curl（流式）#

在请求体里加 "stream": true：

curl -N https://www.yotopivot.top/v1/chat/completions \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "模型名",
    "messages": [{"role": "user", "content": "数到十"}],
    "stream": true
  }'

返回是 SSE 流，每行以 data: 开头，最后以 data: [DONE] 结束。

Python（OpenAI 官方 SDK）#

from openai import OpenAI

client = OpenAI(
    base_url="https://www.yotopivot.top/v1",
    api_key="sk-xxxxxxxx",
)

resp = client.chat.completions.create(
    model="模型名",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

流式读取：

stream = client.chat.completions.create(
    model="模型名",
    messages=[{"role": "user", "content": "数到十"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Node / TypeScript（OpenAI 官方 SDK）#

import OpenAI from 'openai'

const client = new OpenAI({
  baseURL: 'https://www.yotopivot.top/v1',
  apiKey: 'sk-xxxxxxxx',
})

const resp = await client.chat.completions.create({
  model: '模型名',
  messages: [{ role: 'user', content: '你好' }],
})
console.log(resp.choices[0].message.content)

只要兼容 OpenAI，就在这两处填对#

绝大多数第三方库 / 框架只需两个设置：

base_url = https://www.yotopivot.top/v1     # 注意结尾的 /v1
api_key  = sk-xxxxxxxx                      # 你的密钥

模型名不要用示例里的占位符，先从 /v1/models 里选。

九、错误响应与错误码#

响应结构#

曜智枢自身拦截产生的错误是 OpenAI 风格的结构：

{
  "error": {
    "message": "无效的令牌 (request id: 202609200202124569850508268d9d6Ub6AWfdu)",
    "type": "new_api_error",
    "code": "insufficient_user_quota"
  }
}

• message：给人看的说明，末尾通常带请求编号。
• type：new_api_error 表示由中转站拦截；模型上游直接返回的错误可能原样透传，出现 openai_error、claude_error、gemini_error 等类型。
• code：机器可读的错误码。部分错误的 code 是空字符串，此时请结合 HTTP 状态码与 message 判断。

常见错误码速查#

其他状态码#

500 / 502 / 503 还有一类是上游模型服务的临时故障，表现为调用一个本来正常的模型突然失败。这类错误通常重试即可恢复；如果连续多次失败，按第十章的模板反馈。

十、常见问题排查#

按状态码定位

• 401：99% 是密钥问题。重新「复制密钥」，确认没有多空格、没有混进引号或换行，确认密钥是启用状态。
• 403：先分清三种——账号被封禁、IP 不在白名单、密钥无权访问该模型或分组。提示文案会明确写出来。
• 404：多半是地址拼错。常见错误是客户端里填了 https://www.yotopivot.top/v1/v1，或反过来只填了域名而客户端不自动补 /v1。
• 429：等一会儿再试；批量脚本请改串行或加指数退避。失败请求也会占用总请求数配额，先把必然失败的请求修好。

流式输出中断

先确认客户端支持 SSE，并且没有代理或网关缓冲响应。若用的是自建反向代理，需要关闭对 text/event-stream 的缓冲。

图片生成失败

1. 确认模型本身支持生图（在模型广场看该模型的说明与端点类型）；
2. 确认调的是 /v1/images/generations 或 /v1/images/edits，不是对话端点；
3. 若提示渠道未授权图片生成能力，说明当前分组没有生图渠道，换分组或换模型。

提示内容被拦截

提示词或生成结果触发上游安全策略时会被拦截，对应错误码可能为 prompt_blocked 或 sensitive_words_detected。调整措辞后重试，不要靠改参数绕过。

想知道自己用了多少

• 控制台「使用日志」（https://www.yotopivot.top/usage-logs/common）可以按时间、模型、密钥筛选每一次请求；
• 「钱包」（https://www.yotopivot.top/wallet）看账号剩余额度；
• 「API 密钥」页看每枚密钥的已用额度与最后调用时间。

十一、获取帮助#

遇到问题请带上以下信息，可以少走几个来回：

1. X-Oneapi-Request-Id（响应头，或错误信息里 request id: 后面那串）；
2. 出现时间（精确到分钟）；
3. 调用的接口路径与模型名；
4. HTTP 状态码与完整错误信息；
5. 使用的客户端或 SDK 名称与版本。

不要在反馈里贴完整密钥；需要核对时说明「密钥前 8 位」即可。