# 概览

https://modelportal.ai/docs/api-overview?lang=zh

## 基础地址与版本

| 协议 | 基础地址 | 说明 |
| --- | --- | --- |
| 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 |

详见[鉴权](/docs/authentication)。

## 平台请求头

| 请求头 | 协议 | 说明 |
| --- | --- | --- |
| `X-ModelPortal-Provider-Preferences` | 三种 | 路由偏好，JSON，字段同 `provider` 对象，最长 4096 字节，见[供应商选择](/docs/provider-routing) |
| `X-ModelPortal-Session` | 三种 | 会话标识，用于会话亲和，见[默认路由规则](/docs/default-routing) |
| `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 的排除原因代码表见[常见错误](/docs/errors)。

## 限流

账户每分钟请求数、单个密钥每分钟请求数、同时进行的请求数三项限额，超限返回 429 `rate_limited`，带 `Retry-After`。分档见[常见错误](/docs/errors#限流)。

## 请求详情与密钥额度

下面两个接口用 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 还没有开放，上线时会在这里补上。