BeatAPIMusic VideoWorkflow API

Music Video

Create a Music Video workflow task from images, audio, and creative controls. If an input is local, [upload a local input](/quick-guide#upload-an-input-file) and use the returned `data.url`. Save `data.id`, [poll the Task](/quick-guide#get-task-status), and follow the [error and retry policy](/quick-guide#errors-and-retry-policy).

Authentication

AuthorizationBearer

Send your API key as Authorization: Bearer <BEATAPI_API_KEY>.

Headers

Idempotency-KeystringOptional

Optional retry key. Reusing the same key with the same request body returns the accepted task; reusing it with a different body returns 409 idempotency_conflict.

Request

This endpoint expects an object.
audio_urlstringRequiredformat: "uri"

Top-level public HTTPS audio URL. Standard accepts 10-180 seconds; Premium accepts 10-300 seconds.

mv_tierenumOptionalDefaults to standard

Select the Music Video tier. Omit this field for Standard; Premium requests must set premium.

imageslist of stringsOptional

Top-level scene images. Standard requires 1-7. Premium sing modes accept 0-6; Premium dance and perform require exactly 6 public HTTPS PNG, JPEG, or WebP URLs.

promptstringOptional<=3000 characters
Optional creative direction for story, setting, performance, camera, lighting, and pacing. Maximum 3000 characters.
languageenumOptional
Dialogue and lyric language used by the Standard workflow.
qualityenumOptionalDefaults to standard
Generation quality tier. High quality is unavailable at 540p.
stylestringOptional<=200 characters
Optional concise visual style, such as cinematic, anime, documentary, or fashion editorial.
aspect_ratioenumOptional
Target output placement. Set explicitly for the destination player or social feed.
resolutionenumOptionalDefaults to 720p

Top-level output resolution. Standard accepts 540p, 720p, or 1080p; Premium is fixed to 720p.

lip_syncbooleanOptionalDefaults to false

Generate lip-synchronized performance. When true, lip_ref_url is required.

lip_ref_urlstringOptionalformat: "uri"

Public HTTPS close-up, front-facing face image used for Standard lip sync.

add_subtitlebooleanOptionalDefaults to false
Burn generated or supplied subtitles into the final video.
subtitle_colorstringOptionalformat: "^#[0-9A-Fa-f]{6}$"

Subtitle text color as a six-digit hexadecimal value. Used when subtitles are enabled.

srt_urlstringOptionalformat: "uri"

Optional public HTTPS .srt subtitle file. Upload a local subtitle through POST /v1/files.

durationintegerOptional10-300

Top-level billing fallback only; detected audio duration wins. Standard accepts 10-180 seconds and Premium accepts 10-300 seconds.

compose_modeenumOptionalDefaults to auto

Auto composes the final Music Video; manual pauses at requires_action so shots can be reviewed or edited before compose.

mv_modeenumOptional

Premium performance mode. Sing modes require lip_ref_urls; dance and perform require exactly six images.

lip_ref_urlslist of stringsOptional

Required for sing and sing_perform; omit for dance and perform. Provide one or two public HTTPS close-up, front-facing face images.

Response

Task accepted
dataobject
Accepted or current BeatAPI task state.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
409
Conflict Error
429
Too Many Requests Error