Video GenerationtaskType: create_music_video10 Credits / TaskAsync Webhook & Polling

Create Music Video (MP4)

Transform any generated Suno track into a fully synchronized, high-definition MP4 music video. Seamlessly blends dynamic visual animations, cover artwork, audio reactive pulses, customizable artist attribution, and custom brand domain watermarks.

POST/api/v1/createTask
Test in Playground

Video Output Features

1080p MP4
Social-ReadyOPTIMIZED

Formatted for vertical and square mobile feeds on TikTok, Instagram Reels, and YouTube Shorts.

Artist Attribution

Overlay creator name and custom brand domain watermark directly into the video rendering.

Audio-Reactive

Smooth visualizers and lighting pulses synchronized in lockstep with the song's transients.

Key Capabilities & CDN Retention

  • 14-Day Cloud Storage: Rendered MP4 video files are stored on high-speed global CDN edge servers for 14 days.
  • Signature & Branding: Pass optional author and domain_name strings (up to 50 characters each) to stamp custom creator branding.
  • Cost & Billing: Consumes only 10 credits per music video rendering. If generation fails, credits are refunded automatically.

Validation Rules & Constraints

Source Track IDs

Both task_id and audio_id are required and must reference an existing song that has completed audio rendering.

Asynchronous Webhook

Video rendering requires GPU processing time. Provide a valid callBackUrl to receive the final MP4 video download URL immediately upon completion.

Authentication & Headers

HeaderRequirementDescription
Authorizationrequired

Bearer YOUR_API_KEY

Secret API key generated in your dashboard.

Content-Typerequired

application/json

Request body format.

Request Body Parameters

6 fields
task_idstringrequired

Unique identifier of the music generation task containing the target song.

audio_idstringrequired

Unique identifier (UUID) of the specific audio track within the generation task to visualize into an MP4 video.

authorstringoptional

Artist or creator name displayed as signature attribution on the video cover (maximum 50 characters).

domain_namestringoptional

Custom website or brand name displayed as watermark attribution at the bottom of the video (maximum 50 characters).

taskTypestringoptional
default:create_music_video

Explicit task routing identifier. Can be set to "create_music_video".

callBackUrlstringoptional

Public HTTPS webhook URL to receive asynchronous completion notification when video rendering completes.

When Callbacks Are Sent

The SongMesh API automatically triggers an HTTP POST request to your designated callBackUrl under these events:

  • Music video task placed in cloud GPU rendering queue
  • Cover art animation, particle motions, and audio waveforms rendered
  • 1080p H.264 MP4 container assembled and uploaded to edge CDN
  • Webhook notification dispatched with direct video download URL (code: 200 / 0)

Webhook Payload Format

Response Body(200 status)
{
  "code": 200,
  "msg": "success",
  "data": {
    "task_id": "task_id_5bbe7721119d",
    "video_url": "https://cdn.sunoapi.top/path/to/generated_music_video.mp4"
  }
}

Callback Payload Fields

FieldTypeDescription
codeintegerHTTP status code (200 / 0: Success, 400: Bad Request, 500: Server rendering error).
msgstringStatus message ("success" or error details).
data.task_idstringUnique task identifier assigned to the music video generation request.
data.video_urlstringHigh-speed signed CDN download URL for the generated 1080p MP4 music video (valid for 14 days).

Receiver Implementation Example

Webhook Receiver
// Next.js App Router Webhook Receiver (/api/webhook/suno/route.ts)
import { NextRequest, NextResponse } from 'next/server';

export async function POST(req: NextRequest) {
  const payload = await req.json();
  const { code, msg, data } = payload;

  if ((code === 200 || code === 0) && (data?.video_url || data?.videoUrl)) {
    const videoUrl = data.video_url || data.videoUrl;
    console.log(`Music video for task ${data.task_id} generated successfully!`);
    console.log(`Direct MP4 Video URL: ${videoUrl}`);

    // Download MP4 video, upload to cloud storage, or auto-publish to TikTok/YouTube
  } else {
    console.error(`Music video rendering failed (${code}): ${msg}`);
  }

  return NextResponse.json({ received: true });
}

Webhook Security Recommendation

Always verify incoming webhook payloads on your server. Respond with a 200 OK immediately after parsing the payload to prevent redundant delivery retries from the webhook dispatcher.

Request Sample
curl -X POST "https://api.sunoapi.top/api/v1/createTask" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "taskType": "create_music_video",
    "task_id": "taskId_774b9aa0422f",
    "audio_id": "e2318ca3-5b62-49d9-bbd3-08aaf2c6dd27",
    "author": "DJ Electronic",
    "domain_name": "sunoapi.top",
    "callBackUrl": "https://api.yourdomain.com/webhook/suno"
  }'
Response Body(200 status)
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "taskId_774b9aa0422f"
  }
}
Video Creation Tips

• Social Media: Use the generated MP4 file directly for promotional clips on TikTok, YouTube Shorts, and Instagram.

• Retention: Download the MP4 file within 14 days or upload it to your long-term cloud bucket.

• Pricing: 10 credits per music video rendering.

Previous EndpointGenerate MIDI from AudioNext EndpointGenerate Music Webhook

Ready to render synchronized MP4 music videos?

Generate your API key and export professional social-ready music videos in seconds.

Generate Secret Key