# API 概述

Clomio 网关提供与 **OpenAI**、**Anthropic**、Grok/xAI 等兼容的 HTTP API。本节是 API 参考的总入口,先讲通用约定,各端点的完整文档见左侧子页。

---

## 基础信息

| 项 | 值 |
|----|-----|
| OpenAI-compatible Base URL | `https://api.clomio.ai/v1`(可换[线路](#/gateway-lines):`sub.qazwc.com/v1` / `crs.qazwc.com/v1`) |
| Anthropic-compatible Base URL | `https://api.clomio.ai`(SDK/Claude Code 会自动拼 `/v1/messages`) |
| 协议 | HTTPS,请求/响应均为 JSON(图像/视频编辑用 `multipart/form-data`) |
| 鉴权 | 请求头 `Authorization: Bearer 你的密钥`;普通网关也接受 `x-api-key` / `x-goog-api-key` |
| 字符编码 | UTF-8 |

密钥在控制台 [api.clomio.ai](https://api.clomio.ai) 创建,分组需与所调模型匹配,见 [创建 API 密钥](#/api-key)。Base URL 加不加 `/v1` 见 [Base URL 与 /v1 规则](#/base-url-matrix)。

---

## 通用请求头

| 请求头 | 必填 | 说明 |
|--------|:----:|------|
| `Authorization` | 是* | `Bearer 你的密钥` |
| `x-api-key` | 是* | Anthropic SDK/部分 GUI 常用的 Key 头 |
| `x-goog-api-key` | 是* | Gemini/部分 Google 风格工具常用的 Key 头；普通 `/v1` 网关也兼容 |
| `Content-Type` | 是* | JSON 请求填 `application/json`;上传文件填 `multipart/form-data` |
| `Accept` | 否 | 流式可用 `text/event-stream` |
| `anthropic-version` | 否** | Anthropic 原生端点建议带上,如 `2023-06-01` |
| `x-request-id` | 否 | 自定义请求 ID,便于工单排查 |

> \* 三种 Key 头任选其一即可，推荐优先用 `Authorization: Bearer ...`。GET 请求无需 `Content-Type`。\** OpenAI-compatible 端点不需要。

普通 Claude/OpenAI/Grok `/v1` 网关路径禁止把密钥放在 query string：`?key=` 或 `?api_key=` 会返回 400 `api_key_in_query_deprecated`。Gemini 原生 `/v1beta` 路径兼容 Google 风格 `key=` query，但 `api_key=` 仍会返回废弃错误；能用 header 时仍优先用 header。

---

## 端点一览

| 分类 | 端点 | 方法 | 文档 |
|------|------|:----:|------|
| 对话(Chat Completions) | `/v1/chat/completions` | POST | [Chat Completions](#/api-chat) |
| 对话(Responses) | `/v1/responses` | POST | [Responses](#/api-responses) |
| Codex/WS v2 | `/v1/responses` | GET | [Responses](#/api-responses) |
| 对话(Claude 原生 / OpenAI Messages dispatch) | `/v1/messages` | POST | [Messages](#/api-messages) |
| 计数 | `/v1/messages/count_tokens` | POST | [Messages](#/api-messages) |
| Gemini 原生兼容 | `/v1beta/models` · `/v1beta/models/{model}:generateContent` | GET/POST | [Gemini 原生兼容](#/api-gemini) |
| Antigravity 专用 | `/antigravity/v1/messages` · `/antigravity/v1beta/models...` | GET/POST | [Antigravity 接入](#/antigravity) |
| 向量 | `/v1/embeddings` | POST | [Embeddings](#/api-embeddings) |
| 图像 | `/v1/images/generations` · `/v1/images/edits` | POST | [Images](#/api-images) |
| 图像批处理 | `/v1/images/batches` 及其 `/:id` 子路径 | GET/POST/DELETE | [Images](#/api-images) |
| 视频(仅 Grok 分组) | `/v1/videos` · `/v1/videos/generations` · `/v1/videos/edits` · `/v1/videos/extensions` | POST/GET | [Videos](#/api-videos) |
| 语音(仅 Grok 分组) | `/v1/tts` · `/v1/stt` · `/v1/realtime` · `/v1/custom-voices` | POST/GET+WS | [Voice](#/api-voice) |
| 联网搜索 | `/v1/web_search` | POST | [Web Search](#/api-websearch) |
| Alpha Search | `/v1/alpha/search` | POST | OpenAI/Codex 专用搜索入口 |
| 模型 | `/v1/models` | GET | [Models](#/api-models) |
| 用量 | `/v1/usage` | GET | 见下 |
| Key 计费 | `/v1/sub2api/billing` | GET | 当前 Key 的余额/计费信息 |

> 文档和 SDK 示例以 `/v1/...` 作为规范写法；网关支持省略 `/v1` 的兼容形式。省略版本是否被客户端或外层线路直接转发，取决于所用 Base URL 和 endpoint 组合；如果响应是 HTML 而不是 API JSON，说明请求没有进入 API 路由，应改用同一 API 域名下的规范 `/v1/...` 路径。两种形式都可调用的端点请选择一种并保持 Base URL 与客户端的路径拼接规则一致，不要重复拼接路径。
>
> `GET /v1/responses` 是 Codex/Responses WebSocket v2 流入口,**不是**查询历史响应的 REST 接口;当前没有 `GET /v1/responses/{id}`。模型端点也只提供 `GET /v1/models` 列表,没有 `GET /v1/models/{id}`。

### 当前没有的常见误写端点

| 误写路径 | 当前事实 | 替代 |
|---|---|---|
| `/openai/v1/...` | 不是公开网关前缀 | 公开调用统一用 `/v1/...` |
| `/v1/images/variations` | Images 只注册 generations/edits | 用 `/v1/images/generations` 或 `/v1/images/edits` |
| `/v1/images2api/*` | 已不是公开入口 | 用 `/v1/images/*` 或 Responses `image_generation` tool |
| `GET /v1/web_search` | Web Search 简化入口只支持 POST | 用 `POST /v1/web_search` |
| `POST /v1/videos/{id}` | 视频任意子路径只用于 GET 查询/下载类透传 | 创建用 `/v1/videos/generations`;查询用 `GET /v1/videos/{request_id}` |
| `/antigravity/v1/responses` / `/antigravity/v1/chat/completions` | Antigravity v1 专用入口只注册 messages/count_tokens/models/usage | 对话用 `/antigravity/v1/messages`;普通 OpenAI/Codex 用 `/v1/responses` |

---

## 端点 × 分组(重要)

**端点是否可用,取决于你密钥所在分组的平台。** 用错分组会返回 404「not supported for this platform」或 403「does not support the requested model」。对应关系:

| 端点 | Claude 分组 | OpenAI 分组 | Grok 分组 | Gemini 分组 | Antigravity 分组 |
|------|:----:|:----:|:----:|:----:|:----:|
| `/v1/messages` | ✓ | ✓* | ✓* | ✗ | ✗ |
| `/v1/messages/count_tokens` | ✓/上游相关*** | ✗ | ✗ | ✗ | ✗ |
| `/v1/chat/completions` | ✓** | ✓ | ✓ | ✗ | ✗ |
| `POST /v1/responses` | ✗ | ✓ | ✓ | ✗ | ✗ |
| `GET /v1/responses` | ✗ | ✓ | ✓ | ✗ | ✗ |
| `/v1/embeddings` | ✗ | ✓ | ✗ | ✗ | ✗ |
| `/v1/images/*` | ✗ | ✓ | ✓ | ✗ | ✗ |
| `/v1/videos/*` | ✗ | ✗ | ✓ | ✗ | ✗ |
| `/v1/web_search` | ✗ | ✗ | ✓ | ✗ | ✗ |
| `/v1/tts` · `/v1/stt` · `/v1/realtime` · `/v1/custom-voices` | ✗ | ✗ | ✓ | ✗ | ✗ |
| `/v1beta/models...` | ✗ | ✗ | ✗ | ✓ | ✗ |
| `/antigravity/v1...` / `/antigravity/v1beta...` | ✗ | ✗ | ✗ | ✗ | ✓ |
| `/v1/models` · `/v1/usage` | ✓ | ✓ | ✓ | ✓ | ✓ |

> \* OpenAI/Grok 分组只有在当前分组开放 Messages ingress 能力时才接受 `/v1/messages`;否则返回 `This group does not allow /v1/messages dispatch`。Grok 的 Messages/Chat 请求会转换到 xAI Responses/Chat 兼容路径,模型和工具能力以分组为准。
>
> \** Claude 分组的 Chat Completions 会经网关转换到 Anthropic Messages 再返回 OpenAI Chat 形状;若分组被限制为 Claude Code only,仍会拒绝非 `/v1/messages` 请求。Grok Chat Completions 使用 xAI 兼容 Chat/Responses bridge,不是 Claude 转换路径。
>
> \*** `count_tokens` 是辅助估算端点;OpenAI/Grok 固定 404。其他 Anthropic-compatible 分组是否支持取决于模型；主 `/v1/messages` 成功时，辅助端点失败通常不影响正式请求。
>
> 简记:**Claude Code/Anthropic SDK**走 `/v1/messages`;**Codex/OpenAI SDK**优先走 `/v1/responses` 或 chat/images;**Gemini SDK/CLI**走 `/v1beta/models...`;**Antigravity**走 `/antigravity/...`;**Videos 只在 Grok 分组开放**,Grok 还支持 images/web_search。每个分组实际开放的**模型**以控制台为准。

### Base URL 与 `/v1` 怎么填

| 客户端/场景 | Base URL 建议 | 说明 |
|-------------|---------------|------|
| OpenAI SDK、Codex、OpenAI-compatible 工具 | `https://api.clomio.ai/v1` | SDK 会在此基础上追加 `responses`、`chat/completions`、`models` 等相对路径 |
| Anthropic SDK、Claude Code | `https://api.clomio.ai` | Anthropic SDK/Claude Code 会自行请求 `/v1/messages` |
| Gemini SDK/CLI 原生兼容 | `https://api.clomio.ai` | 客户端会自行请求 `/v1beta/models...`,详见 [Gemini 原生兼容](#/api-gemini) |
| Antigravity 专用入口 | `https://api.clomio.ai` | 请求路径自带 `/antigravity/v1...` 或 `/antigravity/v1beta...`,详见 [Antigravity 接入](#/antigravity) |
| 工具有独立 Endpoint Path 字段 | `https://api.clomio.ai` | Endpoint Path 再填 `/v1/...`,避免变成 `/v1/v1/...` |

兼容旧配置时，网关保留省略 `/v1` 的兼容入口。新接入建议沿用上表的 `/v1` 端点，便于不同 SDK 之间保持一致；手工使用根路径时请确认返回 `application/json` 或预期的音视频/WebSocket 响应，而不是站点 HTML。

另外还有两类专用兼容入口,只在对应分组/客户端场景下使用:

| 专用入口 | 典型路径 | 用途 | 注意 |
|----------|----------|------|------|
| Gemini 原生兼容 | `GET /v1beta/models`、`GET /v1beta/models/{model}`、`POST /v1beta/models/{model}:generateContent` 等 | Gemini SDK/CLI 原生形状 | 需要 Google/Gemini 平台分组;错误体会偏 Google API 风格;详见 [Gemini 原生兼容](#/api-gemini) |
| Antigravity 专用 | `/antigravity/models`、`/antigravity/v1/messages`、`/antigravity/v1/messages/count_tokens`、`/antigravity/v1beta/models...` | Antigravity 客户端专用入口 | 仅使用 Antigravity 分组；详见 [Antigravity 接入](#/antigravity) |

---

## 查询用量:GET /v1/usage

查询当前密钥的额度、限速窗口和用量统计。支持可选日期范围,影响 `model_stats` 的统计窗口:

| Query | 说明 |
|------|------|
| `start_date` | 开始日期,格式 `YYYY-MM-DD`;默认近 30 天 |
| `end_date` | 结束日期,格式 `YYYY-MM-DD`;按自然日包含该日期 |

```bash
curl 'https://api.clomio.ai/v1/usage?start_date=2026-06-01&end_date=2026-06-29'   -H "Authorization: Bearer 你的密钥"
```

如果这个 Key 配了总额度、有效期或 5h/1d/7d 限速,返回 `mode: "quota_limited"`:

```json
{
  "mode": "quota_limited",
  "isValid": true,
  "status": "active",
  "quota": { "limit": 10, "used": 1.25, "remaining": 8.75, "unit": "USD" },
  "rate_limits": [
    { "window": "5h", "limit": 2, "used": 0.4, "remaining": 1.6, "reset_at": "2026-06-29T20:00:00Z" }
  ],
  "usage": {
    "today": {
      "requests": 12,
      "input_tokens": 1200,
      "output_tokens": 300,
      "cache_creation_tokens": 0,
      "cache_read_tokens": 0,
      "total_tokens": 1500,
      "cost": 0.12,
      "actual_cost": 0.18
    },
    "total": {
      "requests": 320,
      "input_tokens": 45000,
      "output_tokens": 12000,
      "cache_creation_tokens": 5000,
      "cache_read_tokens": 18000,
      "total_tokens": 80000,
      "cost": 3.1,
      "actual_cost": 4.2
    }
  }
}
```

如果 Key 没有自身限制,返回 `mode: "unrestricted"`,并给出钱包余额或订阅剩余额度:

```json
{
  "mode": "unrestricted",
  "isValid": true,
  "planName": "钱包余额",
  "remaining": 23.5,
  "unit": "USD",
  "balance": 23.5,
  "usage": { "today": { "requests": 12, "actual_cost": 0.18 } }
}
```

`rate_limits[]` 会按窗口列出 `window`、`limit`、`used`、`remaining`、`window_start` 和可选 `reset_at`。`unrestricted` 不是“不计费”,只是 Key 本身没有独立 quota/限速;响应会按钱包或订阅模式给出 `balance` 或 `subscription`,并通常带 `usage` 与 `model_stats` 便于对账。

### `/v1/usage` 字段边界

- `start_date` / `end_date` 只影响 `model_stats` 的查询窗口,不改变 `usage.today` 或 `usage.total`;日期解析失败时会静默沿用默认近 30 天或已成功解析的另一端。
- `usage.today` / `usage.total` 除 token 和金额外,还可能带 `average_duration_ms`、`rpm`、`tpm`;这些统计是 best-effort,客户端不要假设所有字段必定存在。
- `model_stats` 是可选数组,常见字段包括 `model`、`requests`、`input_tokens`、`output_tokens`、`cache_creation_tokens`、`cache_read_tokens`、`total_tokens`、`cost`、`actual_cost`、`account_cost`。
- `rate_limits[].limit/used/remaining` 的单位是 **USD 实际消费额 actual_cost** 窗口,不是请求数、RPM 或 token 数;窗口过期时 `used` 会按 0 计算,`reset_at` 只在窗口未过期且 `window_start` 非空时返回。
- `quota_limited.isValid` 对 `active`、`quota_exhausted`、`expired` 都可能为 true;它表示这个 Key 仍能查询 usage,不等于一定还能继续发起计费请求。

详细计费见 [计费与额度](#/billing)。

---

## 鉴权示例

```bash
curl https://api.clomio.ai/v1/models   -H "Authorization: Bearer 你的密钥"
```

用 OpenAI SDK 时,把 `base_url` 指到带 `/v1` 的网关:

```python
from openai import OpenAI
client = OpenAI(api_key="你的密钥", base_url="https://api.clomio.ai/v1")
```

```javascript
import OpenAI from "openai";
const client = new OpenAI({ apiKey: "你的密钥", baseURL: "https://api.clomio.ai/v1" });
```

用 Anthropic SDK 时,`base_url` 不带 `/v1`:

```python
from anthropic import Anthropic
client = Anthropic(api_key="你的密钥", base_url="https://api.clomio.ai")
```

---

## 流式响应(SSE)

对话类端点支持流式:请求体加 `"stream": true`,服务端以 **Server-Sent Events** 逐块返回,每块形如 `data: {...}`。Chat/Messages 通常以 `data: [DONE]` 或消息结束事件收尾;Responses 会发 `response.completed`。若流开始后上游失败,可能收到 `response.failed` / `response.cancelled` 等终止事件。

---

## 错误格式

错误以 HTTP 状态码 + JSON 返回(OpenAI 风格、Anthropic 风格或 Google/Gemini 风格):

```json
{
  "error": {
    "message": "具体错误描述",
    "type": "invalid_request_error",
    "code": "model_not_found"
  }
}
```

Gemini 原生或 Antigravity `/v1beta` 入口可能返回 Google 风格:

```json
{
  "error": {
    "code": 401,
    "message": "Invalid API key",
    "status": "UNAUTHENTICATED"
  }
}
```

常见状态码:

| 码 | 含义 | 处理 |
|----|------|------|
| `200` | 成功 | — |
| `400` | 参数错误 | 检查请求体、模型名、工具结果关联 |
| `401` / `403` | 鉴权失败/分组或余额问题 | 密钥/分组/余额/订阅 |
| `404` | 地址错误或端点不属于该分组 | 检查路径、`/v1`、端点 × 分组 |
| `413` | 请求体过大 | 减少附件/上下文 |
| `429` | 触发限速 | 降并发、稍后重试或换分组/线路 |
| `529` / `503` | 服务或上游暂时不可用 | 稍后重试或换[线路](#/gateway-lines) |

模型和可用性错误可按这几个关键词区分:

- `The current group does not support the requested model "xxx". Available models: ...`:当前密钥分组明确不开放该模型,按列表换模型或换分组。
- `This group does not allow /v1/messages dispatch`:OpenAI 分组未开启 Messages dispatch,不要把它当 Claude 分组用;改用 `/v1/responses` / `/v1/chat/completions`,或换到允许 dispatch 的 OpenAI 分组。
- `model_not_found` / `Model "xxx" is not supported by any configured account in this group`:当前分组不支持这个模型，通常是模型名或分组能力不匹配。
- `No available accounts supporting model: xxx`:当前暂时无法提供该模型服务。
- `No available accounts` / `Service temporarily unavailable`:当前服务暂时不可用，可能与并发、额度或上游限速有关。
- `Messages API is not supported for this platform`:当前分组未开放 Messages 兼容入口；Claude 分组直接使用，OpenAI/Grok 分组需以分组能力为准。
- `Chat Completions API is not supported for this platform`:当前分组未开放 Chat Completions；Grok 和 OpenAI 分组通常可用，Claude Code only 分组请改用 `/v1/messages`。
- `Responses WebSocket API is not supported for this platform`:当前分组未开放 Responses WebSocket；OpenAI/Grok 分组通常可用，普通 HTTP 客户端请使用 `POST /v1/responses`。
- `Web Search API is not supported for this platform`:独立 `/v1/web_search` 只走 Grok 分组。
- `Videos API is not supported for this platform` / `Video generation is not enabled for this group`:视频只走已开通视频能力的 Grok 分组。
- `API key group platform is not gemini`:普通 `/v1beta` 路径需要 Gemini 分组;如果是 Antigravity 客户端,应使用 `/antigravity/v1beta/...` 和 Antigravity 分组。
- `Query parameter api_key is deprecated. Use Authorization header or key instead.`:Gemini 风格入口不要再用 `api_key` query,改用 `Authorization`、`x-goog-api-key` 或 `key` query。
- `content_policy_violation` / `内容审计命中风险规则，请调整输入后重试`:本地内容审计拦截,HTTP 通常为 403;若审计服务失败且策略 fail-closed,可能返回 `内容审计服务暂不可用，请稍后重试`。

完整错误码与排查见 [故障排查](#/troubleshooting)。

---

## 计费

响应里的 `usage` 字段展示本次 token。控制台和 `/v1/usage` 中:

- `cost` / `total_cost`:倍率前的基础成本口径
- `actual_cost`:实际扣余额、订阅或 API Key quota 的口径
- 缓存命中会体现在 `cache_creation_tokens`、`cache_read_tokens` 或各端点的 usage details 中

详见 [计费与额度](#/billing) 与 [用量明细](#/console-usage)。

## `/v1/usage` 参数与响应

| Query 参数 | 可选值/范围 | 默认/说明 |
|---|---|---|
| `start_date` | `YYYY-MM-DD` | 默认查询窗口；只影响 `model_stats` 时间范围 |
| `end_date` | `YYYY-MM-DD` | 包含当天；不能早于 `start_date` |
| `limit` | 正整数 | 部分部署支持；超范围会按服务端上限处理 |

成功响应可能包含 `mode`=`quota_limited`/`unrestricted`、`quota`、`rate_limits`、`usage`、`model_stats`。金额字段中的 `cost` 是基础成本，`actual_cost` 是叠加分组/Key 倍率后的实际消费。

```json
{
  "mode":"unrestricted",
  "isValid":true,
  "remaining":23.5,
  "unit":"USD",
  "usage":{"today":{"requests":12,"actual_cost":0.18}}
}
```

| HTTP | 典型错误 | 处理 |
|---:|---|---|
| 400 | 日期格式不合法 | 使用 `YYYY-MM-DD` |
| 401 | Key 无效/缺失 | 检查 Authorization |
| 403 | 用户、订阅或分组不可用 | 检查控制台状态 |
| 429 | usage 查询频率过高 | 客户端缓存结果 |
| 500/503 | 计费或服务暂时不可用 | 稍后重试，保留 request_id |