> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aiohub.org/llms.txt
> Use this file to discover all available pages before exploring further.

# API 概览

> 了解 AIOHub 的 Base URL、鉴权方式、请求示例、响应结构和可用端点。

## Base URL

不同协议对 Base URL 的要求不同。按客户端或 SDK 的配置项填写，不要混用。

| 场景                          | Base URL                               | 常用端点                                          |
| --------------------------- | -------------------------------------- | --------------------------------------------- |
| OpenAI SDK / 通用 OpenAI 兼容工具 | `https://api.aiohub.org/v1`            | `POST /chat/completions`                      |
| Codex CLI                   | `https://api.aiohub.org/v1`            | `POST /responses`                             |
| Anthropic SDK / Claude Code | `https://api.aiohub.org`               | `POST /v1/messages`                           |
| Gemini CLI                  | `https://api.aiohub.org`               | `POST /v1beta/models/{model}:generateContent` |
| Gemini REST / Google SDK    | `https://api.aiohub.org/v1beta`        | `POST /models/{model}:generateContent`        |
| 控制台首页                       | `https://api.aiohub.org/console`       | 账户总览                                          |
| API 令牌管理                    | `https://api.aiohub.org/console/token` | 创建和管理 API 令牌                                  |
| 钱包管理                        | `https://api.aiohub.org/console/topup` | 查看余额、充值和充值记录                                  |
| 使用日志                        | `https://api.aiohub.org/console/log`   | 查看消费记录和用量明细                                   |

## 支持的 API 格式

| 格式               | 端点                                            | 适用场景                             |
| ---------------- | --------------------------------------------- | -------------------------------- |
| OpenAI 兼容        | `POST /v1/chat/completions`                   | 大多数 SDK 和工具的默认格式                 |
| OpenAI Responses | `POST /v1/responses`                          | Codex CLI 和使用 Responses API 的客户端 |
| Claude Messages  | `POST /v1/messages`                           | Claude Code、Anthropic SDK        |
| Gemini API       | `POST /v1beta/models/{model}:generateContent` | Gemini CLI、Google SDK            |

<Tip>不确定用哪个格式时，先使用 OpenAI Chat Completions 完成对话请求验证；Codex CLI 使用 Responses，而不是 Chat Completions。</Tip>

## 鉴权方式

AIOHub API 令牌以 `sk-` 开头。不同客户端可能使用不同请求头，但 API 令牌值相同：

| 格式                  | 请求头                                     | 常见客户端                               |
| ------------------- | --------------------------------------- | ----------------------------------- |
| Bearer 鉴权           | `Authorization: Bearer sk-xxx`          | OpenAI SDK、Codex CLI、通用工具           |
| Anthropic API Key   | `x-api-key: sk-xxx`                     | Anthropic SDK                       |
| Anthropic Bearer 鉴权 | `Authorization: Bearer sk-xxx`          | Claude Code（`ANTHROPIC_AUTH_TOKEN`） |
| Google API Key      | `x-goog-api-key: sk-xxx` 或 `key=sk-xxx` | Gemini CLI、Google SDK               |

详细示例见 [鉴权](/cn/api/authentication)。

## 请求示例

```bash theme={"system"}
curl https://api.aiohub.org/v1/chat/completions \
  -H "Authorization: Bearer sk-你的API令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'
```

## 响应格式

成功响应返回 JSON，字段结构按所选 API 格式保持兼容。以下是 OpenAI Chat Completions 示例：

```json theme={"system"}
{
  "id": "chatcmpl-xxx",
  "object": "chat.completion",
  "model": "gpt-4o",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 12,
    "total_tokens": 22
  }
}
```

## 流式响应

Chat Completions 支持 SSE 流式返回。设置 `"stream": true` 即可：

```bash theme={"system"}
curl https://api.aiohub.org/v1/chat/completions \
  -H "Authorization: Bearer sk-你的API令牌" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'
```

## 错误响应

错误响应包含 HTTP 状态码和 JSON 错误体：

```json theme={"system"}
{
  "error": {
    "message": "Incorrect API key provided",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}
```

常见状态码参见 [HTTP 状态码](/cn/support/http-status-codes)。

## 可用端点

API 文档展示面向用户开放的主要端点。模型、分组和端点的实际可用性以 `/v1/models`、控制台模型定价页和当前线上服务状态为准；未在导航中列出的兼容路由不属于公开支持范围。