Музыкальное видео

POST https://api.beatapi.io/v1/music-video/tasks

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

Авторизация

Authorization   string   обязательный

Передавайте API-ключ BeatAPI как токен Bearer. Создать ключ можно в панели управления.

Authorization: Bearer <BEATAPI_API_KEY>

Храните постоянные API-ключи на доверенных серверах. Для тела запроса обязателен Content-Type: application/json. Если метод принимает Idempotency-Key, этот заголовок необязателен, но рекомендуется для безопасных повторных попыток с точно таким же телом.

Тело запроса

mv_tier   enum<string>   необязательный

Выберите уровень 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<string>   необязательный

Язык диалогов и текста песни в рабочем процессе Standard.

Допустимые значения: en, zh

quality   enum<string>   необязательный

Уровень качества генерации. Высокое качество недоступно при 540p.

Допустимые значения: standard, high
По умолчанию: "standard"

style   string   необязательный

Необязательное краткое описание визуального стиля, например кино, аниме, документальная съёмка или модная фотосессия.

Длина: не более 200 символов

aspect_ratio   enum<string>   необязательный

Формат размещения готового видео. Задайте его явно под целевой плеер или ленту соцсети.

Допустимые значения: 1:1, 16:9, 9:16, 4:3, 3:4

resolution   enum<string>   необязательный

Основное разрешение результата. 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<string>   необязательный

Режим auto автоматически собирает готовое Music Video; manual останавливается на requires_action, чтобы вы могли проверить или изменить сцены до сборки.

Допустимые значения: auto, manual
По умолчанию: "auto"

mv_mode   enum<string>   необязательный

Режим исполнения 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.

{
  "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.

Ошибки