Generate

Music Generation API

Overview

Generate AI music based on text prompts using various models. The API supports different generation modes and can automatically handle lyrics generation.

API Endpoint

URL: POST https://udioapi.pro/api/generate
Content-Type: application/json

Code Examples

curl

nodejs

python

curl -X POST "https://udioapi.pro/api/generate" \
   -H "Content-Type: application/json" \
   -d '{
        "title": "",
        "prompt": "",
        "gpt_description_prompt":"",
        "custom_mode":false,
        "make_instrumental": false,
        "model": "chirp-v3.0",
        "callback_url":"",
        "cluster": "default",
        "token":"{{ your token }}"
    }'

Parameters:

Parameter	Type	Required	Description
title	string	No	The title of the music to be generated
prompt	string	Yes	The text prompt describing the music you want to generate
gpt_description_prompt	string	No	Additional prompt for GPT to help generate better music description
custom_mode	boolean	No	Whether to use custom mode
make_instrumental	boolean	No	Whether to generate instrumental music without vocals
model	string	No	The model to use for generation. Available options: "chirp-v3.5", "chirp-v3.0". Default: "chirp-v3.0"
callback_url	string	No	URL to receive generation results. If provided, results will be sent to this URL. If not provided, use the feed API to get results. Note that if the generation is successful, we will make a callback to the provided URL with the generated files. The callback method will be "POST", and the "Content-Type" should be set to "application/json".
cluster	string	No	Specify the cluster to use. Default: "default"
token	string	Yes	Your API token for authentication

title: Music title
prompt: generate music prompt, If the content is too long, the generation will fail with "Topic too long."
gpt_description_prompt: Can input music style, If the content is too long, the generation will fail with "Topic too long."
custom_mode: This parameter exists only in the suno-v3 model.
make_instrumental: false,
model: Options include chirp-v3.0, chirp-v3.5, udio-130, udio-32,
1. udio-130: Generate 2:10 clips. Takes longer
2. udio-32: Generate 32s clips
callback_url : Optional field, but it is recommended to use your own address due to potential delays with our forwarding
cluster: Optional field to specify which API server to use. Options:
1. default: Primary API server (default if not specified)
2. second: Backup API server
token: your api_key Required field

Custom Mode: If you want to use customMode, make sure the following parameters exist.

customMode	instrumental	Required Parameters
true	false	style, prompt, title
true	true	style, title
false	true	prompt
false	false	prompt

Submit Generation Task Response

{
  message: 'success',
  workId: 'workId' // Use this ID to query generation status
}

workId: Fields used to query generate results ::

Generate Callback Sample


{
  "code": 200,
  "data": {
    "callbackType": "complete",
    "data": [
      {
        "audio_url": "https://xxx.mp3",
        "createTime": 1717587606036,
        "duration": 146.08,
        "id": "59001af3-845d-47af-9e23-625adb0c6505",
        "image_url": "https://xxx.png",
        "model_name": "chirp-v3.5",
        "prompt": "[Verse]xxx[Verse 2]xxx[Chorus]xxx[Verse 3]xxx[Bridge]xxx[Chorus]xxx",
        "tags": "melodic pop piano",
        "title": "xxx"
      },
      {
        "audio_url": "https://xxx.mp3",
        "createTime": 1717587606036,
        "duration": 240,
        "id": "b0fa4b03-89d2-4c6d-82ea-28aa2604fee6",
        "image_url": "https://xxx.png",
        "model_name": "chirp-v3.5",
        "prompt": "[Verse]xxx[Verse 2]xxx[Chorus]xxx[Verse 3]xxx[Bridge]xxx[Chorus]xxx",
        "tags": "melodic pop piano",
        "title": "xxx"
      }
    ]
  },
  "msg": "All generated successfully."
}

Important Notes

File Retention: Generated files are stored for 30 days
Callback Format:
- Method: POST
- Content-Type: application/json
Best Practices:
- Use your own callback URL for better reliability
- Keep prompts concise to avoid generation failures
- Consider using the backup cluster during high traffic

Error Handling

Common error scenarios:

"Topic too long": Reduce prompt or gpt_description_prompt length
Authentication errors: Verify your token
Generation failures: Check prompt validity and try the backup cluster

Query Result API Documentation

Overview

This API allows you to retrieve the results of your generation tasks. Use this endpoint when you haven't specified a callback_url in your original request.

Feed API Endpoint

Request Details

Method: GET
URL: /api/feed
Required Parameter:
- workId (string): The unique identifier of your generation task

Example Request

curl -X GET "https://udioapi.pro/api/feed?workId=123456"

Response Format

The API returns a JSON object containing the following fields:

Field	Type	Description
type	string	Current status of the generation task (see Status Types below)
request_body	object	Original request parameters
response_data	array	Array of generated results
created_at	string	Timestamp of when the request was created

Status Types

The type field in the response can have one of these values:

new: Initial status after task submission
IN_PROGRESS: Task is currently being processed
complete: Task has finished, all audio files are generated

Sample Response

{
    "type": "complete",
    "request_body": {
        "prompt": "test",
        "title": "test",
        "customMode": false,
        "instrumental": false
    },
    "response_data": [
        {
            "audio_url": "https://xxx.mp3",
            "createTime": "",
            "id": "59001af3-845d-47af-9e23-625adb0c6505",
            "image_url": "https://xxx.png",
            "prompt": "[Verse]xxx[Verse 2]xxx[Chorus]xxx[Verse 3]xxx[Bridge]xxx[Chorus]xxx",
            "tags": "melodic pop piano",
            "title": "xxx",
            "error_message": "",
            "status": "complete"
        },
        {
            "audio_url": "https://xxx.mp3",
            "createTime": "",
            "id": "b0fa4b03-89d2-4c6d-82ea-28aa2604fee6",
            "image_url": "https://xxx.png",
            "prompt": "[Verse]xxx[Verse 2]xxx[Chorus]xxx[Verse 3]xxx[Bridge]xxx[Chorus]xxx",
            "tags": "melodic pop piano",
            "title": "xxx",
            "error_message": "",
            "status": "complete"
        }
    ],
    "created_at": "2024-09-05 13:09:01"
}

Response Data Fields

Each item in the response_data array contains:

Field	Type	Description
audio_url	string	URL to download the generated audio file
createTime	string	Creation timestamp
id	string	Unique identifier for the generated item
image_url	string	URL of the associated image
prompt	string	The structured prompt used for generation
tags	string	Associated tags describing the content
title	string	Title of the generated content
error_message	string	Error details if any issues occurred
status	string	Status of this specific item

Error Messages

The error_message field may contain one of the following values:

Error Message	Description	Solution
Unable to generate lyrics from song description	Content review detected violation of Suno rules, unable to generate lyrics	Modify your prompt to comply with content guidelines
Prompt likely malformed	The prompt structure or content has formatting issues	Review and correct your prompt format and content
Rate limit exceeded	Too many requests in a short time period	Wait and try again later
Invalid prompt format	The provided prompt doesn't follow required structure	Check prompt format and try again
Generation timeout	The generation process took too long	Try again or simplify your request
Server overload	Server is experiencing high load	Wait and try again later
Invalid parameters	One or more request parameters are invalid	Check your request parameters
Network error	Connection issues during generation	Check your network connection and try again

Note: This is not an exhaustive list. Other error messages may occur depending on specific circumstances.

Server Error

Understanding and Communicating Recent Server Anomalies

Generate V2

On This Page