> 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.

# 连接与调用

> 排查接口地址、鉴权失败、404、超时，以及请求根本没到 BeatAPI 的情况。

# 连接与调用

## 该填哪个接口地址

`https://api.beatapi.io`。末尾要不要带 `/v1`，取决于客户端会替你拼上什么。

| 客户端类型                       | 接口地址                                                | 因为它会拼上               |
| --------------------------- | --------------------------------------------------- | -------------------- |
| OpenAI SDK 及 OpenAI 兼容工具    | `https://api.beatapi.io/v1`                         | `/chat/completions`  |
| Anthropic SDK 及 Claude 原生工具 | `https://api.beatapi.io`                            | `/v1/messages`       |
| Gemini SDK 及 Gemini 原生工具    | `https://api.beatapi.io`                            | `/v1beta/models/...` |
| 直接发 HTTP 请求                 | 完整路径，如 `https://api.beatapi.io/v1/chat/completions` | 什么都不拼                |

填错会让每个请求都返回 `404`，而多数客户端会把它显示成「连接失败」，不会告诉你是地址写错了。

## 所有请求都返回 404

按可能性从高到低：

1. **`/v1` 多了或少了。** 见上表。`/v1/v1/chat/completions` 这个路径不存在。
2. **地址结尾多了斜杠**，部分客户端会原样拼接。
3. **请求了不在公开范围内的接口。** BeatAPI 公开的是一份明确的清单 —— 文本、任务、文件上传、用量、回调、实时。清单之外的路径**故意**返回 `404` 而不是报错。`/v1/embeddings`、`/v1/rerank` 与 `/v1/audio/*` 均不提供。
4. **模型编号不存在。** 编号区分大小写，且不带厂商前缀 —— 是 `claude-fable-5-1`，不是 `anthropic/claude-fable-5-1`。

## 401 missing_api_key 或 invalid_api_key

`missing_api_key` 表示没有密钥到达 BeatAPI。`invalid_api_key` 表示收到了密钥，但它错误、已过期、已停用或额度已用尽，错误信息会说明是哪一种。旧客户端可能仍把这两种情况显示为旧名称 `unauthorized`。

* 请求头是 `Authorization: Bearer <密钥>`。少了 `Bearer ` 会被当成格式错误的密钥。
* 粘贴时带进来的空白字符会被算作密钥的一部分。
* 在[控制台 → API 密钥](https://beatapi.io/dashboard/apikeys)确认密钥仍然可用。已吊销的密钥会立刻且永久失效。
* 有些客户端改用 `x-api-key` 或 `x-goog-api-key` 请求头，这是正常的 —— 它们指向的是同一个账户和同一份余额。

## 403 forbidden

鉴权通过了，但这个账户或这把密钥无权执行该操作。先检查密钥自身的限制——IP 白名单和它能调用的模型分组——以及账户状态，再去看请求内容。只有免费额度的账户调用免费列表以外的模型时，会返回 `403 forbidden` 并在信息里写明；充值后即可解锁。

BeatAPI 返回的 `403` 一定是 BeatAPI 自己的判断，模型的回复从来不会以 `403` 原样转给你。（正文为 `error code: 1010` 的 `403` 则来自网络边缘：请显式设置 `User-Agent`。）提示词未通过内容审核时，创建阶段返回 `400 content_policy_violation`，任务接受后则在 `error_code` 里给出 `content_policy_violation`，详见[错误码](/errors)。

## 402 insufficient_credits

余额为零或低于本次请求的价格。**这是账户级的，不是按密钥算的** —— 在充值之前，账户上所有付费操作都会返回 `402`。余额不足在所有接口上一律是 `402`。如果你有面向用户的服务，这一项值得配告警。

## 429 rate_limit_exceeded

两种不同的限制都会返回 `429`，而它们的应对方式正好相反：

* **请求频率** —— 这把密钥每分钟的请求数超了。按 `Retry-After` 或 `retry_after_seconds` 等待。额度随累计充值提升；免费模型例外，它们有单独的固定限额：首次充值前每分钟成功 1 次，任意金额充值后每分钟最多 10 次，与付费额度分开计算。

前者最常见的成因是轮询循环。任务接口对每把密钥的上限是每分钟 120 次请求，仅仅几个并发任务用固定 1 秒轮询就能自己耗光 —— 见[开发指南](/development)。

## 请求超时

`stream: false` 的文本调用在模型写完之前不会返回任何内容，而一次长推理可能要等一会儿。两个办法：

* **改用流式。** `stream: true` 会很快吐出首批字节，连接全程保持活跃。
* **调大客户端超时。** 很多 SDK 默认 30 或 60 秒，对长的非流式请求来说太短了。

## 任务一直不结束

**看状态，不要看时间。** `GET /v1/tasks/{task_id}` 返回的是一组固定状态，其中有两个并不是「还在跑」：

* 音乐视频任务的 `storyboard_ready` 与 `requires_action` 是在**等你**，不是在等模型。一直轮询不会让它们往前走。

其余状态要么是终态（`succeeded`、`failed`），要么确实在处理中。完整状态表见[快速指南](/quick-guide)。

## 本机能连，服务器上连不上

**请在真正发起调用的那台机器上测。** 自部署的平台 —— Dify、Docker 里的 AnythingLLM、CI 运行器 —— 有各自的出网规则。要确认那个容器或主机能访问 `api.beatapi.io`，并在公司代理上放行它。

## 报障时该提供什么

失败响应里的 `request_id`。BeatAPI 的每个错误都带这个字段，它能在日志中精确定位到那一次调用。再附上模型编号、端点和大致时间。工单在[控制台](https://beatapi.io/dashboard)提交。