文档目录

常见问题与排障

按「你看到什么 → 原因 → 怎么办」组织:401、402、任务卡住、链接 403、流式不流、中文乱码。

内容最后核对:2026-11-18

本页目录

先看这四条

九成的工单落在这里:

你看到多半是怎么办
401 auth.invalid_keybase 写成 /api/v1,请求被当成了控制台接口base 改 <网关地址>/v1。这类请求不会出现在使用日志里,因为它没有进入模型调用
404 model.not_found模型名抄了别家的,或本站没接GET /v1/models 看真实清单
402 quota.insufficient余额不足充值。不要重试,重试一百次结果一样
503 channel.unavailable这个模型当前没有可用渠道稍后重试;持续出现说明所有上游线路都不通,请联系管理员

报障前先抓一串 X-Request-Id(响应头里也有,request_id 在响应体里也有)。它比任何描述都精确。

鉴权类(401 / 403)

401 auth.key_missing — 没带密钥,或带了但不在认的五个位置里。检查是否把密钥写进了 Authorization 以外的自定义头;也检查中间代理有没有把它剥掉。

401 auth.invalid_key — 密钥不存在、已停用、或签发它的用户被停用。这几种情况报文相同 (不区分是刻意的:区分等于告诉攻击者「这把 key 存在但被停了」)。用户被停用时是 403 auth.account_disabled。

401 auth.key_on_console — 拿 API Key 调了 /api/**。控制台接口要登录后拿到的访问令牌, API Key 只调 /v1/**。两个命名空间不通用。细节在鉴权与密钥。

403 model.disabled — 模型存在但已下架。别改名字,请联系管理员确认是否恢复。

403 auth.account_disabled — 账号被停用。与「密钥被停用」是两件事:换一把新 key 也没用,得找管理员。

余额与计费

为什么余额不足是 402 而不是 400。 SDK 把 4xx 当「你请求错了」,会展示成「改参数重试」; 而 402 的语义是「要钱」,主流 SDK 见到它会停止重试并提示充值。这是唯一一处刻意不用 400 的地方。

reserveQuota 不是扣款。 它是提交时的冻结。看 settleQuota + settleStatus: SETTLED 是按实际结算、RELEASED 是失败全额释放、NONE 是还没结束。

金额怎么换算。 接口里的金额是整数,除以 GET /api/meta 返回的 quota_per_unit 就是金额,再按 balance_display 换成显示货币。这些数都从 /api/meta 取,不要写死。见计费与配额。

账单和上游发票差一点。 文本用上游 usage;上游不回报时按估算。图片按实际返回 张数、视频按实际时长。差得多时贴 X-Request-Id,日志行里有逐项计费明细可以核对。

任务类(视频 / 音乐)

一直 queued。 网关每 5 秒检查一次上游,比它更勤的轮询不会更快。真超过 10 分钟还不动, 看控制台「异步任务」页的 upstreamId:任务可能在上游排队,那不是网关能加速的。

SUBMIT_FAILED(HTTP 502)。 提交阶段就被上游拒绝了,预扣已全额释放。 响应体里有任务 id 与 error.message;按 message 改参数后重提,别原样重试。

LINK_EXPIRED。 生成本身成功了,只是产物链接到期。POST /v1/videos/{id}/refresh-url 换新链接;上游已删产物时会失败,那时只能重新生成。

下载 403。 上游的签名链通常只覆盖 GET(HEAD 会 403)。用 GET 或 GET + Range, 或者直接让我们代理:GET /v1/videos/{id}/content。

failed 但看不出原因。 四个格式的 failed 把七种原因压成了一种。看控制台任务详情里的 failCode / failDetail,或 Sora 形状里的 state 字段。

取消退不退钱。 取决于上游:有的提交即计费、取消不退,有的可退。规则由各家上游自己决定, 不由接口决定。取消后看 settleStatus 确认。

状态映射看不懂。 任务的七个状态与四种格式的对照表在视频 API, 整套异步规则在异步任务。

内容与输入

中文乱码。 请求体没声明 Content-Type: application/json; charset=utf-8,或客户端用 ISO-8859-1 解码了响应。网关自己始终按 UTF-8 输出。

token 超限(400 validation.failed,报文提到 context length)。 模型的最大上下文是上游的 硬限制,网关不截断(截断会让输出看起来「莫名其妙少了一段」)。自己裁历史消息。

工具调用(tools)在某些模型上不生效。 网关会在跨协议时转换工具定义,但目标模型必须 支持工具调用。不支持时上游会忽略 tools,表现为模型直接回答而没调函数。

modalities 带 image 却画不出图。 那个字段是「能读图」。画图要看模型有没有图片定价规则, 并且打的是图片端点。见模型与路由。

图片 b64_json 拿不到。 图片端点支持,视频端点明确 400 —— 产物可能几百 MB,不往 JSON 里塞。

流式

不流。 中间有反向代理在缓冲。网关侧已禁用压缩与缓冲;再被缓冲一层就是「等很久,然后一次吐出来」。 Nginx 上 proxy_buffering off;。排查步骤见流式输出。

流到一半断了。 没收到 [DONE] 就是中途断开(上游或网络)。计费按已发出部分折算, 不是按整段。重试前想清楚:没有幂等键的提交是第二笔钱。

只看到 reasoning_content。 那是思考过程,与正文分开发。只读 delta.content 就能忽略它。

控制台

登录后什么都看不到。 普通用户与管理员看到的菜单不同;管理员要 admin 角色, 且部分页签还需要管理员单独授权。

公告页是空的。 新建的公告是草稿,要点列表里的「发布」才会对外出现;排期的公告 到点才出现(按服务器时间 UTC 判断,不看浏览器时钟)。

时间差了 8 小时。 接口时间都是 UTC,控制台按浏览器时区渲染。自己写脚本时注意: 接口返回的时间串可能不带时区后缀,要按 UTC 解析。

「平均延迟」很大。 那个数字是「上游给出回应」的耗时:同步是整次调用、流式是首帧、 异步是提交受理。

报障模板

贴这四样,能省一轮来回:

1. X-Request-Id: req_...
2. 请求:method + 完整路径 + 请求体(密钥等敏感信息打码)
3. 响应:状态码 + 响应体
4. 时间(带时区):2026-11-18 09:12:34 +08:00

异步任务再加一条任务 id(或控制台「异步任务」页里的行)。