Create Music Video

Music Video requires public HTTPS image URLs and a public HTTPS audio URL.
Prompt, language, quality, style, lip reference, subtitle, and format
controls are optional. BeatAPI detects the audio duration before task
creation and charges the detected billable duration at the selected
per-second customer-credit rate. If audio duration cannot be detected,
duration is used as the billing fallback.

Input limits:

Images must contain 1-7 public HTTPS URLs.

Use png, jpg, jpeg, or webp images; each image should be 50 MB or smaller.

Image aspect ratio should be between 1:4 and 4:1.

Audio must be a public HTTPS mp3, wav, aac, or m4a URL between 10 and 180 seconds.

The audio file should be 50 MB or smaller.

prompt is optional and must be at most 3000 characters.

lip_ref_url, when provided, must be a public HTTPS image URL. Use a clear, front-facing close-up face reference for best lip-sync results.

srt_url, when provided, must point to an .srt subtitle file.

duration is only a billing fallback when BeatAPI cannot detect the audio length; it must be 10-180 seconds and cannot override a detected audio duration.

BeatAPI validates URL shape, text limits, enum values, combination
limits, and audio duration at task creation. Files uploaded through
/v1/files are also checked for type and size before they can be used.
Third-party media URLs must follow the same media requirements and may
be rejected during processing if invalid.

Customer pricing:

MV 540p standard: 4 credits/s

MV 720p standard: 5 credits/s

MV 1080p standard: 6 credits/s

lip_sync add-on: +2 credits/s

MV 720p high: 16 credits/s

MV 1080p high: 18 credits/s

Ecommerce Video 1080p: 15 credits/s

Combination limits:

quality=high is not supported with resolution=540p.

lip_sync=true is not supported with resolution=540p.

It returns a task id immediately; poll the task or receive webhook
events for completion.

By default, Music Video responses return the final hosted video plus
storyboard shot ids and metadata. Shot videos are stored only when you
request a specific shot media URL or when a shot edit finishes.

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

curl --location 'https://api.beatapi.io/v1/music-video/tasks' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "images": [ "https://media.beatapi.io/samples/neon-singer.png" ], "audio_url": "https://media.beatapi.io/samples/neon-singer-preview.mp3", "prompt": "Neon rooftop performance with metro cutaways and cinematic light trails.", "language": "en", "quality": "standard", "resolution": "720p", "compose_mode": "auto" }'

{ "data": { "id": "task_8K2qA", "object": "task", "workflow": "music-video", "status": "queued", "stage": "queued", "storyboard": { "shots": [] }, "created_at": 1782210000, "updated_at": 1782210000, "completed_at": null, "output": null, "usage": { "credits_reserved": 75, "credits_charged": 75, "billable_duration_seconds": 15, "credits_settled": 0, "credits_refunded": 0 }, "request_id": "req_abc123", "error_code": null, "error_message": null } }

Create Music Video

Request

Responses