Skip to main content
POST
/
api
/
v1
/
mp4
/
generate
Create Music Video
curl --request POST \
  --url https://api.api.box/api/v1/mp4/generate \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "taskId": "taskId_774b9aa0422f",
  "audioId": "e231****-****-****-****-****8cadc7dc",
  "callBackUrl": "https://api.example.com/callback",
  "author": "Suno Artist",
  "domainName": "music.example.com"
}'
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "taskId_774b9aa0422f"
  }
}

​
Usage Guide

  • This endpoint creates a visual representation of your music track as an MP4 video
  • Both taskId and audioId are required to identify the specific track
  • Optional author and domainName parameters can be used to add branding

​
Developer Notes

  1. Generated video files are retained for 15 days
  2. Videos include visual effects synchronized with the music
  3. This feature is ideal for social media sharing, music promotion, or creating visual content
  4. Videos maintain the same audio quality as the original track

Authorizations

​
Authorization
string
header
required

🔑 API Authentication

All endpoints require authentication using Bearer Token.

Get API Key

  1. Visit the API Key Management Page to obtain your API Key

Usage

Add to request headers:

Authorization: Bearer YOUR_API_KEY

⚠️ Note:

  • Keep your API Key secure and do not share it with others
  • If you suspect your API Key has been compromised, reset it immediately from the management page

Body

application/json
​
taskId
string
required

The task ID of the music generation task.

  • Required. This identifies the task containing the audio to be converted to video.
  • Both taskId and audioId are needed to identify the exact track.
Example:

"taskId_774b9aa0422f"

​
audioId
string
required

The ID of the specific track to convert to video.

  • Required. This identifies which specific track within the task to convert.
  • Both taskId and audioId are needed to identify the exact track.
Example:

"e231****-****-****-****-****8cadc7dc"

​
callBackUrl
string<uri>
required

The URL to receive video generation completion notification.

  • Required.
  • The callback will include a single downloadable URL for the generated MP4 video.

For detailed callback format and implementation guide, see Music Video Generation Callbacks

  • Alternatively, you can use the Get Music Video Details interface to poll task status
Example:

"https://api.example.com/callback"

​
author
string

The artist or creator name to display on the video.

  • Optional.
  • Will be shown prominently in the video, typically at the beginning.
  • Maximum 50 characters.
Maximum length: 50
Example:

"Suno Artist"

​
domainName
string

The website or brand to display as watermark.

  • Optional.
  • Will appear as a subtle watermark at the bottom of the video.
  • Maximum 50 characters.
Maximum length: 50
Example:

"music.example.com"

Response

Request successful

​
code
enum<integer>

Status Codes

  • ✅ 200 - Request successful
  • ⚠️ 400 - Invalid parameters
  • ⚠️ 401 - Unauthorized access
  • ⚠️ 404 - Invalid request method or path
  • ⚠️ 405 - Rate limit exceeded
  • ⚠️ 413 - Theme or prompt too long
  • ⚠️ 429 - Insufficient credits
  • ⚠️ 430 - Your call frequency is too high. Please try again later.
  • ⚠️ 455 - System maintenance
  • ❌ 500 - Server error
Available options:
200,
400,
401,
404,
405,
413,
429,
430,
455,
500
Example:

200

​
msg
string

Error message when code != 200

Example:

"success"

​
data
object