跳到导航
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 and use the returned data.url. Save data.id, poll the Task, and follow the error 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
403
Forbidden Error
409
Conflict Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error