Workflow API

Use a Workflow API when you want a stable BeatAPI capability rather than an upstream provider contract.

Both workflows are asynchronous:

1. Create a task and save data.id.
2. Poll GET /v1/tasks/{task_id} every 5–10 seconds.
3. Stop on succeeded or failed; Music Video manual review can pause at requires_action.
4. Use signed webhooks for notifications after polling works.

Use Music Video, Ecommerce Video, or Video Analysis for the complete field-level contracts.

List workflow types

GET /v1/workflows

This public endpoint has no parameters and does not require authentication.

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

1
{
2
  "data": {
3
    "object": "list",
4
    "data": [
5
      {
6
        "id": "music-video",
7
        "object": "workflow",
8
        "name": "Music Video API",
9
        "description": "Generate short music video clips from audio, lyrics, and visual direction."
10
      },
11
      {
12
        "id": "ecommerce-video",
13
        "object": "workflow",
14
        "name": "Ecommerce Video API",
15
        "description": "Generate product ad videos from product images and a short creative brief."
16
      },
17
      {
18
        "id": "video-analysis",
19
        "object": "workflow",
20
        "name": "Video Analysis API",
21
        "description": "Analyze an uploaded video with timestamp-aware multimodal reasoning."
22
      }
23
    ]
24
  }
25
}

429 rate_limit_exceeded can include Retry-After and error.retry_after_seconds; wait at least that long before retrying.

Shared production rules

• Base URL: https://api.beatapi.io.
• Keep the permanent API key on a trusted server.
• Inputs must be public and reachable; use POST /v1/files for local assets.
• Create requests reserve credits and return a normalized Task envelope.
• Record request_id, usage, status, errors, and final output URLs.
• Do not blindly retry an uncertain create request that lacks a documented idempotency header.

Choose the model-level Video API or Image API when you need one generation operation and want to select the model yourself.