# AI Gateway 文档（全文）

<!-- 页面：概览（/） -->

# AI Gateway

AI Gateway 是一个自有的 AI 能力网关：对外提供 **OpenAI 兼容**的统一接口，对内管理多供应商线路、企业密钥、服务额度与计费。客户购买的是**服务额度**，不是上游供应商的 API 权限。

## 接口分三个面

| 面 | 路径前缀 | 使用者 | 鉴权 |
|---|---|---|---|
| 客户接口 | `/v1/*` | 接入产品（如 Monica） | 企业 key（`agw_` 前缀） |
| 管理接口 | `/admin/*` | 网关运营方 | Admin key / 控制台登录 |
| 运维探针 | `/health` `/readyz` | 监控与部署平台 | 无 |

## Base URL

| 环境 | 地址 |
|---|---|
| 生产 | `https://ai-gateway-6a41e6.preview.tencent-zeabur.cn` |
| 本地开发 | `http://127.0.0.1:18650` |

:::tip 集成建议
产品侧集成建议走内网/私有地址 + `agw_` key，不要把网关直接暴露给终端用户。
:::

## 当前能力

| 能力 | 状态 | 接口 |
|---|---|---|
| 文本生成（Chat） | ✅ 已上线 | [`POST /v1/chat/completions`](/api/chat) |
| 图像生成 | ✅ 已上线 | [`POST /v1/images/generations`](/api/images) 等 |
| 联网搜索 | ✅ 已上线 | [`POST /v1/searches`](/api/search) |
| 视频生成 / 语音合成 / 语音识别 / 向量 / 重排 | 🚧 规划中 | 见[规划中能力](/api/planned) |

## 给模型看的版本

本站同时提供机器可读的纯文本文档：

- [`/llms.txt`](pathname:///llms.txt)：页面索引
- [`/llms-full.txt`](pathname:///llms-full.txt)：全部内容单文件

把 `llms-full.txt` 的 URL 直接喂给 LLM 即可获得完整接口知识。

---

<!-- 页面：快速开始（/quickstart） -->

# 快速开始

三步完成首次调用：拿到企业 key → 调一次 Chat → 核对用量。

## 1. 获取企业 key

企业 key 由网关运营方通过 admin console（企业接入页）或管理接口签发，形如 `agw_xxxxxxxx`，绑定：

- **组织**：计费与账单主体；
- **scope**：可访问的产品（`text` / `image` / `search`），越权访问返回 403；
- 可选 **RPM / TPM 限额**。

:::warning
key 明文只在创建时返回一次，请妥善保存。泄漏时联系运营方吊销并换发。
:::

## 2. 首次调用

```bash
curl https://ai-gateway-6a41e6.preview.tencent-zeabur.cn/v1/chat/completions \
  -H "Authorization: Bearer agw_你的key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "azure-ai-foundry-deepseek-v4-pro",
    "messages": [{"role": "user", "content": "你好"}],
    "user": "user-1234"
  }'
```

要点：

- `model` 用网关的**对外别名**（完整列表见 [`GET /v1/models`](/api/models)），网关内部自动路由到具体供应商线路；
- `user` 字段建议**始终携带**（传你产品侧的用户 ID）——月度账单的人级明细按它聚合，见[计费与对账](/billing#user-标签人级对账)。

## 3. 核对用量与余额

调用成功后，运营方可在 admin console 的「用量账单」页看到逐笔事件；你会在月度结算单中看到按产品 × 模型和按 user 标签两套明细。

余额不足时接口直接返回 **402**（请求不会转发到上游，不产生费用），请联系运营方充值。

## 常见下一步

- 流式输出、工具调用 → [文本生成](/api/chat)
- 出图（同步 / 异步任务）→ [图像生成](/api/images)
- 联网搜索 → [搜索](/api/search)
- 错误码一览 → [鉴权与错误码](/auth)

---

<!-- 页面：鉴权与错误码（/auth） -->

# 鉴权与错误码

## 鉴权方式

所有客户接口使用 HTTP Bearer：

```
Authorization: Bearer <token>
```

两类 token：

| 类型 | 形式 | 用途 |
|---|---|---|
| **企业 key** | `agw_` 前缀 | 客户接入唯一正式方式。绑定组织与产品 scope，计费、限流、人级对账都挂在它上面 |
| 内部直连 key | 运维配置的环境变量 | 仅网关运营方内部调试/冒烟，**不计费、不归属组织**，不对客户发放 |

`agw_` key 的 scope 与接口对应关系：

| scope | 可访问接口 |
|---|---|
| `text` | `POST /v1/chat/completions` |
| `image` | `POST /v1/images/generations`、`POST /v1/images/tasks`、`GET /v1/images/tasks/{id}` |
| `search` | `POST /v1/searches` |

`GET /v1/models` 无需鉴权。

## 错误码

| 状态码 | 含义 | 处理建议 |
|---|---|---|
| 401 | 缺少或无效的 Bearer token | 检查 key 是否正确、是否已被吊销 |
| **402** | 组织服务额度余额不足 | 响应体含 `balanceMicrounits` 当前余额；联系运营方充值。请求未转发上游，不计费 |
| 403 | key 没有该产品 scope | 换用带对应 scope 的 key，或联系运营方加 scope |
| 404 | 模型别名不存在或未启用 | 以 `GET /v1/models` 返回为准 |
| 429 | 超出 key 或线路的 RPM/TPM 限额 | 退避重试；持续触发请联系运营方调整限额 |
| 502 / 503 / 504 | 上游供应商故障 | 网关已按线路优先级自动重试/切换后仍失败；可重试 |

402 响应示例：

```json
{
  "detail": {
    "message": "Insufficient service credits",
    "balanceMicrounits": -1200,
    "currency": "CNY"
  }
}
```

## 高可用行为（对调用方透明）

同一个对外模型别名背后可配置多条供应商线路：请求按**优先级**分组（数字小者优先），组内按**权重**分流；可重试的上游错误（连接失败、429、5xx、超时）自动切换下一条线路，**不会重复计费**。流式请求只在首个数据块之前允许切换。

---

<!-- 页面：计费与对账（/billing） -->

# 计费与对账

## 计费口径

- 结算货币 **CNY**，内部以微元记账：**1 元 = 1,000,000 微元**，金额向上取整到微元；
- 对外价格挂在**能力维度**（产品 × 模型 × 计费单位），与实际承接的供应商线路无关——同一个模型别名无论路由到哪家供应商，价格一致；
- **失败请求（非 2xx）不计费**，月度结算单单列失败笔数；
- 计费模型要求组织余额为正才转发（余额硬闸，见 [402](/auth#错误码)）。

各能力计费单位：

| 能力 | 计费单位 |
|---|---|
| 文本生成 | 输入 / 输出 / 缓存读取，按 1K tokens |
| 图像生成 | 按张（异步任务按**成功取回**的张数） |
| 联网搜索 | 按次 |

## user 标签（人级对账）

所有计费请求都支持请求体 `user` 字段（任意字符串，建议传产品侧用户 ID，超过 256 字符截断）：

```json
{ "model": "...", "messages": [...], "user": "user-1234" }
```

- 月度结算单的**人级明细**按此字段聚合，用于产品侧内部分摊；
- 不带 `user` 的调用计入「(未标记)」行，**金额照收**；
- 图像与搜索接口同样支持该字段（网关转发上游前会剔除，不影响供应商行为）。

## 月度结算单

- 账期为 **Asia/Shanghai 自然月**（月初 00:00 起、次月初 00:00 止，含头不含尾）；
- 内容：期初余额 / 本期充值 / 本期消耗 / 期末余额、产品 × 模型明细、人级明细、失败笔数；
- 单据带勾稽标志（用量事件合计 == 额度扣减合计），CSV 版随发票交付；
- 有争议时以逐笔用量事件为准，可向运营方索取。

## 充值

当前为对公转账 + 运营方后台入账。入账后余额即时生效，充值记录会体现在结算单「本期充值」。

---

<!-- 页面：模型目录（/api/models） -->

# GET /v1/models

对外模型目录。**无需鉴权**。只返回已上线（`active`）的模型；规划中的能力不会出现在这里。

```bash
curl https://ai-gateway-6a41e6.preview.tencent-zeabur.cn/v1/models
```

响应（节选）：

```json
{
  "object": "list",
  "data": [
    {
      "id": "azure-ai-foundry-deepseek-v4-pro",
      "object": "model",
      "owned_by": "ai-gateway",
      "product": "text",
      "display_name": "DeepSeek V4 Pro",
      "supports_streaming": true,
      "supports_function_calling": true,
      "supports_vision": false,
      "max_input_tokens": 1000000,
      "max_output_tokens": 8192,
      "input_modalities": ["text"],
      "output_modalities": ["text"],
      "pricing": {
        "currency": "CNY",
        "units": [
          { "unit_type": "input_1k_tokens", "unit_name": "输入 / 1K tokens", "price_cny": 0.012 },
          { "unit_type": "output_1k_tokens", "unit_name": "输出 / 1K tokens", "price_cny": 0.024 },
          { "unit_type": "cache_read_1k_tokens", "unit_name": "缓存读取 / 1K tokens", "price_cny": 0.001 }
        ]
      }
    }
  ]
}
```

要点：

- `id` 即调用其他接口时的 `model` 参数（对外别名，与上游供应商的型号名解耦）；
- `product` 标识能力类型（`text` / `image` / `search`）；
- 能力标志（`supports_*`、`max_*_tokens`、modalities）用于产品侧做模型选择与前置校验；
- `pricing` 为该模型的对外报价（与[计费](../billing.md)同一套价目，CNY）：`unit_type` 对应计费单位（文本按 1K tokens，图片按张 `image`，搜索按次 `request`），`price_cny` 为每单位单价。价目未配置的模型该字段为 `null`。

---

<!-- 页面：文本生成（Chat）（/api/chat） -->

# POST /v1/chat/completions

OpenAI Chat Completions 兼容。需要 `text` scope，按 tokens 计费（输入 / 输出 / 缓存读取分开计价）。

## 非流式

```bash
curl https://ai-gateway-6a41e6.preview.tencent-zeabur.cn/v1/chat/completions \
  -H "Authorization: Bearer agw_你的key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "azure-ai-foundry-deepseek-v4-pro",
    "messages": [
      {"role": "system", "content": "你是一个有帮助的助手。"},
      {"role": "user", "content": "介绍一下你自己"}
    ],
    "user": "user-1234"
  }'
```

响应为标准 OpenAI 格式，`usage` 字段返回本次 token 用量（计费依据）：

```json
{
  "id": "chatcmpl-...",
  "choices": [{ "message": { "role": "assistant", "content": "..." } }],
  "usage": { "prompt_tokens": 25, "completion_tokens": 180, "total_tokens": 205 }
}
```

## 流式（SSE）

```bash
curl https://ai-gateway-6a41e6.preview.tencent-zeabur.cn/v1/chat/completions \
  -H "Authorization: Bearer agw_你的key" \
  -H "Content-Type: application/json" \
  -d '{"model": "baidu-qianfan-glm-5-2", "stream": true,
       "messages": [{"role": "user", "content": "写一首短诗"}],
       "user": "user-1234"}'
```

`stream: true` 时返回 `text/event-stream`，以 `data: [DONE]` 结束。供应商切换只发生在首个数据块之前，流中断不会静默换供应商。

## 支持的参数

常用 OpenAI 参数（`temperature`、`max_tokens`、`tools` / `tool_choice`、`response_format` 等）按上游模型能力透传；模型是否支持工具调用/视觉见[模型目录](/api/models)的能力标志。

## 使用 OpenAI SDK

网关完全兼容 OpenAI SDK，改 `base_url` 和 `api_key` 即可：

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://ai-gateway-6a41e6.preview.tencent-zeabur.cn/v1",
    api_key="agw_你的key",
)
resp = client.chat.completions.create(
    model="volcengine-doubao-seed-2-1-pro",
    messages=[{"role": "user", "content": "你好"}],
    user="user-1234",
)
```

---

<!-- 页面：图像生成（/api/images） -->

# 图像生成

需要 `image` scope。两种模式：**同步出图**（Seedream 系列）与**异步任务**（即梦系列）。计费按张；异步任务按**成功取回的张数**计费，提交本身不扣费。

## POST /v1/images/generations（同步）

```bash
curl https://ai-gateway-6a41e6.preview.tencent-zeabur.cn/v1/images/generations \
  -H "Authorization: Bearer agw_你的key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "doubao-seedream-5-0-260128",
    "prompt": "一张简洁的白底产品图，蓝色玻璃水杯，摄影棚光线",
    "size": "1024x1024",
    "response_format": "url",
    "user": "user-1234"
  }'
```

响应：

```json
{
  "created": 1751856000,
  "data": [{ "url": "https://..." }]
}
```

- `response_format`: `url`（默认，链接有时效）或 `b64_json`；
- `n` 支持多张，按张计费。

## POST /v1/images/tasks（异步提交）

适用于耗时较长的模型（即梦）：

```bash
curl https://ai-gateway-6a41e6.preview.tencent-zeabur.cn/v1/images/tasks \
  -H "Authorization: Bearer agw_你的key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jimeng-t2i-v40",
    "prompt": "赛博朋克城市夜景，霓虹灯，雨后街道",
    "size": "1024x1024",
    "user": "user-1234"
  }'
```

响应返回任务 ID：

```json
{ "id": "task_...", "status": "pending" }
```

## GET /v1/images/tasks/\{task_id\}（轮询取回）

```bash
curl https://ai-gateway-6a41e6.preview.tencent-zeabur.cn/v1/images/tasks/task_xxx \
  -H "Authorization: Bearer agw_你的key"
```

`status` 流转：`pending` → `running` → `succeeded` / `failed`。首次以 `succeeded` 取回时结算费用；`failed` 不计费；未轮询取回不扣费。任务结果有缓存，重复轮询不会重复计费。

---

<!-- 页面：联网搜索（/api/search） -->

# POST /v1/searches

联网搜索（博查引擎）。需要 `search` scope，按次计费。

```bash
curl https://ai-gateway-6a41e6.preview.tencent-zeabur.cn/v1/searches \
  -H "Authorization: Bearer agw_你的key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "阿里巴巴 2025 年 ESG 报告",
    "freshness": "noLimit",
    "summary": true,
    "count": 5,
    "user": "user-1234"
  }'
```

## 请求参数

| 参数 | 类型 | 说明 |
|---|---|---|
| `query` | string | 必填，搜索词 |
| `freshness` | string | 时效过滤：`noLimit`（默认）/ `oneDay` / `oneWeek` / `oneMonth` / `oneYear` |
| `summary` | boolean | 是否返回每条结果的摘要 |
| `count` | number | 返回条数（默认 10） |
| `user` | string | 人级对账标签，转发上游前剔除 |

## 响应（节选）

```json
{
  "data": {
    "webPages": {
      "value": [
        {
          "name": "结果标题",
          "url": "https://...",
          "snippet": "结果摘要...",
          "summary": "更完整的内容摘要...",
          "datePublished": "2025-04-18T00:00:00Z"
        }
      ]
    }
  }
}
```

---

<!-- 页面：规划中能力（/api/planned） -->

# 规划中能力

以下能力已进入网关能力目录（`planned` 状态），**尚未上线，接口不可调用**。端点形状将保持 OpenAI 兼容，正式上线时本文档会更新为完整参考。

| 能力 | 预期端点 | 预期计价单位 |
|---|---|---|
| 向量 embedding | `POST /v1/embeddings` | 1K tokens |
| 重排 rerank | `POST /v1/rerank` | 次 |
| 语音合成 speech | `POST /v1/audio/speech` | 1K 字符 |
| 语音识别 transcription | `POST /v1/audio/transcriptions` | 分钟 |
| 视频生成 video | `POST /v1/videos/tasks`（异步，同[图像任务](/api/images#post-v1imagestasks异步提交)模式） | 秒 / 条 |

上线节奏与各能力当前状态以运营方 admin console「能力状态」页为准。有优先接入诉求可与运营方沟通排期。

---

<!-- 页面：管理接口（内部）（/admin） -->

# 管理接口（`/admin/*`，仅内部）

供网关运营方使用，不对客户开放。日常操作建议走 admin console（浏览器），接口用于脚本化与应急。

## 鉴权

两种方式，二选一：

- **Admin API key**：`Authorization: Bearer $AI_GATEWAY_ADMIN_API_KEY`（支持多 key，逗号分隔配置）。用于脚本。
- **Session cookie**：`POST /admin/auth/login` 用户名密码登录，签发 HttpOnly cookie。admin console 走这条，key 不进前端。

## 接口分组

### 认证会话

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/admin/auth/login` | 用户名密码换 session cookie |
| GET | `/admin/auth/me` | 当前会话状态 |
| POST | `/admin/auth/logout` | 注销会话 |

### 企业与密钥

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/admin/organizations` | 创建企业（name + slug） |
| GET | `/admin/organizations` | 企业列表（含余额、活跃密钥数） |
| POST | `/admin/api-keys` | 签发 `agw_` key（组织 + scopes + 可选 RPM/TPM），**明文仅创建时返回一次** |
| GET | `/admin/api-keys` | 密钥列表（不含明文） |
| DELETE | `/admin/api-keys/{key_id}` | 吊销密钥 |

### 额度

| 方法 | 路径 | 说明 |
|---|---|---|
| POST | `/admin/credits` | 充值/调减（微元；正数充值，负数调减） |
| GET | `/admin/credits` | 额度流水（按组织过滤） |

### 能力目录与定价

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/admin/capabilities` | 能力就绪状态（能力 × 活跃模型 × 活跃线路 × 缺失 env） |
| GET / POST | `/admin/models` | 对外模型目录查询 / upsert（按 alias） |
| GET / POST | `/admin/model-deployments` | 供应商线路查询 / upsert（优先级、权重、限流、凭证 env 引用） |
| GET / POST | `/admin/pricing` | 价格目录查询 / upsert（对外价挂能力级；供应商成本行按 provider 区分） |

### 用量与账单

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/admin/usage-events` | 逐笔用量事件（含 user 标签、路由尝试、成本/售价快照） |
| GET | `/admin/usage-summary` | 按企业 × 产品 × 模型聚合 |
| GET | `/admin/statements?organization_id=&month=YYYY-MM` | 月度结算单 JSON（四项余额、产品明细、人级明细、勾稽标志） |
| GET | `/admin/statements/export` | 同上，CSV（UTF-8 BOM），随发票交付客户 |

### 总览

| 方法 | 路径 | 说明 |
|---|---|---|
| GET | `/admin/overview` | console 首页聚合（企业数、密钥数、近期请求等） |

## 出账示例

```bash
# 月度结算单 JSON
curl "$GW/admin/statements?organization_id=<org_id>&month=2026-07" \
  -H "Authorization: Bearer $AI_GATEWAY_ADMIN_API_KEY"

# CSV（交付客户）
curl -OJ "$GW/admin/statements/export?organization_id=<org_id>&month=2026-07" \
  -H "Authorization: Bearer $AI_GATEWAY_ADMIN_API_KEY"
```

---

<!-- 页面：运维探针（/ops） -->

# 运维探针（无鉴权）

## GET /health

进程存活探针。进程能响应即返回 200：

```json
{ "status": "ok", "jimeng_configured": true, "bocha_configured": true }
```

## GET /readyz

就绪探针，检查两件事，任一不满足返回 503：

1. **数据库 schema 版本**与代码要求的 Alembic 版本严格一致（新代码遇旧库、旧代码遇新库都会拒绝服务——所以部署顺序永远是**先迁移后发版**）；
2. `AI_GATEWAY_READY_PRODUCTS`（默认 `text,image,search`）中的每个产品都有活跃模型、活跃线路，且线路引用的凭证环境变量齐备。

`planned` 状态的规划中能力不参与就绪检查。

503 响应会列出未就绪的产品与原因（`no_active_models` / `no_active_deployments` / `missing_env`），可直接用于告警定位：

```json
{
  "status": "not_ready",
  "requiredProducts": ["text", "image", "search"],
  "notReadyProducts": [
    { "type": "image", "reason": "missing_env", "missingEnv": ["VOLCENGINE_ACCESS_KEY_ID"] }
  ]
}
```

---