> 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 Workflow API

> Build Music Video, Ecommerce Video, and Video Analysis workflows with tasks, polling, and signed webhooks.

# Workflow API

Use a Workflow API when you want a stable BeatAPI capability rather than a single model's contract.

| Workflow ID       | Required input                                             | Key controls                                                                               | Result                                      |
| ----------------- | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------- |
| `music-video`     | Audio plus tier-specific visual references                 | Standard/Premium tier, quality, resolution, mode, subtitles, lip sync, review/edit/compose | Hosted Music Video plus storyboard metadata |
| `ecommerce-video` | 1–7 product images and a 10–60 second duration             | Prompt, aspect ratio, language                                                             | Hosted 1080p product video                  |
| `video-analysis`  | One MP4 or MOV uploaded through `/v1/files`, plus a prompt | Standard/deep depth and output-token budget                                                | Analysis text plus token usage              |

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](/webhooks) for notifications after polling works.

Use [Music Video](/workflow-api/music-video), [Ecommerce Video](/workflow-api/ecommerce-video), or [Video Analysis](/workflow-api/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.

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

```json
{
  "data": {
    "object": "list",
    "data": [
      {
        "id": "music-video",
        "object": "workflow",
        "name": "Music Video API",
        "description": "Generate short music video clips from audio, lyrics, and visual direction."
      },
      {
        "id": "ecommerce-video",
        "object": "workflow",
        "name": "Ecommerce Video API",
        "description": "Generate product ad videos from product images and a short creative brief."
      },
      {
        "id": "video-analysis",
        "object": "workflow",
        "name": "Video Analysis API",
        "description": "Analyze an uploaded video with timestamp-aware multimodal reasoning."
      }
    ]
  }
}
```

| Field                     | Type      | Meaning                                               |
| ------------------------- | --------- | ----------------------------------------------------- |
| `data.object`             | string    | `list`                                                |
| `data.data`               | object\[] | Available launch workflows                            |
| `data.data[].id`          | string    | `music-video`, `ecommerce-video`, or `video-analysis` |
| `data.data[].object`      | string    | `workflow`                                            |
| `data.data[].name`        | string    | Display name                                          |
| `data.data[].description` | string    | Workflow summary                                      |

`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](/video-api) or [Image API](/image-api) when you need one generation operation and want to select the model yourself.