> 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

> 使用统一任务、轮询和签名 Webhook 构建音乐视频、电商视频和视频分析工作流。

# 工作流 API

当你需要稳定的 BeatAPI 能力，而不想绑定某个单一模型的契约时，使用工作流 API。

| 工作流 ID            | 必填输入                            | 主要控制项                                                     | 结果             |
| ----------------- | ------------------------------- | --------------------------------------------------------- | -------------- |
| `music-video`     | 音频和对应套餐的视觉参考                    | 标准版 `standard` / 高级版 `premium`、质量、分辨率、模式、字幕、口型同步、审核/编辑/合成 | 托管音乐视频和分镜信息    |
| `ecommerce-video` | 1–7 张商品图和 10–60 秒时长             | 提示词、宽高比、语言                                                | 托管的 1080p 商品视频 |
| `video-analysis`  | 通过 `/v1/files` 上传的 MP4/MOV 和提示词 | `standard` / `deep` 深度及输出 Token 预算                        | 分析文本和 Token 用量 |

三个工作流都是异步任务：

1. 创建任务并保存 `data.id`。
2. 每 5–10 秒轮询 `GET /v1/tasks/{task_id}`。
3. 在 `succeeded` 或 `failed` 时停止；音乐视频人工审核可能停在 `requires_action`。
4. 轮询跑通后，再使用签名 [Webhook](/webhooks) 接收通知。

完整字段契约见[音乐视频](/workflow-api/music-video)、[电商视频](/workflow-api/ecommerce-video) 和[视频分析](/workflow-api/video-analysis)。

## 查询工作流类型

`GET /v1/workflows` 无需鉴权，也没有参数。

```bash
curl https://api.beatapi.io/v1/workflows
```

```json
{
  "data": {
    "object": "list",
    "data": [
      { "id": "music-video", "object": "workflow", "name": "Music Video API" },
      { "id": "ecommerce-video", "object": "workflow", "name": "Ecommerce Video API" },
      { "id": "video-analysis", "object": "workflow", "name": "Video Analysis API" }
    ]
  }
}
```

`429 rate_limit_exceeded` 可能包含 `Retry-After` 和 `error.retry_after_seconds`，至少等待指定时间后再试。

## 通用生产规则

* 基础地址为 `https://api.beatapi.io`。
* 永久 API 密钥只保存在可信服务端。
* 输入必须能从公网访问；本地素材先调用 `POST /v1/files`。
* 创建请求会预留 USD 余额并返回统一任务结构。
* 记录 `request_id`、用量、状态、错误和最终输出 URL。
* 对没有明确幂等头的未知创建结果，不要盲目重试。

只需要单次生成并希望自行选择模型时，使用[视频 API](/video-api) 或[图片 API](/image-api)。