连接与调用

该填哪个接口地址

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

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

所有请求都返回 404

按可能性从高到低：

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

401 unauthorized

密钥缺失、格式不对、已吊销或已停用。

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

403 forbidden

鉴权通过了，但这个账户或这把密钥无权执行该操作。先检查密钥自身的限制和账户状态，再去看请求内容。

402 insufficient_credits

余额已用尽。这是账户级的，不是按密钥算的 —— 在充值之前，账户上所有付费操作都会失败。如果你有面向用户的服务，这一项值得配告警。

429 rate_limit_exceeded

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

• 请求频率 —— 这把密钥每分钟的请求数超了。按 Retry-After 或 retry_after_seconds 等待。额度随累计充值提升。
• user_concurrency_exceeded —— 同时处理中的任务数超了。立刻重试只会更糟，要等在跑的任务结束。GET /v1/usage 会给出 concurrency.limit 与 concurrency.active。

前者最常见的成因是轮询循环。任务接口对每把密钥的上限是每分钟 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 的每个错误都带这个字段，它能在日志中精确定位到那一次调用。再附上模型编号、端点和大致时间。工单在控制台提交。