> 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. # Музыкальное видео > Создайте задачу рабочего процесса Music Video из изображений и аудио, задав творческие параметры. `POST https://api.beatapi.io/v1/music-video/tasks` Создайте задачу рабочего процесса Music Video из изображений и аудио, задав творческие параметры. ## Авторизация `Authorization`   `string`   **обязательный** Передавайте API-ключ BeatAPI как токен Bearer. Создать ключ можно в [панели управления](https://beatapi.io/dashboard). ``` Authorization: Bearer ``` Храните постоянные API-ключи на доверенных серверах. Для тела запроса обязателен `Content-Type: application/json`. Если метод принимает `Idempotency-Key`, этот заголовок необязателен, но рекомендуется для безопасных повторных попыток с точно таким же телом. ## Тело запроса `mv_tier`   `enum`   **необязательный** Выберите уровень Music Video. Для Standard поле можно не передавать; для Premium обязательно укажите `premium`. **Допустимые значения:** `standard`, `premium` \ **По умолчанию:** `"standard"` --- `images`   `string[]`   **необязательный** Основные изображения сцен. Для Standard требуется 1-7 изображений. Режимы пения Premium принимают 0-6 изображений; для dance и perform в Premium требуется ровно 6 общедоступных HTTPS-ссылок на PNG, JPEG или WebP. **Количество:** 0 – 7 элементов --- `audio_url`   `string`   **обязательный** Основная общедоступная HTTPS-ссылка на аудио. Standard принимает 10-180 секунд, Premium — 10-300 секунд. **Формат:** `uri` --- `prompt`   `string`   **необязательный** Необязательные указания по сюжету, месту действия, исполнению, камере, освещению и темпу. Максимум 3000 символов. **Длина:** не более 3000 символов --- `language`   `enum`   **необязательный** Язык диалогов и текста песни в рабочем процессе Standard. **Допустимые значения:** `en`, `zh` --- `quality`   `enum`   **необязательный** Уровень качества генерации. Высокое качество недоступно при 540p. **Допустимые значения:** `standard`, `high` \ **По умолчанию:** `"standard"` --- `style`   `string`   **необязательный** Необязательное краткое описание визуального стиля, например кино, аниме, документальная съёмка или модная фотосессия. **Длина:** не более 200 символов --- `aspect_ratio`   `enum`   **необязательный** Формат размещения готового видео. Задайте его явно под целевой плеер или ленту соцсети. **Допустимые значения:** `1:1`, `16:9`, `9:16`, `4:3`, `3:4` --- `resolution`   `enum`   **необязательный** Основное разрешение результата. Standard принимает 540p, 720p или 1080p; у Premium фиксированное разрешение 720p. **Допустимые значения:** `540p`, `720p`, `1080p` \ **По умолчанию:** `"720p"` --- `lip_sync`   `boolean`   **необязательный** Создать исполнение с синхронизацией движения губ. При true обязателен `lip_ref_url`. **По умолчанию:** `false` --- `lip_ref_url`   `string`   **необязательный** Общедоступная HTTPS-ссылка на крупный фронтальный снимок лица для синхронизации губ в Standard. **Формат:** `uri` --- `add_subtitle`   `boolean`   **необязательный** Встроить сгенерированные или переданные субтитры в итоговое видео. **По умолчанию:** `false` --- `subtitle_color`   `string`   **необязательный** Цвет субтитров в виде шестизначного шестнадцатеричного значения. Применяется, когда субтитры включены. --- `srt_url`   `string`   **необязательный** Необязательный общедоступный файл субтитров `.srt` по HTTPS. Локальный файл сначала загрузите через `POST /v1/files`. **Формат:** `uri` --- `duration`   `integer`   **необязательный** Только запасное значение для расчёта стоимости; приоритет имеет определённая длительность аудио. Standard принимает 10-180 секунд, Premium — 10-300 секунд. **Диапазон:** 10 – 300 --- `compose_mode`   `enum`   **необязательный** Режим auto автоматически собирает готовое Music Video; manual останавливается на `requires_action`, чтобы вы могли проверить или изменить сцены до сборки. **Допустимые значения:** `auto`, `manual` \ **По умолчанию:** `"auto"` --- `mv_mode`   `enum`   **необязательный** Режим исполнения Premium. Для режимов пения нужны `lip_ref_urls`, для dance и perform — ровно шесть `images`. **Допустимые значения:** `sing`, `sing_perform`, `dance`, `perform` --- `lip_ref_urls`   `string[]`   **необязательный** Обязательно для sing и sing_perform; не передавайте для dance и perform. Укажите одну или две общедоступные HTTPS-ссылки на крупные фронтальные снимки лица. **Количество:** 1 – 2 элементов ## Ответ Успешный запрос возвращает HTTP `201`. ```json { "data": { "id": "task_8K2qA", "object": "task", "task_kind": "workflow", "capability_id": "music-video", "capability_version": 1, "workflow": "music-video", "status": "queued", "stage": "queued", "storyboard": { "shots": [] }, "created_at": 1782210000, "updated_at": 1782210000, "completed_at": null, "output": null, "usage": { "credits_reserved": 1.5, "credits_charged": 1.5, "billable_duration_seconds": 15, "credits_settled": 0, "credits_refunded": 0 }, "request_id": "req_abc123", "error_code": null, "error_message": null } } ``` ## Рабочий процесс с ручной проверкой Если `compose_mode` равен `manual`, проверяйте статус до `requires_action`, затем используйте возвращённую раскадровку и ID сцен: 1. Вызовите `POST /v1/music-video/tasks/{task_id}/shots/{shot_id}/edit`, если нужно изменить промпт сцены или референсы Premium. 2. Вызовите `GET /v1/music-video/tasks/{task_id}/shots/{shot_id}/media`, чтобы получить предварительный результат по ссылке для проверки. 3. Когда выбранные сцены готовы, вызовите `POST /v1/music-video/tasks/{task_id}/compose`. После редактирования или запуска сборки продолжайте опрашивать ту же родительскую задачу. При автоматической сборке эти ручные вызовы не нужны. ## Следующий шаг Сохраните `data.id` из ответа о принятии задачи и опрашивайте `GET /v1/tasks/{task_id}` каждые 5–10 секунд, пока `status` не станет `succeeded` или `failed`. Готовые файлы находятся в `data.output.media`. ## Ошибки | Статус | Значение | | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | Некорректный JSON либо недопустимое поле, значение или сочетание параметров (`bad_request`; сообщение указывает поле), либо входные данные отклонены модерацией (`content_policy_violation`). Повтор без изменений не поможет. | | `401` | Ключ не передан (`missing_api_key`), неверен, просрочен, отключён или исчерпал лимит (`invalid_api_key`; точная причина указана в сообщении). Передавайте `Authorization: Bearer `; ключ работает с префиксом `sk-` и без него. Повторять без исправления не следует. | | `402` | Недостаточно средств (`insufficient_credits`): баланс равен нулю или меньше стоимости запроса. Пополните баланс, затем отправьте запрос снова. До пополнения повтор не поможет. | | `403` | Операция запрещена ключу или аккаунту (`forbidden`): например, модель недоступна за счёт регистрационного бонуса (пополнение открывает доступ), IP-адрес не входит в разрешённый список ключа или модель недоступна его группе. Повторять без исправления не следует. | | `409` | В течение 24 часов `Idempotency-Key` уже использован с другим телом или путём запроса либо первый запрос с этим ключом ещё выполняется (`idempotency_conflict`). Повтор без изменений не поможет. | | `429` | Слишком много запросов (`rate_limit_exceeded`, в том числе лимит бесплатной модели). Повторите через число секунд из `Retry-After` (также указано в `error.retry_after_seconds`). | | `500` | Непредвиденная внутренняя ошибка (`internal_error`). Запрос можно повторить; если ошибка сохраняется, сохраните `request_id` для поддержки. | | `503` | Запрос не удалось выполнить (`processing_unavailable`, `processing_timeout`, `processing_failed` или `result_transfer_failed`). Средства не списаны. Повторяйте с увеличивающейся задержкой; у 503 нет заголовка `Retry-After` и поля `retry_after_seconds`. BeatAPI не возвращает 502 и 504. |