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

# BeatAPI 快速指南

> 创建 API 密钥、调用 GPT-5.6、提交图片或视频任务、轮询结果、上传本地素材、配置 Webhook，并安全处理生产重试。

# 快速指南

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

## 三步完成第一个任务

### 1. 创建 API 密钥

在 [控制台 → API 密钥](https://beatapi.io/dashboard/apikeys) 创建密钥，然后在终端中安全载入，避免写入命令历史：

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

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

```http
Authorization: Bearer <BEATAPI_API_KEY>
```

### 2. 创建任务

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

```bash
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. 轮询结果

```bash
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` 后停止。

> **Note**
>
> 永久 API 密钥只能放在可信服务端，不能写进浏览器、移动端、公开脚本、日志或截图。实时 API 的浏览器端只接收由你的服务端创建的短期 `client_secret`。

## 选择 API

| API         | 创建操作                             | 输入                          | 结果              |
| ----------- | -------------------------------- | --------------------------- | --------------- |
| 文本（GPT-5.6） | `POST /v1/responses`             | 文本、图片、工具和推理控制               | 同步 JSON 或流式文本响应 |
| 音乐视频工作流     | `POST /v1/music-video/tasks`     | 音频和对应套餐要求的视觉参考              | 完整音乐视频和分镜信息     |
| 电商视频工作流     | `POST /v1/ecommerce-video/tasks` | 商品图片、时长和创意说明                | 完整商品视频          |
| 视频分析工作流     | `POST /v1/video-analysis/tasks`  | 已上传视频、分析提示词和分析深度            | 分析文本和 Token 用量  |
| 实时 API      | `POST /v1/realtime/sessions`     | 浏览器来源、固定时长和实时 `MediaStream` | 实时生成的 WebRTC 视频 |
| 视频 API      | `POST /v1/videos/tasks`          | 模型专属提示词和媒体参考                | 一个托管视频          |
| 图片 API      | `POST /v1/images/tasks`          | 模型专属提示词和可选参考图               | 一个托管图片          |
| 特效 API      | `POST /v1/effects/tasks`         | 已发布特效 ID、图片和支持的参数           | 一个托管图片或视频特效结果   |

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

GPT-5.6 模型选择、SDK 兼容格式和流式示例请查看 [GPT-5.6 指南](/text-api/gpt-5-6)。

## 查询任务状态

`GET /v1/tasks/{task_id}`

| 参数        | 位置 | 类型     | 必填 | 规则                 |
| --------- | -- | ------ | -- | ------------------ |
| `task_id` | 路径 | string | 是  | 使用创建响应中的 `data.id` |

### 状态值

| 状态                 | 含义         | 客户端动作                  |
| ------------------ | ---------- | ---------------------- |
| `queued`           | 已接受，等待处理   | 继续轮询                   |
| `processing`       | 正在生成       | 继续轮询                   |
| `storyboard_ready` | 音乐视频分镜已就绪  | 自动流程可继续；需要时检查          |
| `requires_action`  | 音乐视频等待人工审核 | 编辑或合成镜头                |
| `editing`          | 正在编辑音乐视频镜头 | 继续轮询                   |
| `composing`        | 正在合成音乐视频   | 继续轮询                   |
| `succeeded`        | 托管结果已就绪    | 读取 `data.output` 并停止轮询 |
| `failed`           | 任务失败结束     | 读取错误和退款字段并停止轮询         |

### 标准任务字段

| 字段                             | 类型             | 出现条件    | 含义                                                 |
| ------------------------------ | -------------- | ------- | -------------------------------------------------- |
| `id`                           | string         | 始终      | 稳定任务 ID                                            |
| `object`                       | string         | 始终      | 固定为 `task`                                         |
| `task_kind`                    | string         | 始终      | `workflow`、`effect`、`image` 或 `video`              |
| `capability_id`                | string         | 始终      | 稳定的工作流、特效或模型 ID                                    |
| `capability_version`           | integer 或 null | 始终      | 版本化能力的不可变版本                                        |
| `workflow`                     | string         | 工作流任务   | `music-video`、`ecommerce-video` 或 `video-analysis` |
| `effect_id`                    | string         | 特效任务    | 稳定特效 ID                                            |
| `effect_version`               | integer        | 特效任务    | 已选择的不可变版本                                          |
| `media_type`                   | string         | 图片/视频任务 | `image` 或 `video`                                  |
| `model`                        | string         | 图片/视频任务 | 稳定公开模型别名                                           |
| `status`                       | string         | 始终      | 当前生命周期状态                                           |
| `stage`                        | string         | 始终      | 当前处理阶段                                             |
| `storyboard`                   | object         | 音乐视频    | 可用时返回分镜信息                                          |
| `created_at` / `updated_at`    | integer        | 始终      | Unix 时间戳                                           |
| `completed_at`                 | integer 或 null | 始终      | 终态 Unix 时间戳                                        |
| `output`                       | object 或 null  | 始终      | 成功前为 `null`                                        |
| `usage`                        | object         | 始终      | USD 计费和可计费时长                                       |
| `request_id`                   | string         | 始终      | 客服与排障关联 ID                                         |
| `error_code` / `error_message` | string 或 null  | 始终      | 机器可读和人类可读错误                                        |

> **Note**
>
> 为保持 API 兼容，公开字段仍使用 `credits_reserved` 等名称。所有 Credit 与余额数值都是美元账本金额，1 Credit 等于 1 美元，控制台使用 `$` 展示同一数值。

| 字段                                | 类型         | 含义                |
| --------------------------------- | ---------- | ----------------- |
| `usage.credits_reserved`          | number     | 为操作预留的 USD 金额     |
| `usage.credits_charged`           | number     | 接受任务时扣取的 USD 金额   |
| `usage.billable_duration_seconds` | integer，可选 | 用于计费的时长           |
| `usage.credits_settled`           | number     | 成功后最终结算的 USD 金额   |
| `usage.credits_refunded`          | number     | 符合条件的失败所退回金额      |
| `output.media`                    | object\[]  | 托管结果文件            |
| `output.media[].type`             | string     | `image` 或 `video` |
| `output.media[].url`              | string     | 托管结果 URL          |
| `output.media[].mime_type`        | string     | 结果 MIME 类型        |
| `output.r2_url`                   | string     | 主要托管结果 URL        |

## 上传输入文件

`POST /v1/files`

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

| 字段        | 类型     | 必填 | 默认值     | 规则                              |
| --------- | ------ | -- | ------- | ------------------------------- |
| `file`    | binary | 是  | —       | 单个支持文件；视频最大 100 MB，其他类型最大 50 MB |
| `purpose` | string | 否  | `input` | 目前只支持 `input`                   |

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

| 素材     | 扩展名               | MIME 类型                                            | 附加规则                                     |
| ------ | ----------------- | -------------------------------------------------- | ---------------------------------------- |
| 图片     | PNG、JPG/JPEG、WebP | `image/png`、`image/jpeg`、`image/webp`              | 最大 50 MB                                 |
| 音频     | MP3、WAV、AAC、M4A   | `audio/mpeg`、`audio/wav`、`audio/aac`、`audio/mp4`   | 最大 50 MB；10–300 秒                        |
| 字幕     | SRT               | `application/x-subrip`；仅 `.srt` 文件可使用 `text/plain` | 最大 50 MB                                 |
| 动作参考视频 | MP4、MOV           | `video/mp4`、`video/quicktime`                      | 最大 100 MB；3–30 秒；用于 Kling Motion Control |

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

## 查询用量与限制

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

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

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

## 错误与重试策略

```json
{
  "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 只公开稳定错误码，不会透传任何第三方的状态码或原始报错。每种失败在创建时和任务接受后分别对应哪个码，以及文本接口的原生错误结构，见[错误码](/errors)。

| 错误码                                        | 含义                                                                | 客户端动作                                    |
| ------------------------------------------ | ----------------------------------------------------------------- | ---------------------------------------- |
| `bad_request`                              | JSON 格式错误，或字段、组合、格式、URL 或限制不合法（创建时，或已接受任务的参数、输入被模型拒绝），错误信息会点名字段   | 修正请求后再试                                  |
| `missing_api_key`                          | 请求没有带 API 密钥                                                      | 用 `Authorization: Bearer <key>` 发送       |
| `invalid_api_key`                          | 密钥错误、已过期、已停用或额度已用尽，错误信息会说明是哪一种                                    | 到控制台核对当前有效的密钥                            |
| `unauthorized`                             | `401` 的旧名称，2026-09-29 起由 `missing_api_key` 和 `invalid_api_key` 取代 | 按 `invalid_api_key` 处理                   |
| `forbidden`                                | 密钥或账户无权执行该操作，例如免费额度不能调用该模型、密钥的 IP 白名单或分组不允许                       | 查看错误信息；免费额度账户充值后解锁全部模型                   |
| `not_found`                                | 模型或能力不存在，或资源不存在、不属于当前密钥所在账户                                       | 检查 ID 和归属                                |
| `insufficient_credits`                     | 余额不足：账户余额为零或低于本次请求的价格                                             | 充值后再发送付费请求                               |
| `idempotency_conflict`                     | 同一幂等键对应不同请求体                                                      | 相同逻辑请求复用原键，否则换新键                         |
| `user_concurrency_exceeded`                | 活跃任务已达并发上限                                                        | 等待任务结束或提升额度                              |
| `rate_limit_exceeded`                      | 超过请求频率，包括免费模型的限额                                                  | 遵守 `Retry-After` 或 `retry_after_seconds` |
| `content_policy_violation`                 | 提示词、媒体或生成结果未通过内容审核                                                | 修改内容后重新提交                                |
| `processing_unavailable`                   | 模型暂时不可用或容量已满（与你的请求频率无关）                                           | 稍后退避重试；已接受任务继续轮询                         |
| `processing_failed` / `processing_timeout` | 我方原因导致处理失败，或超时                                                    | 停止轮询，检查错误与退款，退避后新建任务                     |
| `result_transfer_failed`                   | 结果未能保存到一方存储                                                       | 检查退款后按需重试                                |
| `invalid_signature`                        | Webhook 签名或时间戳无效                                                  | 用原始字节、时间戳和 Secret 重新验证                   |
| 实时 API 专属错误                                | 未启用、无容量、会话过期、来源或密钥无效                                              | 按错误创建新会话或修正来源和权限                         |
| `internal_error`                           | BeatAPI 内部异常                                                      | 保留 `request_id`，重试一次，仍失败请联系支持            |

| HTTP  | 错误码                                                                                        | `retryable` | 客户端动作                         |
| ----- | ------------------------------------------------------------------------------------------ | ----------- | ----------------------------- |
| `400` | `bad_request`、`content_policy_violation`                                                   | `false`     | 修正字段、组合、格式、URL、限制或输入内容        |
| `401` | `missing_api_key`、`invalid_api_key`                                                        | `false`     | 补上或更换 Bearer 密钥               |
| `402` | `insufficient_credits`                                                                     | `false`     | 充值后再发送付费请求                    |
| `403` | `forbidden` 或实时会话来源错误                                                                      | `false`     | 检查权限或浏览器来源                    |
| `404` | `not_found`                                                                                | `false`     | 检查模型、reference 或 ID 及其归属      |
| `409` | `idempotency_conflict`                                                                     | `false`     | 只对完全相同的请求体复用幂等键               |
| `429` | `rate_limit_exceeded`、`user_concurrency_exceeded`                                          | `true`      | 遵守 `Retry-After`，或等待运行中的任务结束  |
| `500` | `internal_error`                                                                           | `true`      | 保留 `request_id`；重试一次，仍失败请联系支持 |
| `503` | `processing_unavailable`、`processing_timeout`、`processing_failed`、`result_transfer_failed` | `true`      | 退避重试                          |

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。
* 处理摄像头、人脸、声音或参考素材前，查看[隐私政策](https://beatapi.io/privacy-policy)和[服务条款](https://beatapi.io/terms-of-service)。