工作流 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 用量

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

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

完整字段契约见音乐视频、电商视频和视频分析。

查询工作流类型

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

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

{
  "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 或图片 API。