文档目录

模型与路由

模型清单从哪来、显示名与规范 id 怎么解析、能力位不等于计价方式、多渠道路由与转移。

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

本页目录

模型从哪来

模型清单一律来自本站实际接入的模型,不是厂商的全量目录:

  • 管理员在控制台的「渠道」页绑定「渠道 × 模型」,并在「模型」页维护价格与能力位。
  • GET /v1/models 只列出当前可用、且你的身份能用的那些。
  • 模型广场 /square 用同一份数据展示价目与能力矩阵,不要求登录。

所以「同一个模型名在别处能用、这里 404」不是 bug:这里的名字是本站的承诺,不在清单里的名字没有渠道能接。

显示名与规范 id

一个模型有两个名字:管理员起的显示名(Seedance-2-5)与上游的规范 id(doubao-seedance-2-5-260628)。两个都能用,解析顺序是固定的:

你写的结果
正好是某个模型的规范 id,且它有自己的显示名用它。老客户端发真实 id 不会被换到别的模型上
唯一命中某个模型的显示名用它
同时是「A 的显示名」和「B 的规范 id」,而 B 没有显示名用 A —— 连对外名称都没有的行不构成对外承诺
命中多个模型的同一个显示名409 model.ambiguous,报文里列候选。不猜:挑错的后果是你以为调 A 实际调 B,而账单完全正常
是某个模型但已下架403 model.disabled(不是 404)—— 404 会让你去改一个本来正确的名字
完全不认识404 model.not_found

GET /v1/models/{model} 接受两种写法;两者不同时响应里会回 requested_as,方便对账。

能力位不等于计价方式

模型上的 modalities 说明它能读 / 能产什么,不说明怎么收费:

  • modalities 含 image 只是「能读图」。要判断能不能画图,看它有没有 per_image / per_call 的定价规则。
  • 一个模型可能既是文本模型又绑了图片定价(同一个上游既会写字又会画图),这时按端点决定走哪条计价路径。
  • 拿文本模型去打图片端点会被挡在入站层:400 model.modality_not_supported,不会先转发再被上游拒。

一个模型,多条渠道

同一模型可以由多条上游线路承接,它们的差别是稳定性与能力细节(比如是否支持某种分辨率)。

请求类型选渠道与转移
文本(非流式)在同模型的多条渠道间做请求内转移,最多尝试 3 条
文本(流式)只选一条:已经吐出去的字节无法换渠道重来
图片 / 语音 / 视频 / 音乐只选一条,不在一次请求里切换

后两类不在请求内切换,原因是它们的「重试」意味着重新生成:图片会再出一张、视频会再下一单。那不是重试,那是第二次消费。

全部候选渠道都失败时返回 502 channel.all_failed;一条都用不了(都停用 / 都不在你的分组里)返回 503 channel.unavailable。两者要分开看:前者是上游的问题,后者是配置的问题。

定价与渠道无关

  • 调用方看到的是模型定价:单位 × 单价 × 档位,与走哪条上游线路无关。
  • 同一个模型可以由不同线路承接,你看到的标价不变。
  • 每次下单会把当时的价目记进价目快照(priceSnapshot)。改价不影响已下单的任务,对账也要用快照而不是今天的价目表。

若本站的价目表超过 7 天未同步,新的任务提交会被暂时拒绝(409 price.stale)—— 避免拿一份已经过时的价目表收费。遇到它请联系管理员。

计费口径、八个计价单位与预扣结算见计费与配额。