文档目录

从别的网关迁移

改三处就能跑;以及六处最容易当成 bug 的行为差异与一份迁移检查单。

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

本页目录

如果你原来用的是 New API / One API 一类的网关,改三处就能跑:

项原来这里
base url各自的地址<网关地址>/v1(不是 /api/v1,也不是 /v1/chat/completions 整条)
密钥sk- 开头的一串sk-ag- 开头。前缀不是契约的一部分,别用它判类型
模型名厂商原名或别家的别名本站实际接入的显示名,先 GET /v1/models

迁过来最容易被当成 bug 的六处

  • 余额不足是 402,不是 400。 400 会让 SDK 以为「参数错了」并把错误展示给你改参数,而真实处置是充值。
  • 视频提交失败是 502,响应体里仍带任务 id(用来对账),不再有 200 + submitted:false。
  • /v1/videos/{id}/content 直接给字节(Sora 契约)。要链接用 /v1/videos/{id}/link。
  • /v1/videos 是 Sora 形状:id 是字符串、status 四态小写、seconds 是字符串、时间是秒级整数。网关的七个状态在 state 里。
  • 管理接口不接受 API Key。 控制台的 /api/** 要登录后拿到的访问令牌;API Key 只调 /v1/**。两个命名空间互不通用,这是刻意的:一个密钥能改自己的余额,等于没有余额。
  • 没有「令牌分组倍率」这个概念。 价格由模型的定价规则与档位决定,与你发什么请求头无关。

迁过来最容易被当成「没生效」的两处

  • 未知字段被静默忽略。 有些网关对不认识的参数返回 400,这里返回 200 —— 参数确实没生效。写错键名(maxTokens 而不是 max_tokens)不会有提示,只能对照字段表。
  • n 不决定计费。 图片按实际返回张数、视频按实际上报时长。照旧逻辑估算预扣,会发现实际扣得不一样。

迁移检查单

  1. base url 改成 <网关地址>/v1,确认不是 /api/v1。
  2. 换密钥,别把 sk- 当类型判据。
  3. GET /v1/models 拉清单,把旧模型名映射到这里的显示名。
  4. 用一条最小请求验证鉴权与模型解析(不要一上来就压测)。
  5. 接入异步链路:确认提交带幂等键、轮询在终态停止、产物链接及时下载。
  6. 对账:用使用日志里的价目快照(priceSnapshot)核一天,确认与预期口径一致。

反向迁移(从本网关出去)

如果哪天要迁走:入站形状都是标准协议(OpenAI / Anthropic / Gemini / 可灵 / 即梦), 把 base url 指回原厂即可。唯一需要注意的是我们扩展的字段(state、/link、settleStatus) 在别家不存在 —— 用它们的地方要改成读标准字段。