概览

最后更新

基础地址与版本

协议 基础地址 说明
OpenAI 兼容 https://modelportal.ai/v1 与 OpenAI API 的 /v1 路径一致
Anthropic 兼容 https://modelportal.ai 接口在 /v1/messages 下，需要 anthropic-version 请求头
Gemini 兼容 https://modelportal.ai/v1beta 与 Gemini API 的 /v1beta 路径一致
平台接口 https://modelportal.ai/api/v1 公开的模型列表等

接口版本跟随各协议的官方版本号。平台新增字段只增不改；会破坏兼容的改动会提前发公告。

鉴权

协议 请求头
OpenAI 兼容 Authorization: Bearer YOUR_API_KEY
Anthropic 兼容 x-api-key: YOUR_API_KEY 或 Bearer
Gemini 兼容 x-goog-api-key: YOUR_API_KEY、查询参数 key 或 Bearer

详见鉴权。

平台请求头

请求头 协议 说明
X-ModelPortal-Provider-Preferences 三种 路由偏好，JSON，字段同 provider 对象，最长 4096 字节，见供应商选择
X-ModelPortal-Session 三种 会话标识，用于会话亲和，见默认路由规则
Idempotency-Key 三种 幂等键：同一个键重复提交不会再次调用上游，非流式请求原样返回第一次的结果，流式请求返回 409

平台响应头

模型调用的成功响应带以下响应头：

响应头 说明
X-ModelPortal-Request-Id 平台请求 ID，和控制台调用明细、账单对得上
X-ModelPortal-Provider 实际承接的供应商标识
X-ModelPortal-Endpoint 实际承接的报价标识
X-ModelPortal-Model 实际使用的规范模型 ID
X-ModelPortal-Attempts 这次请求尝试了几个报价

流式响应在首个内容事件到达、或开始发保活时发出响应头，以先到的为准。只发过保活时供应商、报价和尝试次数还没定，这三个头不出现，以流里的字段为准。

响应附加字段

三种协议的响应体都多三个字段，流式写在最后带用量的那个事件里：

字段 说明
provider 实际承接的供应商标识
attempts 每次尝试一项：provider、endpoint（报价标识）、status（HTTP 状态）、cost（USD）；失败的尝试 cost 为 0
用量对象里的 cost 这次请求的扣费金额（USD），和账单一致

用量对象是 OpenAI 的 usage（Responses 流式是 response.usage）、Anthropic 的 usage、Gemini 的 usageMetadata。OpenAI Chat 流式的每个分块都带 provider。实际承接的报价以最后一项 attempts 为准。

错误

每种协议按自己的错误格式返回：OpenAI 格式与平台接口的 code 是平台错误码；Anthropic 格式只有错误类型，Gemini 格式的 code 是 HTTP 状态码。完整错误码表、422 的排除原因代码表见常见错误。

限流

账户每分钟请求数、单个密钥每分钟请求数、同时进行的请求数三项限额，超限返回 429 rate_limited，带 Retry-After。分档见常见错误。

请求详情与密钥额度

下面两个接口用 API 密钥鉴权，只认 Authorization: Bearer YOUR_API_KEY。它们不收费，但计入这把密钥的每分钟请求数。金额字段以 _minor 结尾，单位是 0.000001 USD。

GET /api/v1/requests/{请求 ID}

请求 ID 就是响应头 X-ModelPortal-Request-Id 的值。一把密钥只能查自己发起的请求；同账户其他密钥或其他账户的请求，和不存在的请求 ID 一样返回 404 call.not_found。能查多久以前的请求，跟调用记录的保留期一致。

字段 说明
request_id、started_at、model、status 请求 ID、开始时间、模型 ID、状态
provider、offering_id 最终承接的供应商标识与报价标识
config_version、price_version 承接时这个报价的配置版本号与价格版本号
error_category 失败时的错误类型
duration_ms、first_byte_ms 耗时与首字延迟，单位毫秒
tokens 各项用量
cost_minor 这次请求的费用，和账单一致
meter_flags 计量标记，例如按估算计费的 estimated
routing_constraints 生效的路由约束：账户偏好、密钥偏好和请求参数合并后的数据政策、地区、量化精度等限制，没有限制时为 null
attempts 每次尝试一项：provider、offering_id、config_version、started_at、duration_ms、upstream_status（HTTP 状态）、error_category、cost_minor

GET /api/v1/key

返回当前密钥的设置与额度：

字段 说明
id、name、last4、status、expires_at 密钥 ID、名称、末 4 位、状态、过期时间
allowed_model_ids 模型白名单，空表示全部模型
daily_limit_minor、monthly_limit_minor 每日、每月消费上限，没设为 null
spent_today_minor、spent_month_minor 今天、本月已用，和控制台密钥列表一致
held_minor 在途请求的预扣
rate_limits 限流档位：账户每分钟请求数、单个密钥每分钟请求数、同时进行的请求数
routing_preferences 密钥级路由偏好
available_minor 这把密钥现在能用的额度

available_minor 只算现金余额和不限模型的赠送额度，已预扣的部分不算。密钥设了消费上限时，它不会超过「上限 − 本期已用 − 在途预扣」。

应用授权与管理 API 还没有开放，上线时会在这里补上。