BeatAPI 工作流 API

工作流 API

当你需要稳定的 BeatAPI 能力，而不想绑定某个上游供应商契约时，使用工作流 API。

工作流 ID必填输入主要控制项结果
music-video音频和对应套餐的视觉参考标准版 standard / 高级版 premium、质量、分辨率、模式、字幕、口型同步、审核/编辑/合成托管音乐视频和分镜信息
ecommerce-video1–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 接收通知。

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

查询工作流类型

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

$curl https://api.beatapi.io/v1/workflows
1{
2  "data": {
3    "object": "list",
4    "data": [
5      { "id": "music-video", "object": "workflow", "name": "Music Video API" },
6      { "id": "ecommerce-video", "object": "workflow", "name": "Ecommerce Video API" },
7      { "id": "video-analysis", "object": "workflow", "name": "Video Analysis API" }
8    ]
9  }
10}

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

通用生产规则

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

只需要单次生成并希望自行选择模型时，使用视频 API 或图片 API。