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

# 直接调用 API

> 接口地址、鉴权方式、可用模型查询，以及用 curl 和 SDK 调用的示例。

TokenHub 兼容 Anthropic Messages 和 OpenAI Responses 两种接口。密钥绑定的分组决定了它走哪一种：面向 Claude 的分组用 Anthropic 接口，面向 Codex 的分组用 OpenAI 接口。

## 接口地址

| 生态 | Base URL |
| - | - |
| Anthropic 兼容 | `https://aitokenhub.vip`（不带 `/v1`，SDK 会自己拼上 `/v1/messages`） |
| OpenAI 兼容 | `https://aitokenhub.vip/v1` |

在控制台 **账户 → 密钥设置** 点 **Endpoints** 按钮，也能看到并复制这两个地址。

目前开放的接口：

| 接口 | 协议 | 用途 |
| - | - | - |
| `POST /v1/messages` | Anthropic | 生成消息 |
| `POST /v1/messages/count_tokens` | Anthropic | 计算 token 数 |
| `POST /v1/responses` | OpenAI | 生成响应 |
| `POST /v1/responses/compact` | OpenAI | 压缩上下文 |
| `POST /v1/responses/input_tokens` | OpenAI | 计算输入 token 数 |
| `GET /v1/models` | 两者皆可 | 列出可用模型（不收费） |

## 鉴权

以下任意一种请求头都可以携带密钥：

```http theme={null}
x-api-key: <your-api-key>
```

```http theme={null}
Authorization: Bearer <your-api-key>
```

Anthropic SDK 默认用第一种，OpenAI SDK 和 Codex 默认用第二种，不需要额外处理。

> [!WARNING]
>
> 密钥等同于你的余额。不要写进前端代码、提交到代码仓库，或发到群里。泄露后请立即到控制台吊销。

## 客户端限制

很多分组只允许官方客户端访问：Claude Code、Claude 桌面版和 Codex。用 curl、SDK 或其他第三方工具请求这类分组时，会收到 `403 client.not_allowed`。

如果你需要在自己的程序里调用，请选择允许所有客户端的分组，或联系平台管理员开通。下面的调用示例都假定你的分组允许这样访问。

## 查询可用模型

`GET /v1/models` 返回密钥所在分组可用的模型。它不收费、不占并发，也不受客户端限制，适合用来确认密钥是否有效：

```bash theme={null}
curl https://aitokenhub.vip/v1/models \
  -H "x-api-key: <your-api-key>"
```

返回格式跟随分组的协议：Anthropic 分组返回 Anthropic 的模型列表格式，OpenAI 分组返回 `{"object": "list", "data": [...]}`。请求时 `model` 字段按返回的 `id` 原样填写。

模型 ID 带 `[1m]` 后缀的（例如 `claude-sonnet-4-6[1m]`）是 100 万 token 上下文的版本。

## 调用示例

```bash curl theme={null}
curl https://aitokenhub.vip/v1/messages \
  -H "x-api-key: $TOKENHUB_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "<模型 ID>",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "你好"}]
  }'
```

```python Python theme={null}
import os
from anthropic import Anthropic

client = Anthropic(
    base_url="https://aitokenhub.vip",
    api_key=os.environ["TOKENHUB_API_KEY"],
)

message = client.messages.create(
    model="<模型 ID>",
    max_tokens=1024,
    messages=[{"role": "user", "content": "你好"}],
)
print(message.content[0].text)
```

```typescript TypeScript theme={null}
import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  baseURL: "https://aitokenhub.vip",
  apiKey: process.env.TOKENHUB_API_KEY,
});

const message = await client.messages.create({
  model: "<模型 ID>",
  max_tokens: 1024,
  messages: [{ role: "user", content: "你好" }],
});
console.log(message.content);
```

OpenAI 分组用 `POST /v1/responses`，base URL 改成 `https://aitokenhub.vip/v1`，其余用法和 OpenAI Responses API 一致。

## 请求限制

* 单个请求体最大 64 MB。
* 耗时较长的请求请开启流式输出（`stream: true`），避免长时间没有数据返回而被断开。
* 并发请求数按个人 / 团队统一计算，不是按密钥。超过上限会收到 `429`。

## 错误格式

TokenHub 拒绝请求时，返回对应的 HTTP 状态码和：

```json theme={null}
{
  "error": {
    "code": "billing.payment_required",
    "message": "insufficient balance"
  }
}
```

请求已经转发到模型之后出的错，会原样返回上游的错误。全部错误码见 [错误码](https://docs.aitokenhub.vip/reference/errors.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.