连接与调用

该填哪个接口地址

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

填错会让每个请求都返回 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 密钥确认密钥仍然可用。已吊销的密钥会立刻且永久失效。
• 有些客户端改用 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，详见错误码。

402 insufficient_credits

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

429 rate_limit_exceeded

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

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

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

请求超时

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

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

任务一直不结束

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

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

其余状态要么是终态（succeeded、failed），要么确实在处理中。完整状态表见快速指南。

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

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

报障时该提供什么

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