文本 API

• 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、上下文窗口、输出上限和价格。

选择协议

Base URL 与鉴权

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

各模型该用哪种格式

• 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 --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." }]
}'

查找模型

GET /v1/text/models

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

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

该列表只包含文本模型。

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 不限速。
• 免费模型有各自独立的限额，见免费模型。
• 触达限额时，返回 429 rate_limit_exceeded，带 retry_after_seconds 和 Retry-After 响应头。等待相应时间后重试。

错误

文本调用可能在两个阶段失败，两个阶段的响应体不同。错误码有完整的错误码表和重试策略，这里只给简版。

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 响应头。

{
  "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；请按状态码和错误码判断。见错误码。

{
  "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。

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

免费模型

免费模型不按 token 计费，有单独的每分钟限额，详见免费模型。每个免费模型都是最后一列付费模型的免费版本。

旧型号

仍可调用的旧模型 ID 见旧型号，页内给出应迁移到的当前模型。