Retrieve a music video

November 10, 2026

Table of contents

  1. Request Headers
  2. Path Parameters
  3. Responses
  4. Model
  5. Examples
  6. Try It

Use this endpoint to follow a music video made with POST music-video/create until status is succeeded or failed, and to get the result. Besides the video it returns the settings the video was made with and, once it has finished, the extra files PixVerse produced:

role What it is
no_subtitle_video the same video without burned-in captions
subtitle_ass the timed lyrics as an .ass subtitle file
intermediate_image the key images PixVerse generated for the shots
intermediate_video the individual clips before they were cut together

The same video_id also works with GET videos/video_id, which returns the plain video record (video_status_name GENERATING while it renders, then COMPLETED or FAILED).

https://api.useapi.net/v2/pixverse/music-video/video_id

Request Headers 
Authorization: Bearer {API token}
Path Parameters
Responses

  • 200 OK

    status is pending or processing while the video renders, then succeeded (with video and files) or failed (with error).

    {
    "video_id": "user:<userid>-pixverse:<email>-video:642767619916505",
    "project_id": 192080023076656,
    "status": "succeeded",
    "mode": "performance",
    "audio_path": "upload/8aa34c5f-7f33-4fdc-af40-7357909102cb.mp3",
    "audio_duration": 151.97,
    "style": "auto",
    "image_path": "upload/66952750-badc-473b-b2a2-721197e96e7d.jpeg",
    "music_genre": "hip_hop",
    "subtitles": true,
    "aspect_ratio": "16:9",
    "quality": "1080p",
    "video": {
        "video_id": "user:<userid>-pixverse:<email>-video:642767619916505",
        "url": "https://media.pixverse.ai/pixverse%2Fmp4%2Fmedia%2Fweb%2Fori%2Fs-298ddfb9-f337-4091-a75e-ef7434aa9ce4_seed479843745.mp4",
        "cover_url": "https://media.pixverse.ai/pixverse%2Fvideo%2Fframe%2Ff7b7474c-53c3-4579-8f46-42982e159731.jpg",
        "first_frame": "https://media.pixverse.ai/pixverse%2Fvideo%2Fframe%2Ff7b7474c-53c3-4579-8f46-42982e159731.jpg",
        "width": 1920,
        "height": 1072,
        "duration": 152,
        "format": "mp4"
    },
    "files": [
        {
            "role": "intermediate_image",
            "file_name": "one-click-mv-image-0000.png",
            "url": "https://media.pixverse.ai/pixverse%2Fmp4%2Fmedia%2Fweb%2Fori%2Fs-298ddfb9-f337-4091-a75e-ef7434aa9ce4_seed479843745_artifact_000.png",
            "format": "png"
        },
        {
            "role": "subtitle_ass",
            "file_name": "one-click-mv-subtitle-00.ass",
            "url": "https://media.pixverse.ai/pixverse%2Fmp4%2Fmedia%2Fweb%2Fori%2Fs-298ddfb9-f337-4091-a75e-ef7434aa9ce4_seed479843745_artifact_034.ass",
            "format": "ass"
        },
        {
            "role": "no_subtitle_video",
            "file_name": "one-click-mv-no-subtitle.mp4",
            "url": "https://media.pixverse.ai/pixverse%2Fmp4%2Fmedia%2Fweb%2Fori%2Fs-298ddfb9-f337-4091-a75e-ef7434aa9ce4_seed479843745_artifact_035.mp4",
            "format": "mp4"
        }
    ],
    "created_at": "2026-11-10T06:53:05Z",
    "updated_at": "2026-11-10T07:08:41Z"
}

    A failed video carries PixVerse’s reason, and its credits are refunded:

    {
    "video_id": "user:<userid>-pixverse:<email>-video:905470371786428",
    "project_id": 536243871290987,
    "status": "failed",
    "error": "<PixVerse's reason>",
    "mode": "performance",
    "video": null,
    "files": []
}

  • 400 Bad Request

    {
  "error": "Path parameter path_video_id (…) has incorrect format",
  "code": 400
}

  • 401 Unauthorized

    {
  "error": "Unauthorized"
}

  • 404 Not Found

    The video is not a music video (use GET videos/video_id for it) or no longer exists.

    {
  "error": "Video user:<userid>-pixverse:<email>-video:<number> is not a music video. Use GET /videos/… for it",
  "code": 404
}

  • 596 Pending mod message

    The account has a pending error, and the API does not use it until you add it again with POST accounts/email. You receive an email when this happens. There are three causes.

    PixVerse could not sign the account in, most often because its password was changed. Add the account again with the current password.

    {
  "error": "Your PixVerse account has pending error. Please address this issue at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email before making any new API calls.",
  "code": 596
}

    Or PixVerse suspended the account. PixVerse suspends accounts that break its content rules and does not say which generation caused it. The first response carries PixVerse’s own details in account_moderation, and later calls return the same error. Add the account again after reinstatement_at. To ask PixVerse to lift the suspension earlier, write to the support_email it gives.

    {
  "error": "PixVerse suspended account [email protected] for 30 days, from 2026-10-16 09:26 UTC until 2026-11-15 09:26 UTC. PixVerse suspends accounts that break its content rules and does not say which generation caused it. Add the account again at https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email after 2026-11-15 09:26 UTC. To ask PixVerse to lift it earlier, write to [email protected].",
  "code": 596,
  "account_moderation": {
    "ban_level": "suspend_30d",
    "action": "temporary_suspend",
    "duration_days": 30,
    "suspended_at": "2026-10-16 09:26:25 (UTC)",
    "reinstatement_at": "2026-11-15 09:26:25 (UTC)",
    "support_email": "[email protected]"
  }
}

    Or PixVerse banned the account for violating its community guidelines. A ban is permanent unless PixVerse accepts an appeal, and the error quotes PixVerse’s own message, which says how to appeal. Remove the account with DELETE accounts/email, or add it again only if PixVerse lifts the ban.

    {
  "error": "PixVerse banned account [email protected] for violating its community guidelines (400024). A ban is permanent unless PixVerse accepts an appeal. PixVerse says: \"Your account has been banned for violating community guidelines. If you wish to appeal, please contact us via ...\" Remove it with DELETE /v2/pixverse/accounts/[email protected], or add it again (https://useapi.net/docs/api-pixverse-v2/post-pixverse-accounts-email) only if PixVerse lifts the ban.",
  "code": 596
}

    If every account you have is in this state, a request without email returns 596 as well.

Model 
{ // TypeScript, all fields are optional
    video_id: string
    project_id: number
    status: 'pending' | 'processing' | 'succeeded' | 'failed'
    error: string
    mode: 'performance' | 'expressive' | 'storytelling'
    audio_path: string
    audio_duration: number
    style: string
    style_image_path: string
    image_path: string
    image_path_2: string
    music_genre: string
    subtitles: boolean
    lyrics: string
    prompt: string
    aspect_ratio: string
    quality: string
    video: {
        video_id: string
        url: string
        cover_url: string
        first_frame: string
        width: number
        height: number
        duration: number
        format: string
    } | null
    files: {
        role: 'no_subtitle_video' | 'subtitle_ass' | 'intermediate_image' | 'intermediate_video'
        file_name: string
        url: string
        format: string
    }[]
    created_at: string
    updated_at: string
}
Examples 
  • curl "https://api.useapi.net/v2/pixverse/music-video/<video_id>" \
   -H "Accept: application/json" \
   -H "Authorization: Bearer …"

  • const video_id = "video_id returned by POST music-video/create";
const apiUrl = `https://api.useapi.net/v2/pixverse/music-video/${video_id}`;
const token = "API token";
const data = {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json' }
};
const response = await fetch(apiUrl, data);
const result = await response.json();
console.log("response", {response, result});

  • import requests
video_id = "video_id returned by POST music-video/create"
apiUrl = f"https://api.useapi.net/v2/pixverse/music-video/{video_id}"
token = "API token"
headers = {
    "Content-Type": "application/json",
    "Authorization" : f"Bearer {token}"
}
response = requests.get(apiUrl, headers=headers)
print(response, response.json())
Try It