> 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

> Создавайте процессы Music Video, Ecommerce Video и Video Analysis с задачами, проверкой статуса и подписанными вебхуками.

# Workflow API

Используйте Workflow API, если вам нужна стабильная возможность BeatAPI, а не контракт отдельной модели.

| ID процесса       | Обязательные данные                                       | Основные настройки                                                                                         | Результат                                     |
| ----------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| `music-video`     | Аудио и визуальные референсы выбранного уровня            | Standard/Premium, качество, разрешение, режим, субтитры, синхронизация губ, просмотр/редактирование/сборка | Музыкальное видео по URL и данные раскадровки |
| `ecommerce-video` | 1–7 изображений товара и длительность 10–60 секунд        | Промпт, соотношение сторон, язык                                                                           | Видео товара 1080p по URL                     |
| `video-analysis`  | Один MP4 или MOV, загруженный через `/v1/files`, и промпт | Глубина Standard/deep и лимит выходных токенов                                                             | Текст анализа и данные о токенах              |

Эти процессы асинхронные:

1. Создайте задачу и сохраните `data.id`.
2. Проверяйте `GET /v1/tasks/{task_id}` каждые 5–10 секунд.
3. Прекратите опрос при `succeeded` или `failed`. Ручная проверка Music Video может приостановить процесс в `requires_action`.
4. После настройки опроса подключите подписанные [вебхуки](/webhooks) для уведомлений.

Полные контракты полей приведены в [Music Video](/workflow-api/music-video), [Ecommerce Video](/workflow-api/ecommerce-video) и [Video Analysis](/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",
        "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."
      }
    ]
  }
}
```

| Поле                      | Тип       | Значение                                              |
| ------------------------- | --------- | ----------------------------------------------------- |
| `data.object`             | string    | `list`                                                |
| `data.data`               | object\[] | Доступные рабочие процессы                            |
| `data.data[].id`          | string    | `music-video`, `ecommerce-video` или `video-analysis` |
| `data.data[].object`      | string    | `workflow`                                            |
| `data.data[].name`        | string    | Отображаемое название                                 |
| `data.data[].description` | string    | Описание рабочего процесса                            |

`429 rate_limit_exceeded` может содержать `Retry-After` и `error.retry_after_seconds`. Перед повтором подождите не меньше указанного времени.

## Общие правила для рабочей среды

* Базовый адрес: `https://api.beatapi.io`.
* Храните постоянный API-ключ на доверенном сервере.
* Входные файлы должны быть общедоступны по сети. Для локальных материалов используйте `POST /v1/files`.
* При создании резервируются средства и возвращается объект Task единого формата.
* Записывайте `request_id`, использование, статус, ошибки и конечные URL результатов.
* Не повторяйте вслепую запрос создания с неизвестным исходом, если у него нет документированного заголовка идемпотентности.

Если нужна одна операция генерации с самостоятельным выбором модели, используйте [Video API](/video-api) или [Image API](/image-api).