Pixverse Music Mv Agent API Documentation

Pixverse Music Mv Agent API Documentation

Playground

PixVerse Music MV Agent is a fast AI music video generation model that creates music videos from uploaded audio with optional character reference images, music style, MV style, aspect ratio, and quality controls. Ready-to-use REST inference API for audio-to-video generation, music videos, artist visuals, social media clips, promotional content, creative storytelling, and professional MV production workflows with simple integration, no coldstarts, and affordable pricing.

Features

PixVerse Music MV Agent generates a music video from an input audio track, with optional reference images, lyrics, music-style controls, visual-style controls, aspect ratio selection, and resolution options. It is designed for AI music videos, lyric-driven visuals, artist promos, character-led MV concepts, and other audio-to-video workflows.

Why Choose This?

• Audio-to-music-video generation
  Turn a song or audio track into a full music video from a single workflow.

• Optional reference image guidance
  Add up to 5 reference images to guide character appearance or visual direction.

• Music and MV style controls
  Set both music_style and mv_style to better match the tone of the final output.

• Flexible aspect ratios
  Supports widescreen, vertical, and square outputs for different publishing platforms.

• Lyrics-aware workflow
  Optionally provide lyric_text to better align visuals with the song content.

• Production-ready API
  Suitable for music promotion, social content, creator workflows, visualizer-style generation, and AI MV prototyping.

Parameters

Reference Image Format

Each item in image_references supports:

How to Use

1. Upload your audio — provide the song or audio track you want to turn into a music video.
2. Add reference images (optional) — upload character or style references if you want more visual control.
3. Set the music style — choose the genre or overall music direction.
4. Set the MV style — choose the visual style for the generated video.
5. Choose aspect ratio and quality — select the final video format and resolution.
6. Add lyrics (optional) — provide lyric_text if you want stronger lyric-aware visual guidance.
7. Set instrumental mode (optional) — enable instrumental_switch when the audio has no vocals.
8. Submit — run the model and download the generated music video.

Example Use Case

Generate a cinematic 16:9 AI music video from a pop track, with character reference images, lyric guidance, and 1080p quality for social media release or artist promotion.

Pricing

Pricing depends on audio duration and quality.

Billing Rules

• 720p costs $0.08 per billed second
• 1080p costs $0.12 per billed second
• Audio duration is billed in whole seconds, rounded up
• Minimum billed duration is 10 seconds
• Maximum billed duration is 360 seconds
• image_references, music_style, mv_style, aspect_ratio, lyric_text, and instrumental_switch do not affect pricing

Example Costs

Best Use Cases

• AI music videos — Generate full MV-style visuals from a song.
• Artist promotion — Create visual promos for track launches and teasers.
• Lyric-driven content — Pair song lyrics with matching visual storytelling.
• Character-led music content — Use references to maintain a more stable cast or visual identity.
• Social media releases — Produce vertical or widescreen clips for modern distribution platforms.

Pro Tips

• Use image_references when identity, style, or recurring characters matter.
• Add lyric_text when you want visuals to better follow the song content.
• Leave instrumental_switch enabled for instrumental tracks or beat-only audio.
• Use 720p for testing and iteration, then switch to 1080p for final-quality output.
• Keep reference images visually consistent when you want more stable character appearance.

Notes

• audio is required.
• Audio duration is billed with a minimum of 10 seconds and a maximum of 360 seconds.
• Billing uses whole seconds and rounds duration up.
• quality defaults to 720p.
• aspect_ratio defaults to 16:9.
• instrumental_switch defaults to true.

Related Models

• MiniMax Music 3.0 — Generate complete songs with vocals and instrumentals from text prompts and lyrics.
• Music Video Generator — Generate music-video-style visuals from audio or soundtrack-driven inputs.
• Vidu One-Click V2 MV — Create music video clips with one-click MV generation workflows.

Authentication

For authentication details, please refer to the Authentication Guide.

API Endpoints

Submit Task & Query Result

set -euo pipefail

export WAVESPEED_API_KEY="your-api-key"

REQUEST_BODY=$(cat <<'JSON'
{
  "audio": "https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3",
  "aspect_ratio": "16:9",
  "quality": "720p",
  "caption_switch": false,
  "instrumental_switch": false
}
JSON
)

# 1. Submit the prediction.
SUBMIT_RESPONSE=$(curl --silent --show-error --fail-with-body \
  -X POST "https://api.wavespeed.ai/api/v3/pixverse/music-mv-agent" \
  -H "Authorization: Bearer ${WAVESPEED_API_KEY}" \
  -H "Content-Type: application/json" \
  -d "${REQUEST_BODY}")

TASK=$(printf '%s' "${SUBMIT_RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
PREDICTION_ID=$(printf '%s' "${TASK}" | jq -r '.id // empty')
if [ -z "${PREDICTION_ID}" ]; then
  printf 'Submission response did not contain a prediction id
' >&2
  exit 1
fi
RESULT_URL="https://api.wavespeed.ai/api/v3/predictions/${PREDICTION_ID}/result"

# 2. Poll until the prediction finishes.
while true; do
  RESPONSE=$(curl --silent --show-error --fail-with-body \
    "${RESULT_URL}" \
    -H "Authorization: Bearer ${WAVESPEED_API_KEY}")
  RESULT=$(printf '%s' "${RESPONSE}" | jq 'if type == "object" and has("data") then .data else . end')
  STATUS=$(printf '%s' "${RESULT}" | jq -r '.status // empty')

  case "${STATUS}" in
    completed) printf '%s\n' "${RESULT}" | jq '.outputs'; break ;;
    failed|cancelled|timeout|deleted) printf '%s\n' "${RESULT}" | jq . >&2; exit 1 ;;
    *) sleep 2 ;;
  esac
done

Parameters

Task Submission Parameters

Request Parameters

Response Parameters

Result Request Parameters

Result Response Parameters