> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 文本 API

> 用一个 API 密钥，通过 OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 或 Gemini 原生请求调用 BeatAPI 的文本模型。

* BeatAPI 以同步、按 token 计费的 API 提供文本模型。只需一个 BeatAPI 密钥，用你的应用已在使用的请求格式发送即可。
* 所有文本模型共用一个密钥和一个 base URL：`https://direct.beatapi.io`（推荐）或 `https://api.beatapi.io`（备用）。
* 四种请求格式：OpenAI Chat Completions、OpenAI Responses、Anthropic Messages 和 Gemini 原生。用哪一种取决于系列，见下表。
* 文本调用立即返回 JSON，或以服务端推送事件流式返回，不会创建异步的 BeatAPI 任务。
* `GET /v1/text/models` 是公开的：无需密钥即可读取模型 ID、上下文窗口、输出上限和价格。

> **Note**
>
> 文本请求建议使用 `https://direct.beatapi.io` 作为 base URL：它不受 Cloudflare 100 秒限制，长时间的非流式请求不会被中途切断。`https://api.beatapi.io` 同样可用；如果你的网络访问不了 `direct.beatapi.io`，请改用它作为备用。两个域名的密钥、模型和价格完全一致。图片和视频 API 只使用 `https://api.beatapi.io`。

## 选择协议

| 协议                      | 端点                                            | SDK                            | 系列                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ----------------------- | --------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| OpenAI Chat Completions | `POST /v1/chat/completions`                   | OpenAI SDK（`chat.completions`） | [GPT](/text-api/gpt/chat-completions)、[Gemini](/text-api/gemini/chat-completions)、[Grok](/text-api/grok/chat-completions)、[DeepSeek](/text-api/deepseek/chat-completions)、[GLM](/text-api/glm/chat-completions)、[Qwen](/text-api/qwen/chat-completions)、[Kimi](/text-api/kimi/chat-completions)、[MiniMax](/text-api/minimax/chat-completions)、[MiMo](/text-api/mimo/chat-completions)、[Hunyuan](/text-api/hunyuan/chat-completions)、[Muse](/text-api/muse/chat-completions) |
| OpenAI Responses        | `POST /v1/responses`                          | OpenAI SDK（`responses`）        | [GPT](/text-api/gpt/responses)、[Gemini](/text-api/gemini/responses)、[Grok](/text-api/grok/responses)、[DeepSeek](/text-api/deepseek/responses)、[GLM](/text-api/glm/responses)、[Qwen](/text-api/qwen/responses)、[Kimi](/text-api/kimi/responses)、[MiniMax](/text-api/minimax/responses)、[MiMo](/text-api/mimo/responses)、[Hunyuan](/text-api/hunyuan/responses)、[Muse](/text-api/muse/responses)                                                                              |
| Anthropic Messages      | `POST /v1/messages`                           | Anthropic SDK（`messages`）      | [Claude](/text-api/claude/messages)、[Gemini](/text-api/gemini/messages)、[Grok](/text-api/grok/messages)、[DeepSeek](/text-api/deepseek/messages)、[GLM](/text-api/glm/messages)、[Qwen](/text-api/qwen/messages)、[Kimi](/text-api/kimi/messages)、[MiniMax](/text-api/minimax/messages)、[MiMo](/text-api/mimo/messages)、[Hunyuan](/text-api/hunyuan/messages)、[Muse](/text-api/muse/messages)                                                                                   |
| Gemini 原生               | `POST /v1beta/models/{model}:generateContent` | Gemini SDK 或直接 HTTP            | [Gemini](/text-api/gemini/native)                                                                                                                                                                                                                                                                                                                                                                                                                                           |

## Base URL 与鉴权

文本请求请使用 `https://direct.beatapi.io`，它不受 Cloudflare 100 秒限制。`https://api.beatapi.io` 是备用地址。密钥放在你的 SDK 已在使用的请求头里即可，它们都对应同一个 BeatAPI 账号和美元余额。密钥带不带 `sk-` 前缀都可以。

| 格式                                       | 密钥请求头                                                         |
| ---------------------------------------- | ------------------------------------------------------------- |
| OpenAI Chat Completions、OpenAI Responses | `Authorization: Bearer <BEATAPI_API_KEY>`                     |
| Anthropic Messages                       | `x-api-key: <BEATAPI_API_KEY>`，或 `Authorization: Bearer`      |
| Gemini 原生                                | `x-goog-api-key: <BEATAPI_API_KEY>`，或 `Authorization: Bearer` |

> **Note**
>
> 请把长期有效的 BeatAPI 密钥保存在可信的服务端，不要放进浏览器或移动应用。

## 各模型该用哪种格式

* **GPT** 使用 OpenAI Chat Completions 或 OpenAI Responses。新的推理和工具调用集成推荐使用 Responses。
* **Claude** 使用 Anthropic Messages（`POST /v1/messages`）。
* **Gemini** 四种格式都可以：Chat Completions、Responses、Anthropic Messages 和 Gemini 原生。
* **其他所有系列** 可使用 Chat Completions、Responses 和 Anthropic Messages。Messages 请求需带 `anthropic-version` 请求头。拿不准时就用 Chat Completions。

## 快速开始

**`cURL`**

```bash title="cURL"
curl --request POST \
  --url https://direct.beatapi.io/v1/chat/completions \
  --header "Authorization: Bearer $BEATAPI_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "model": "glm-5.3",
  "messages": [{ "role": "user", "content": "Say hello in one sentence." }]
}'
```

**`Python`**

```python title="Python"
import os
from openai import OpenAI

client = OpenAI(api_key=os.environ["BEATAPI_API_KEY"], base_url="https://direct.beatapi.io/v1")
completion = client.chat.completions.create(
    model="glm-5.3",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)
print(completion.choices[0].message.content)
```

**`JavaScript`**

```javascript title="JavaScript"
import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.BEATAPI_API_KEY,
  baseURL: "https://direct.beatapi.io/v1",
});
const completion = await client.chat.completions.create({
  model: "glm-5.3",
  messages: [{ role: "user", content: "Say hello in one sentence." }],
});
console.log(completion.choices[0].message.content);
```

## 查找模型

### `GET /v1/text/models`

公开且匿名：无需密钥。请求地址是 `https://api.beatapi.io/v1/text/models`；`direct.beatapi.io` 只用于调用模型，不提供这个列表。它在 `data.data` 中为每个模型返回一项：

| 字段                                               | 含义                                                                                                                                             |
| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                                             | 作为 `model` 发送的模型 ID。                                                                                                                           |
| `family`                                         | 该模型被路由和计费所属的分组。密钥必须能访问该系列才能调用此模型。                                                                                                              |
| `endpoints`                                      | 该模型所在线路原生支持的格式：`openai`（Chat Completions）、`anthropic`（Messages）、`openai-response`（Responses）。它**不是**你可以调用的全部格式：某个模型文档化了哪些格式，请以各系列页面为准，而不是这个字段。 |
| `context_length`                                 | 上下文窗口，单位 token。未公布时省略。                                                                                                                         |
| `max_output_tokens`                              | 最大输出，单位 token。未公布时省略。                                                                                                                          |
| `input_usd_per_million`、`output_usd_per_million` | 我们的价格，每百万 token 的美元数，已计入折扣。这是基础档：不含长上下文档位。                                                                                                     |
| `discount`                                       | 我们的价格是标价乘以 `discount`（`0.7` 表示标价的七折）。为 1 时省略。                                                                                                  |
| `time_rules`                                     | 高峰时段的价格倍率，含条件以及当前是否生效。模型没有时省略。                                                                                                                 |
| `capabilities`                                   | 自由格式的标签，例如推理或工具。仅供参考，不构成契约。                                                                                                                    |
| `description`                                    | 简短描述。                                                                                                                                          |

免费模型（ID 以 `-free` 结尾）只列出 `id`、`family` 和 `endpoints`：不公布价格、上下文窗口或描述。见[免费模型](/free-models)。

该列表只包含文本模型。

### `GET /v1/models`

需要密钥。返回该密钥能调用的模型，采用 OpenAI 列表结构（`id`、`object`、`created`、`owned_by`、`supported_endpoint_types`），包在 `data` 中。带 `x-api-key` 和 `anthropic-version` 时返回 Anthropic 列表结构；带 `x-goog-api-key` 或 `?key=` 时返回 Gemini 列表结构。密钥所在分组无法访问的模型会被略去，使用免费额度时账户不能使用的模型也会被略去。该接口不限速。

## 流式输出

在 Chat Completions、Responses 和 Messages 上设置 `"stream": true`。Gemini 原生则调用 `:streamGenerateContent?alt=sse`。响应为 `text/event-stream`；不使用流式时为 `application/json`。在调用模型之前发生的失败，会作为带 HTTP 状态码的普通 JSON 错误返回，而不是流事件。

## `max_tokens` 与输出上限

* 网关接受的 `max_tokens`（Chat Completions 和 Messages）、`max_output_tokens`（Responses）的最大值为 1,073,741,823。更大的值返回 `400 bad_request`。
* 网关**不会**把你的值与目录中该模型的 `max_output_tokens` 比较。请保持在该数值以内；超出后会怎样由模型所在线路决定，不作保证。
* `max_tokens` 也用于估算一次请求需要多少余额。过大的值即使实际输出很小，也可能被 `402 insufficient_credits` 拒绝。请按实际需要设置。

## 限流

* 每个账户都有每分钟成功请求数的限额，**随账户累计充值提高**。兑换码、邀请奖励和促销额度不计入。具体数字不以表格公布；请在控制台查看你自己的限额和下一档。
* 请求在运行期间占用名额，失败的请求会归还名额。
* `GET /v1/models` 不限速。
* 免费模型有各自独立的限额，见[免费模型](/free-models)。
* 触达限额时，返回 `429 rate_limit_exceeded`，带 `retry_after_seconds` 和 `Retry-After` 响应头。等待相应时间后重试。

## 错误

文本调用可能在两个阶段失败，两个阶段的响应体不同。[错误码](/errors#text-endpoints)有完整的错误码表和重试策略，这里只给简版。

**1. 调用模型之前。** 在 `/v1/chat/completions`、`/v1/responses` 和 `/v1/messages` 上返回 BeatAPI 错误结构：`code`、`message`、`retryable` 和 `request_id`，`429` 还带 `retry_after_seconds`。Gemini 原生接口（`/v1beta/...`）和 `GET /v1/models` 不属于该结构的范围：它们的错误形如 `{"error":{"message":"... (request id: ...)","type":"beatapi_error","code":...}}`，不带 `retryable` 或 `retry_after_seconds`，但 `429` 仍带 `Retry-After` 响应头。

| HTTP  | 错误码                                 | 原因                                                 |
| ----- | ----------------------------------- | -------------------------------------------------- |
| `401` | `missing_api_key`、`invalid_api_key` | 没有密钥，或密钥错误、已过期、已停用或额度已用尽。                          |
| `403` | `forbidden`                         | 账户使用免费额度且该模型不在免费列表内，请求来源不在密钥的 IP 白名单内，或模型不在密钥的分组里。 |
| `404` | `not_found`                         | 模型不存在，或该密钥无法路由到它。用 `GET /v1/models` 列出可用模型。        |
| `429` | `rate_limit_exceeded`               | 达到账户或免费模型的限额。等待 `retry_after_seconds` 秒。           |

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded: this model allows at most 10 successful requests per minute per account. Retry after 60 seconds.",
    "retryable": true,
    "request_id": "req_abc123",
    "retry_after_seconds": 60
  }
}
```

模型不存在时返回 `404 not_found`：`The requested model is not available to this key: check the model id against GET /v1/models, or retry in a few minutes if it worked before.`

**2. 调用过程中。** 响应体保留 SDK 的原生结构，所以 OpenAI 和 Anthropic SDK 能解析并抛出它们惯常的异常。网关自己给出的拒绝使用 BeatAPI 错误码（`insufficient_credits`、`content_policy_violation`、`bad_request`、`not_found` 或 `internal_error`）：`error.type` 为 `beatapi_error`，错误码在 `error.code`；在 `/v1/messages` 上错误码在 `error.type`。模型一侧的失败会被改写为 `temporary_error`、`upstream_timeout`、`model_unavailable` 或 `rate_limit_exceeded`，并保留原状态码，只是 `502` 和 `504` 会变成 `503`（我方在供应商处的账户故障为 `503 model_unavailable`）。模型给出的英文参数错误，例如上下文过长，会作为一句话原样转出，方便你修正输入。这一阶段每条 `message` 末尾都附有请求 ID。这里没有 `retryable` 字段，`429` 也不保证带 `Retry-After`；请按状态码和错误码判断。见[错误码](/errors#text-endpoints)。

```json
{
  "error": {
    "message": "This API key's remaining quota is below the price of this request. Raise the key's quota in the console or use another key. (request id: req_abc123)",
    "type": "beatapi_error",
    "param": "",
    "code": "insufficient_credits"
  }
}
```

只对 `429`、`500` 和 `503` 重试，并使用退避。

## 全部文本模型

当前所有文本模型，由网关目录生成。点进系列可查看各协议页。价格是 BeatAPI 的实收价，单位为美元 / 100 万 tokens。

| 模型 ID                     | 系列                                              | 上下文（tokens） | 最大输出（tokens） | 输入，美元 / 100 万 tokens | 输出，美元 / 100 万 tokens | 协议                                            |
| ------------------------- | ----------------------------------------------- | ----------- | ------------ | -------------------- | -------------------- | --------------------------------------------- |
| `gpt-6.1-sol`             | [GPT](/text-api/gpt/responses)                  | 1,050,000   | 128,000      | \$0.80               | \$4.00               | Chat Completions、Responses                    |
| `gpt-6-astra`             | [GPT](/text-api/gpt/responses)                  | 1,000,000   | 128,000      | \$4.00               | \$20.00              | Chat Completions、Responses                    |
| `gpt-6-sol`               | [GPT](/text-api/gpt/responses)                  | 1,050,000   | 128,000      | \$0.80               | \$4.00               | Chat Completions、Responses                    |
| `gpt-6-luna`              | [GPT](/text-api/gpt/responses)                  | 1,050,000   | 128,000      | \$0.04               | \$0.20               | Chat Completions、Responses                    |
| `claude-opus-5-5`         | [Claude](/text-api/claude/messages)             | 1,000,000   | 128,000      | \$2.00               | \$10.00              | Messages                                      |
| `claude-sonnet-5-5`       | [Claude](/text-api/claude/messages)             | 1,000,000   | 128,000      | \$1.00               | \$5.00               | Messages                                      |
| `claude-haiku-5-5`        | [Claude](/text-api/claude/messages)             | 1,000,000   | 128,000      | \$0.05               | \$0.25               | Messages                                      |
| `claude-fable-5-1`        | [Claude](/text-api/claude/messages)             | 1,000,000   | 128,000      | \$5.00               | \$25.00              | Messages                                      |
| `gemini-4-argon`          | [Gemini](/text-api/gemini/chat-completions)     | —           | 1,000,000    | \$1.00               | \$5.00               | Chat Completions、Responses、Messages、Gemini 原生 |
| `gemini-3.8-flash`        | [Gemini](/text-api/gemini/chat-completions)     | —           | —            | \$0.375              | \$1.875              | Chat Completions、Responses、Messages、Gemini 原生 |
| `gemini-3.1-pro-preview`  | [Gemini](/text-api/gemini/chat-completions)     | 1,048,576   | 65,536       | \$1.00               | \$6.00               | Chat Completions、Responses、Messages、Gemini 原生 |
| `grok-4.7`                | [Grok](/text-api/grok/chat-completions)         | 500,000     | —            | \$0.70               | \$2.10               | Chat Completions、Responses、Messages           |
| `deepseek-v4.1-flash`     | [DeepSeek](/text-api/deepseek/chat-completions) | —           | —            | \$0.075              | \$0.30               | Chat Completions、Responses、Messages           |
| `deepseek-v4-pro-0813`    | [DeepSeek](/text-api/deepseek/chat-completions) | 1,000,000   | 128,000      | \$0.33               | \$0.99               | Chat Completions、Responses、Messages           |
| `deepseek-v4.1-flash-hc`  | [DeepSeek](/text-api/deepseek/chat-completions) | —           | —            | \$0.105\*            | \$0.42\*             | Chat Completions、Responses、Messages           |
| `deepseek-v4-pro-0813-hc` | [DeepSeek](/text-api/deepseek/chat-completions) | 1,000,000   | 128,000      | \$0.462\*            | \$1.386\*            | Chat Completions、Responses、Messages           |
| `glm-5.3`                 | [GLM](/text-api/glm/chat-completions)           | 1,000,000   | 128,000      | \$0.98               | \$3.08               | Chat Completions、Responses、Messages           |
| `glm-5.3-flash`           | [GLM](/text-api/glm/chat-completions)           | 1,000,000   | 128,000      | \$0.105              | \$0.35               | Chat Completions、Responses、Messages           |
| `glm-5.3-flashx`          | [GLM](/text-api/glm/chat-completions)           | 1,000,000   | 128,000      | \$0.259              | \$0.875              | Chat Completions、Responses、Messages           |
| `qwen3.8-max`             | [Qwen](/text-api/qwen/chat-completions)         | 1,000,000   | 128,000      | \$1.40               | \$4.20               | Chat Completions、Responses、Messages           |
| `qwen3.8-flash`           | [Qwen](/text-api/qwen/chat-completions)         | —           | —            | \$0.105              | \$0.329              | Chat Completions、Responses、Messages           |
| `kimi-k3`                 | [Kimi](/text-api/kimi/chat-completions)         | 1,048,576   | 128,000      | \$2.10               | \$10.50              | Chat Completions、Responses、Messages           |
| `MiniMax-M3`              | [MiniMax](/text-api/minimax/chat-completions)   | 1,048,576   | 128,000      | \$0.21               | \$0.84               | Chat Completions、Responses、Messages           |
| `MiniMax-M3.1-Flash`      | [MiniMax](/text-api/minimax/chat-completions)   | 1,000,000   | —            | \$0.135              | \$0.54               | Chat Completions、Responses、Messages           |
| `mimo-v2.6-flash`         | [MiMo](/text-api/mimo/chat-completions)         | 1,048,576   | 128,000      | \$0.098              | \$0.196              | Chat Completions、Responses、Messages           |
| `mimo-v2.5`               | [MiMo](/text-api/mimo/chat-completions)         | 1,048,576   | 128,000      | \$0.098              | \$0.196              | Chat Completions、Responses、Messages           |
| `hy4-preview`             | [Hunyuan](/text-api/hunyuan/chat-completions)   | —           | —            | \$0.5838             | \$1.7507             | Chat Completions、Responses、Messages           |
| `hy3`                     | [Hunyuan](/text-api/hunyuan/chat-completions)   | 256,000     | 64,000       | \$0.05775\*          | \$0.231\*            | Chat Completions、Responses、Messages           |
| `muse-wonder`             | [Muse](/text-api/muse/chat-completions)         | 1,048,576   | 131,072      | \$4.00               | \$20.00              | Chat Completions、Responses、Messages           |

* 价格为基础档，已计入折扣。长上下文档、缓存命中输入价和缓存写入价不在本表内，见[价格表](https://beatapi.io/pricing)。
* `—` 表示目录未公布该数字。
* \* 模型在高峰时段另有价格倍数；表中显示的是非高峰的基础价。

## 免费模型

免费模型不按 token 计费，有单独的每分钟限额，详见[免费模型](/free-models)。每个免费模型都是最后一列付费模型的免费版本。

| 模型 ID                         | 系列       | 付费版                      | 价格 |
| ----------------------------- | -------- | ------------------------ | -- |
| `deepseek-v4.1-flash-free`    | DeepSeek | `deepseek-v4.1-flash`    | 免费 |
| `deepseek-v4-flash-0731-free` | DeepSeek | `deepseek-v4-flash-0731` | 免费 |
| `glm-5.3-free`                | GLM      | `glm-5.3`                | 免费 |
| `glm-5.3-flash-free`          | GLM      | `glm-5.3-flash`          | 免费 |
| `gemini-3.8-flash-free`       | Gemini   | `gemini-3.8-flash`       | 免费 |

## 旧型号

仍可调用的旧模型 ID 见[旧型号](/text-api/legacy-models)，页内给出应迁移到的当前模型。