AI Music Video Generator API (MV 2.0)

Turn a song into a full music video: lip-synced singing, performance and dance shots, scenes and cuts planned automatically. Compatible with Vidu's one-click MV 2.0 API.

API key

Enter your API key to submit or inspect tasks.

Create a music video

Fields map directly onto POST /ent/v2/one-click/premium_mv.

ModeThe singer sings to camera, lips synced to the vocal. Needs a singer photo.

Song (audio) (1/1)

1Upload

10–360 seconds. MP3, WAV, AAC or M4A. Instrumentals work too.

Singer photo (1/1)

1Upload

A clear photo of the singer's face. One singer for now.

Reference images (optional) (0/6)

None added.

Optional scene or style images. Singer portraits in this list are ignored in sing modes.

Uploads are limited to 30MB each — use a URL for larger files.

StyleOptional, up to 500 characters.PromptOptional extra direction, up to 3000 characters.

Aspect ratioScene modeauto fills in missing scenes.

Or inspect an existing task

Request log

Every call this page makes to the API, in order, most recent first.

Nothing sent yet.

Overview

Turn a song into a music video. Upload the audio, optionally a singer photo and reference images, and the service analyses the song, plans the shots, renders each segment and stitches them back to your original track. The API is compatible with Vidu's one-click MV 2.0 (premium_mv): same paths, request fields and response fields — change the base URL and the auth header and existing Vidu clients keep working.

Item	Value
Base URL	https://api.foxaihub.com/api/v2/ent/v2
Auth header	api-key: <your key> (Vidu's Authorization: Token is not supported)
Format	JSON requests and responses
Flow	POST to create a task, then poll GET until state is success or failed (or use callback_url)

Create a task

POST/ent/v2/one-click/premium_mv

Field	Type	Required	Notes
premium_mv_mode	string	yes	sing, sing_perform, perform or dance. See the modes table below.
audio_url	string	yes	The song: an http(s) URL or base64 (data URLs accepted). 10–360 seconds; mp3, wav, aac or m4a; up to 30MB. Instrumentals are allowed.
lip_ref_urls	string[]	sing, sing_perform	Singer portrait, URL or base64. Exactly one for now — two returns MultipleSingersNotSupported. Ignored for perform and dance.
images	string[]	perform, dance	Up to 6 reference images (URL or base64). Each is used as a scene, a style reference or a performer, decided automatically.
style	string	no	Free-text visual style, up to 500 characters.
prompt	string	no	Extra direction for the whole video, up to 3000 characters.
language	string	no	Recorded only. The language is detected from the audio.
scene_mode	string	no	auto (default) fills in missing scenes with generated ones; user_only uses only your images and never generates scenes (images must then contain scene images).
aspect_ratio	string	no	16:9 (default), 9:16, 1:1, 4:3 or 3:4.
resolution	string	no	720p (default). 1080p is rejected for now.
callback_url	string	no	https URL. We POST the same body as the query endpoint on every state change; failed deliveries are retried 3 times.
payload	string	no	Up to 1024 characters, returned unchanged when you query the task.
add_subtitle, subtitle_color	—	no	Accepted for Vidu compatibility, currently ignored.

Example request

curl -X POST 'https://api.foxaihub.com/api/v2/ent/v2/one-click/premium_mv' \
  -H 'api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "premium_mv_mode": "sing",
    "audio_url": "https://example.com/song.mp3",
    "lip_ref_urls": ["https://example.com/singer.png"],
    "style": "cinematic, neon city at night",
    "aspect_ratio": "16:9"
  }'

Response

{ "id": "7f0c2d6e-3b1a-4c1e-9a53-0f6c1d2e8b11", "state": "created", "credits": 0 }

id is the task id for the query endpoint. Pricing is read from your account when the task is created and billing is handled by the platform; if a task fails, the amount is refunded in full.

Modes

premium_mv_mode	Needs	What you get
sing	lip_ref_urls	The singer sings to camera with lips synced to the vocal.
sing_perform	lip_ref_urls	The singer sings on camera, cut with performance and scene shots.
perform	images	Performance and scene footage built from your reference images; no lip sync.
dance	images	A dance-driven video built from your reference images.

For instrumentals the service may fall back to a different mode; the one actually used is returned as effective_mode.

Query a task

GET/ent/v2/tasks/{id}/creations

Poll every 5–10 seconds. A full video usually takes several minutes, depending on the song length. Only the task's owner can read it; anything else returns 404.

Example request

curl 'https://api.foxaihub.com/api/v2/ent/v2/tasks/7f0c2d6e-3b1a-4c1e-9a53-0f6c1d2e8b11/creations' \
  -H 'api-key: YOUR_API_KEY'

Response (success)

{
  "id": "7f0c2d6e-3b1a-4c1e-9a53-0f6c1d2e8b11",
  "state": "success",
  "err_code": "",
  "credits": 480,
  "payload": "",
  "bgm": false,
  "off_peak": false,
  "creations": [
    {
      "id": "7f0c2d6e-3b1a-4c1e-9a53-0f6c1d2e8b11",
      "url": "https://cdn.example.com/mv2/.../final.mp4",
      "cover_url": "https://cdn.example.com/mv2/.../cover.jpg",
      "watermarked_url": "https://cdn.example.com/mv2/.../final.mp4"
    }
  ],
  "stage": "completed",
  "held": false,
  "stop_after": null,
  "error": null,
  "effective_mode": "sing",
  "progress": { "segments_done": 12, "segments_total": 12 },
  "scenes": [{ "scene_id": "s1", "name": "Neon street", "image_url": "https://...", "source": "generated" }],
  "segments": [
    {
      "segment_id": "seg_01", "start": 0, "end": 8.5, "scene_id": "s1",
      "status": "completed", "video_url": "https://...",
      "shots": [{ "start": 0, "end": 4.2, "role": "singer", "lyric_text": "..." }]
    }
  ]
}

States and fields

state	stage	Meaning
created	pending	Queued.
processing	analyzing, analyzed	Analysing the song: lyrics, vocals, structure.
processing	planning, planned	Writing the shot plan and generating scene images.
processing	rendering, rendered	Rendering each segment (see progress).
processing	composing	Stitching the segments onto the original audio.
success	completed	creations[0].url is the final MP4.
failed	failed	See err_code and error.

Field	Notes
id, state, err_code, credits, payload, bgm, off_peak, creations	Vidu-compatible fields. creations is empty until state is success; watermarked_url equals url (no watermark).
stage	Our finer-grained internal stage (table above).
progress	{ segments_done, segments_total } while rendering.
effective_mode	The mode actually used.
scenes[]	scene_id, name, image_url, source (user or generated).
segments[]	segment_id, start, end, scene_id, status (pending, processing, completed, failed), video_url, shots[] with start, end, role, lyric_text.
error	Human-readable failure reason when state is failed.

Fields that Vidu does not have are additions; Vidu clients can ignore them.

Errors

Errors use the platform format { "success": false, "error": "...", "err_code": "..." }.

HTTP	err_code	When
400	InvalidRequest	Malformed JSON, field fails validation, a required image is missing for the mode, resolution is 1080p.
400	AudioInvalid	audio_url is not a URL or valid base64, or the file can't be decoded.
400	ImageInvalid	An image is not a URL or valid base64, or can't be decoded.
400	MultipleSingersNotSupported	lip_ref_urls has more than one entry.
401	—	Missing or unknown api-key.
402	InsufficientBalance	Balance is too low to cover even the shortest song.
404	NotFound	Task doesn't exist or isn't yours.
413	InvalidRequest	Request body too large (inline uploads are limited to 30MB each).
500	InternalError	Server-side error.

A task that fails after it was created reports these in err_code on the query endpoint:

err_code	Meaning
AudioTooShort	The audio is shorter than 10 seconds.
AudioTooLong	The audio is longer than 360 seconds.
AudioInvalid	The audio could not be processed.
ImageInvalid	An image could not be processed.
InsufficientBalance	The balance ran out once the audio length was known.
GenerationFailed	Rendering failed after retries.
Timeout	The task did not finish within 24 hours.

Notes

Inline (base64) assets are limited to 30MB each; use a URL for anything larger.
Output is an H.264 MP4 with your original audio track, cut to the song length.
Try everything interactively in the Playground tab; the Request log there shows the exact calls.