接口设计稿 · 第 0.1 版

先把接口摆出来，听完意见再动手

这是一份设计稿，接口尚未开放，字段在内测前都可能调整。把它摆出来，是为了让将来的调用方现在就能提意见：哪里别扭、缺什么，直接来信。

一、设计原则

第一，沿用业界通行的对话接口写法，已有代码只改地址与密钥即可接入。第二，路由相关的选项全部可选，不写就走默认的均衡策略。第三，返回里写明实际走了哪个上游、用了多少词元，账单与返回可以逐条对上。

二、对话接口

POST /v1/chat/completions，请求头 Authorization: Bearer kr-…。请求体在通行字段之外，多三个可选字段。

字段	类型	含义
`model`	字符串	写具体模型名，或写 `auto` 交给路由选择。
`route`	字符串，可选	`price` 最低价优先，`latency` 最低延迟优先，`balanced` 均衡（默认）。
`fallbacks`	字符串数组，可选	首选失败时依次尝试的模型名。不写则由路由在同档模型里选。
`max_price`	数字，可选	单价上限（元/百万词元）。超过上限的上游不参与选择；全部超限则直接报错，不悄悄用贵的。

三、返回里多出来的字段

{
  "model": "模型甲",                 // 实际作答的模型
  "choices": [ … ],
  "usage": { "prompt_tokens": 21, "completion_tokens": 64, "total_tokens": 85 },
  "routing": {
    "upstream": "上游 A",            // 实际走的上游
    "attempts": 2,                  // 尝试次数；大于 1 说明发生过转移
    "strategy": "balanced",
    "latency_ms": 731
  }
}

四、错误码与重试

状态码	含义	调用方该怎么办
`401`	密钥无效或缺失	检查密钥，不要重试。
`402`	余额或配额不足	充值或联系管理员调整配额。
`422`	全部上游超出 `max_price`	放宽上限或换模型。
`429`	超出速率限制	按返回头里的等待秒数退避后重试。
`502`	全部上游都失败	路由已替你试过全部可用上游；稍后重试，返回体里列出每个上游的失败原因。

路由内部的转移对调用方不可见：只要有一个上游成功，调用方拿到的就是一次正常返回，只是 routing.attempts 大于 1。

五、流式、工具调用与结构化输出

三者都按通行写法透传。上游不支持某项能力时，路由不做模拟，直接跳过该上游；全部不支持则返回 422 并说明原因。

六、还没定的事

模型名单与命名规则要等上游授权确定后公布。计费精度、发票与对公结算的细则在内测前公布。意见请发到页脚的联系邮箱，标题写“接口设计稿意见”。