# API 参考 — OpenAI / Anthropic / Gemini 三协议

Source: https://ofox.io/zh/docs/api

OfoxAI 提供三种协议的 API 接入方式，完全兼容各厂商官方 SDK，包括 OpenAI 最新的 Responses API。

**协议推荐：** OpenAI 协议推荐使用 [Responses API](https://ofox.io/zh/docs/api/openai/responses)，原生 Prompt Caching 支持更优；调用 Claude 模型推荐使用 [Anthropic 原生协议](https://ofox.io/zh/docs/api/anthropic/messages)，可获得完整特性和原生缓存优势。

## Base URL

| 协议 | Base URL | 说明 |
|------|----------|------|
| **OpenAI 兼容** | `https://api.ofox.io/v1` | 兼容 OpenAI SDK，支持 Chat Completions 和 Responses API |
| **Anthropic 原生** | `https://api.ofox.io/anthropic` | 兼容 Anthropic SDK，原生 Claude 体验 |
| **Gemini 原生** | `https://api.ofox.io/gemini` | 兼容 Google GenAI SDK |

## 认证

所有协议使用统一的 OfoxAI API Key，但 Header 格式因协议而异：

| 协议 | Header | 格式 |
|------|--------|------|
| OpenAI | `Authorization` | `Bearer sk-xxx` |
| Anthropic | `x-api-key` | `sk-xxx` |
| Gemini | `x-goog-api-key` | `sk-xxx` |

详见 [API Key 获取与使用](https://ofox.io/zh/docs/develop/authentication)。

## 可用端点

### OpenAI 兼容协议

| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/chat/completions` | POST | 创建对话补全 |
| `/v1/responses` | POST | 创建模型响应（Responses API，推荐） |
| `/v1/embeddings` | POST | 创建文本向量 |
| `/v1/images/generations` | POST | 图像生成 |
| `/v1/models` | GET | 列出所有可用模型 |
| `/v1/models/{provider}` | GET | 按供应商过滤模型 |
| `/v1/models/{provider}/{model_id}` | GET | 获取模型详情 |
| `/v1/models/count` | GET | 获取模型数量统计 |

### Anthropic 原生协议

| 端点 | 方法 | 说明 |
|------|------|------|
| `/anthropic/v1/messages` | POST | 创建 Messages（推荐） |
| `/anthropic/v1/models` | GET | 列出所有可用模型 |
| `/anthropic/v1/models/{provider}` | GET | 按供应商过滤模型 |
| `/anthropic/v1/models/{provider}/{model_id}` | GET | 获取模型详情 |
| `/anthropic/v1/models/count` | GET | 获取模型数量统计 |

### Gemini 原生协议

| 端点 | 方法 | 说明 |
|------|------|------|
| `/gemini/v1beta/models/{model}:generateContent` | POST | 生成内容 |
| `/gemini/v1beta/models/{model}:streamGenerateContent` | POST | 流式生成内容 |
| `/gemini/v1beta/models` | GET | 列出所有可用模型 |
| `/gemini/v1beta/models/{provider}` | GET | 按供应商过滤模型 |
| `/gemini/v1beta/models/{provider}/{model_id}` | GET | 获取模型详情 |
| `/gemini/v1beta/models/count` | GET | 获取模型数量统计 |

### 类型化判断（Decisions）

对内容做是/否、单选、打分判断，返回带概率的结构化答案，详见 [Decisions API 文档](https://ofox.io/zh/docs/api/decisions)。

| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/decisions` | POST | 统一格式，也可用 OpenAI SDK 调用 |
| `/openai/v1/decisions` | POST | 同上，供 base URL 为 `/openai/v1` 的 OpenAI SDK 使用 |
| `/typesafe/v1/systemone` | POST | TypeSafe 官方格式，兼容 TypeSafe SDK |

### 视频生成（OpenRouter 兼容）

统一异步视频生成 API，详见 [Video API 文档](https://ofox.io/zh/docs/api/videos)。

| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/videos` | POST | [创建视频生成任务](https://ofox.io/zh/docs/api/videos/create) |
| `/v1/videos/{id}` | GET | [查询任务状态与结果](https://ofox.io/zh/docs/api/videos/retrieve) |
| `/v1/videos/{id}` | DELETE | [取消任务](https://ofox.io/zh/docs/api/videos/cancel) |

### OfoxAI OpenAPI（账户）

与协议无关的平台接口，使用 OfoxAI API Key 鉴权。

| 端点 | 方法 | 说明 |
|------|------|------|
| `/v1/user/balance` | GET | [余额查询](https://ofox.io/zh/docs/api/openapi/balance)，兼容 cc-switch |

## 速率限制

OfoxAI 按量付费，所有用户共享统一的速率策略，无套餐差异：

| 限制项 | 额度 |
|--------|------|
| RPM（请求/分钟） | 100（团队级聚合） |
| TPM（Token/分钟） | 不限 |

RPM 按团队聚合计算，多 Key 共享同一配额。如需更高速率配额，请联系 [hi@ofox.ai](mailto:hi@ofox.ai) 申请调整。详见 [Rate Limits](https://ofox.io/zh/docs/develop/guides/rate-limits)。

当触发限流时，API 返回 `429 Too Many Requests`，响应 Header 包含：

```http
x-ratelimit-limit-requests: 100
x-ratelimit-remaining-requests: 0
x-ratelimit-reset-requests: 1s
```

## 错误码

所有协议返回统一的 HTTP 状态码：

| 状态码 | 说明 | 常见原因 |
|--------|------|---------|
| `200` | 成功 | — |
| `400` | 请求错误 | 参数格式错误、缺少必填字段 |
| `401` | 认证失败 | API Key 无效或过期 |
| `403` | 权限不足 | 账户无权访问该模型 |
| `404` | 资源不存在 | 模型 ID 错误 |
| `429` | 触发限流 | 超过速率限制 |
| `500` | 服务器错误 | 内部错误，请重试 |
| `502` | 上游错误 | 模型供应商服务异常 |
| `503` | 服务不可用 | 服务维护中 |

### 错误响应格式

```json
{
  "error": {
    "code": "invalid_api_key",
    "message": "提供的 API Key 无效，请检查后重试。",
    "type": "authentication_error"
  }
}
```

## OfoxAI 扩展参数

OfoxAI 在标准协议基础上提供扩展参数，用于高级路由和回退控制：

```json
{
  "model": "openai/gpt-6.1-sol",
  "messages": [...],
  "extra_body": {
    "provider": {
      "fallback": ["anthropic/claude-sonnet-5.5", "google/gemini-3.8-flash"]
    }
  }
}
```

`provider` 须置于请求体的 `extra_body` 中，放在顶层会返回 `400`。详见 [供应商路由](https://ofox.io/zh/docs/develop/advanced/provider-routing) 和 [故障回退](https://ofox.io/zh/docs/develop/advanced/fallback)。