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).

身份验证

AuthorizationBearer

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

请求头

Idempotency-Keystring可选

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.

请求

This endpoint expects an object.
audio_urlstring必需格式: "uri"

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

mv_tierenum可选默认为 standard

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

imageslist of strings可选

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.

promptstring可选<=3000 characters
Optional creative direction for story, setting, performance, camera, lighting, and pacing. Maximum 3000 characters.
languageenum可选
Dialogue and lyric language used by the Standard workflow.
qualityenum可选默认为 standard
Generation quality tier. High quality is unavailable at 540p.
stylestring可选<=200 characters
Optional concise visual style, such as cinematic, anime, documentary, or fashion editorial.
aspect_ratioenum可选
Target output placement. Set explicitly for the destination player or social feed.
resolutionenum可选默认为 720p

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

lip_syncboolean可选默认为 false

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

lip_ref_urlstring可选格式: "uri"

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

add_subtitleboolean可选默认为 false
Burn generated or supplied subtitles into the final video.
subtitle_colorstring可选格式: "^#[0-9A-Fa-f]{6}$"

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

srt_urlstring可选格式: "uri"

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

durationinteger可选10-300

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

compose_modeenum可选默认为 auto

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

mv_modeenum可选

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

lip_ref_urlslist of strings可选

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

响应

Task accepted
dataobject
Accepted or current BeatAPI task state.

错误

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