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

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

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

站点地址：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：以各自官方文档为准（字段多年未变，仍建议对照一次当前版本）

八、Wan 3.0 视频生成#

接口与模型#

新接入请使用 /v1/videos。旧的 /v1/video/generations 只作为已有客户端的创建兼容入口；查询统一使用 /v1/videos/{id}。

支持的模型：

• wan3.0-video
• wan3.0-video-prime

先用 /v1/models 确认当前密钥能看到目标模型。模型不可见时，检查密钥的分组和模型限制；当前生产环境通常通过「生视频」分组提供这两款模型。

创建任务#

curl -sS https://www.yotopivot.top/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -d '{
    "model": "wan3.0-video",
    "prompt": "a red paper lantern rising in snowy night",
    "size": "16:9",
    "seconds": "5"
  }'

需要保留创建请求编号时，给 curl 增加 -D response-headers.txt，并在成功或失败时从该文件提取 X-Oneapi-Request-Id。创建 POST 不要配置自动重试。

成功时返回 HTTP 200。关键字段示例：

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "wan3.0-video",
  "status": "queued",
  "progress": 0,
  "created_at": 1791590000
}

保存并使用 id。task_id 是旧客户端兼容字段，当前与 id 相同；创建响应目前不保证回填 seconds 和 size。

请求参数#

size 支持两类取值：

当前公开兼容参数中，size 一次只表达分辨率或画幅之一。不要依赖未在本文列出的 metadata 或供应商原生字段来同时强制指定两者。

时长请按示例使用字符串整数，例如 "seconds":"5"。自动时长 -1 不受支持。

查询状态#

curl -sS https://www.yotopivot.top/v1/videos/<TASK_ID> \
  -H "Authorization: Bearer sk-xxxxxxxx"

建议每 10 至 15 秒查询一次，并在连续网络错误或 429/5xx 时采用指数退避。任务创建成功后只轮询原 id，不要重复提交同一个生成请求。

完成响应的关键字段示例：

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "wan3.0-video",
  "status": "completed",
  "progress": 100,
  "created_at": 1791590000,
  "completed_at": 1791590120
}

是否完成只看 status，不要用 completed_at 推断任务终态。响应还可能包含 metadata；下载时使用本站 /content 接口，不要依赖其中的临时结果地址。

下载视频#

仅在状态为 completed 后下载：

curl -sS https://www.yotopivot.top/v1/videos/<TASK_ID>/content \
  -H "Authorization: Bearer sk-xxxxxxxx" \
  -o output.mp4

成功时当前接口返回 HTTP 200 和完整视频内容。任务尚未完成时返回 400；任务不存在或不属于当前用户时返回 404。

当前公开契约不保证 HTTP Range 请求或 206 Partial Content。需要断点续传的客户端应先按普通完整下载处理。

价格#

以下为基础价格，按生成秒数计费：

分辨率倍率分别为 1、2、4。上面的 16:9 示例使用默认 480P，所以 5 秒 wan3.0-video 的基础费用是 ¥1.50，5 秒 wan3.0-video-prime 是 ¥2.25。

账号或分组折扣可能影响实际结算金额。最终费用以模型广场、任务记录和使用日志显示为准。

错误与重试#

任务处理错误通常使用顶层字段：

{
  "code": "invalid_request",
  "message": "wan3.0 video duration must be between 2 and 30 seconds; automatic duration is not supported",
  "data": null
}

鉴权、路由和下载阶段的错误通常使用 OpenAI 风格的包裹结构：

{
  "error": {
    "code": "model_not_found",
    "message": "No available channel for model wan3.0-video under the current group",
    "type": "new_api_error"
  }
}

错误外形取决于失败发生的层级，创建或查询请求也可能返回第二种结构。客户端应先判断 HTTP 状态码；业务错误码读取 code 或 error.code，错误消息读取 message 或 error.message。

创建请求没有在本文中承诺幂等键。收到任务 ID 后再次发送 POST 可能产生第二个任务和第二笔费用。如果创建响应在网络中丢失，请先用已保存响应头中的 X-Oneapi-Request-Id 查询使用日志，确认是否已经创建任务；如果连响应头都没有收到，请按调用时间、模型名和当前密钥对应的使用日志核对。

当前只承诺已经验证的文生视频流程。不要依赖真实图生视频、多参考图、自动时长 -1、完整原生参数透传、同时强制指定分辨率和画幅，或 Range / 206 分段下载；这些能力完成单独适配和验收后会再更新文档。

九、Seedance 2.x 视频生成#

本章包含 Seedance 2.0 和 2.5 的完整调用说明、请求参数、参考素材、查询下载、价格与错误处理，也可阅读独立文档页。

本文说明如何在曜智枢调用 Seedance 2.0 和 2.5，完成文生视频、参考素材生成、查询及下载。请使用有「生视频」分组权限的站内 API 密钥；模型权限以当前密钥的 /v1/models 返回结果为准。

Seedance 基本信息#

使用本站控制台创建的站内 API 密钥。视频任务为异步处理：创建得到任务 ID，再查询状态，完成后下载。

调用前可用 GET /v1/models 核对当前密钥是否有权访问模型。工作流页面的时长、分辨率及参考附件选项可能少于 API 支持范围；以下以直接调用 API 为准。

Seedance 创建文生视频任务#

先使用 5 秒、720p 开始测试。以下为 Bash / curl 示例：

curl -sS https://www.yotopivot.top/v1/videos \
  -H "Authorization: Bearer <YOTOPIVOT_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedance-2-0-260128",
    "prompt": "海边悬崖，夕阳落入海平面，镜头缓慢向前推进，电影感",
    "duration": 5,
    "size": "720p",
    "metadata": {
      "ratio": "16:9",
      "generate_audio": false
    }
  }'

成功响应的关键字段示例：

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "doubao-seedance-2-0-260128",
  "status": "queued",
  "progress": 0
}

保存响应中的公开 id，后续查询和下载均使用它。不要根据 ID 的外形拼接其他接口地址。

Seedance 请求参数#

Seedance 统一格式#

建议时长为 4–15 秒，这不是保证所有模型均接受的硬性范围。本站接口接受 1–3600 秒的正整数，具体模型仍可能拒绝不支持的时长；首次测试推荐 5 秒。-1 等自动时长写法不受支持。

Seedance 的 size 表示分辨率，画幅单独放在 metadata.ratio。不要把 Wan 的 "size":"16:9" 写法直接用于这两款模型。768P 会兼容转换为 720p；Seedance 2.5 的 4k 请求会在提交前被拒绝。

Seedance 内容数组格式#

也可把 content、resolution、ratio、generate_audio 等参数直接放在顶层。下面的纯文本请求与前面的统一格式等价：

{
  "model": "doubao-seedance-2-0-260128",
  "content": [
    {"type": "text", "text": "海边悬崖，夕阳落入海平面，镜头缓慢向前推进，电影感"}
  ],
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9",
  "generate_audio": false
}

每个请求选用一种格式更容易排查。混用时，prompt 优先于 content 内的文本；size 优先于 resolution；duration 优先于 seconds。顶层内容参数优先于 metadata 内同名字段。省略 prompt 时，content 至少要含一项非空文本。

Seedance 使用参考图片、视频和音频#

参考素材必须是可公开读取的 HTTP(S) 地址，或由管理员提供且适用于当前服务的 asset://asset-... 素材 ID。URL 在任务处理期间应持续有效。当前不接受本地文件上传、文件路径或 data: / Base64 URI。

{
  "model": "doubao-seedance-2-5-260628",
  "prompt": "参考图片中的场景与视频中的镜头运动，生成一段自然连贯的短片",
  "duration": 5,
  "size": "720p",
  "metadata": {
    "ratio": "16:9",
    "generate_audio": true,
    "content": [
      {
        "type": "image_url",
        "image_url": {"url": "https://your-public-cdn.example/scene.png"},
        "role": "reference_image"
      },
      {
        "type": "video_url",
        "video_url": {"url": "https://your-public-cdn.example/motion.mp4"},
        "role": "reference_video"
      }
    ]
  }
}

示例素材域名为占位地址，调用时请换成实际可读取的素材 URL。

每项只能包含一个与 type 对应的媒体字段。省略 role 时自动使用该素材类型的 reference_* 角色。使用 asset:// 时仅将相应 URL 值替换为管理员提供的素材 ID；本站尚未开放素材库创建或管理接口。

Seedance 查询状态#

curl -sS "https://www.yotopivot.top/v1/videos/<TASK_ID>" \
  -H "Authorization: Bearer <YOTOPIVOT_API_KEY>"

建议每 5–10 秒查询一次。遇到 429、网络错误或 5xx 时增加间隔并采用指数退避。查询使用创建任务的同一用户身份；收到任务 ID 后，只查询原任务，不要反复发送创建请求。

完成响应的关键字段示例：

{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "doubao-seedance-2-0-260128",
  "status": "completed",
  "progress": 100
}

以 status 判断是否完成，其他时间或进度字段不能替代终态。任务响应可能包含临时结果地址；请使用下面的本站下载接口。

Seedance 下载视频#

仅在任务状态为 completed 后调用：

curl -sS "https://www.yotopivot.top/v1/videos/<TASK_ID>/content" \
  -H "Authorization: Bearer <YOTOPIVOT_API_KEY>" \
  -o output.mp4

视频结果地址有有效期，生成后请及时下载并自行保存。本站下载接口不表示永久保存视频。当前不保证 HTTP Range 或 206 Partial Content，客户端应按完整下载处理。

Seedance 价格#

标准价格如下表，单位均为人民币 / 百万 token。表中「有视频输入」指请求包含参考视频；参考图片、参考音频或开启音频生成不会单独改变这个价阶。

Seedance 2.5 不支持 4k。表中为分组倍率 1 的基础价；账号或分组折扣以模型广场和实际结算记录为准。

任务创建时会按模型、分辨率、时长及是否含参考视频估算并预扣额度。完成后使用实际 usage.total_tokens 多退少补；失败任务按任务退款流程退回预扣额度。

token 数大致随画面像素数、24 fps 和计费时长增加。有视频输入时计费时长包含输入与输出视频；预扣无法得知实际输入时长时，先按与输出相同时长估算。画幅、实际素材时长及额外帧会影响最终用量，所以「每秒价格」不是固定值。

例如无视频输入的 720p、16:9、5 秒视频，基础估算约为 108,000 token：2.0 约 ¥4.968，2.5 约 ¥7.56。以上仅用于理解价格，不是固定任务报价，最终请以本站任务记录和使用日志为准；账号或分组折扣也可能影响实际金额。

Seedance 错误与重试#

客户端应同时处理顶层 code / message 与 error.code / error.message 两类错误结构，并首先判断 HTTP 状态码。

创建接口未承诺幂等键。若创建响应丢失，盲目重发可能产生额外任务及费用。先用响应头中的 X-Oneapi-Request-Id 核对使用日志；未收到响应头时，按调用时间、模型名和当前密钥的记录核对。

需要反馈时提供公开任务 ID、请求编号、调用时间和脱敏请求参数，请勿发送完整 API 密钥。

十、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 位」即可。