ナビゲーションにスキップ
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