快速指南

文本、工作流、实时、视频、图片和特效 API 共用一套服务端 API 密钥。先完成下面三个步骤，再查看同步文本响应、任务字段、文件上传、额度限制和生产错误处理。

三步完成第一个任务

1. 创建 API 密钥

在 控制台 → API 密钥 创建密钥，然后在终端中安全载入，避免写入命令历史：

read -rsp "BeatAPI API 密钥: " BEATAPI_API_KEY && echo
export BEATAPI_API_KEY

所有请求使用 https://api.beatapi.io，并携带：

Authorization: Bearer <BEATAPI_API_KEY>

2. 创建任务

下面用 POST /v1/images/tasks 提交最小图片请求：

curl https://api.beatapi.io/v1/images/tasks \
  -X POST \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nano-banana",
    "prompt": "暖色石材展台上的编辑风格产品摄影。"
  }'

合法请求返回 201 Created。保存响应中的 data.id。

3. 轮询结果

curl https://api.beatapi.io/v1/tasks/task_8K2qA \
  -H "Authorization: Bearer $BEATAPI_API_KEY"

将 task_8K2qA 替换为上一步的 data.id。建议每 5–10 秒轮询一次并加入随机抖动。状态为 succeeded 时读取 data.output.media 并停止轮询；状态为 failed 时读取 data.error_code 和 data.error_message 后停止。

选择 API

文本调用会同步返回，或返回 SSE 事件流；实时 API 创建短期 Session。工作流、视频、图片和特效创建操作会返回异步任务，保存 data.id 后轮询统一任务接口。每个 API 密钥对任务查询接口的限制为每分钟 120 次。

GPT-5.6 模型选择、SDK 兼容格式和流式示例请查看 GPT-5.6 指南。

查询任务状态

GET /v1/tasks/{task_id}

状态值

标准任务字段

上传输入文件

POST /v1/files

本地文件无法通过公共 HTTPS URL 访问时，先上传再使用返回的 data.url。每次上传必须带准确的 Content-Length；普通 cURL、浏览器和 SDK 会自动设置。未声明长度的分块上传会在读取正文前被拒绝。

curl https://api.beatapi.io/v1/files \
  -X POST \
  -H "Authorization: Bearer $BEATAPI_API_KEY" \
  -F "file=@./song.mp3" \
  -F "purpose=input"

不支持 PDF、普通文本、octet-stream、不支持的视频封装和 ZIP。BeatAPI 会校验 MIME 与文件签名，并在服务端读取视频时长和尺寸。工作流输入 URL 不能指向 localhost、私有网络或 data URL。

查询用量与限制

GET /v1/usage 是无参数鉴权接口：

curl https://api.beatapi.io/v1/usage \
  -H "Authorization: Bearer $BEATAPI_API_KEY"

重点字段包括当前美元余额 credit_balance、任务总数 total_tasks、结算与退款金额、并发上限及占用，以及按工作流、能力、模型和 API 密钥的统计。余额可能为负；余额不足时不能创建新的付费任务。

错误与重试策略

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Wait 12 seconds, then retry.",
    "retryable": true,
    "request_id": "req_abc123",
    "retry_after_seconds": 12
  }
}

每个错误都带 code、说明原因的英文 message、retryable 和 request_id；429（以及已知等待时间的 503）还带 retry_after_seconds 和 Retry-After 响应头。请按 retryable 分支：为 false 时，不修改请求就会一直失败。

BeatAPI 只公开稳定错误码，不会透传任何第三方的状态码或原始报错。每种失败在创建时和任务接受后分别对应哪个码，以及文本接口的原生错误结构，见错误码。

BeatAPI 不会返回 502 或 504；如果仍然收到，那是网络边缘返回的，正文不是 JSON，请像 503 一样退避重试。

实时会话创建必须使用 1–128 字符的 Idempotency-Key。工作流、图片、视频和特效任务创建可选幂等键，只可对完全相同的逻辑请求复用。

生产检查清单

• 使用准确的 https://api.beatapi.io 域名。
• 永久 API 密钥只放在可信服务端。
• 按对应 API 页面校验字段、枚举、限制和条件组合。
• 启动后台处理前保存任务或会话 ID 与 request_id。
• 轮询加入随机抖动，并在终态或人工动作状态停止。
• 遵守 HTTP 状态码、Retry-After 和 retry_after_seconds。
• JSON 解析前，对 Webhook 原始字节验证签名。
• 记录预留、结算、退款、错误和最终输出 URL。
• 处理摄像头、人脸、声音或参考素材前，查看隐私政策和服务条款。