POST /generate

Generate music using AI with callback support. Supports both inspiration mode (text description) and custom mode (lyrics, style, title).

POSThttps://udioapi.pro/api/generate

tips

This endpoint generates music and sends results to your callback URL when completed.

Callback URL Requirements:

  • Must be publicly accessible (no localhost, internal IPs, or private networks)
  • Must accept POST requests
  • Will receive an array of generation results in the request body

Two Generation Modes:

  • Inspiration Mode: Use gpt_description_prompt to generate music from a text description
  • Custom Mode: Use prompt, style, and title for detailed control

Callbacks are sent at each stage: text generation, first audio, and completion.

requestHeaders

namerequireddescription
AuthorizationYesBearer token for authentication
Content-TypeYesapplication/json

Request Body

Request body supports two modes: Inspiration Mode or Custom Mode, plus callback URL

Inspiration Mode

Generate music from a text description

Parameter Type Required Description Example
gpt_description_promptstringYesText description of the music you want to generate. Max length: 400 chars for chirp-v3-5/chirp-v4-0A upbeat pop song about summer vacation with catchy melody
Custom Mode

Generate music with custom lyrics, style, and title

Parameter Type Required Description Example
promptstringYesCustom lyrics or detailed prompt. Max length: 3000 chars (chirp-v3-5/chirp-v4-0) or 5000 chars (chirp-v4-5/chirp-v4-5-plus)Verse 1: Walking down the street, feeling so free...
stylestringNoMusical style/genre. Max length: 200 chars (chirp-v3-5/chirp-v4-0) or 1000 chars (chirp-v4-5/chirp-v4-5-plus)pop, upbeat, electronic, 120 bpm
titlestringNoSong title. Max length: 80 charactersSummer Dreams
tagsstringNoNegative tags to avoid in generationsad, slow
Common Parameters
Parameter Type Required Description Example
callback_urlstringYesURL to receive generation results callbacks. Must be publicly accessible.https://your-domain.com/api/callback
modelstringNoAI model to use. Options: 'chirp-v3-5' (default), 'chirp-v4-0', 'chirp-v4-5', 'chirp-v4-5-plus', 'chirp-v5'.chirp-v5
make_instrumentalbooleanNoGenerate instrumental music without vocalsfalse
genderstringNoVocal gender preference. Use 'male' or 'female'female
style_weightnumberNoStrength of adherence to style. Range 0–1, up to 2 decimals0.65
weirdness_constraintnumberNoControls creative deviation. Range 0–1, up to 2 decimals0.65
audio_weightnumberNoBalance weight for audio features. Range 0–1, up to 2 decimals0.65

responses

{
  "code": 200,
  "message": "success",
  "workId": "gen2abc123def456bksv",
  "data": {
    "task_id": "gen2abc123def456bksv"
  }
}
{
  "code": 400,
  "message": "callback_url is required"
}
{
  "code": 401,
  "message": "No API key provided in Authorization header"
}
{
  "code": 500,
  "message": "Internal Server Error",
  "data": {
    "task_id": "gen2abc123def456bksv"
  },
  "workId": "gen2abc123def456bksv"
}
[
  {
    "id": "081a452c-45e2-44d2-88cc-15e06fb2544d",
    "audio_url": "",
    "image_url": "https://image_.jpeg",
    "image_large_url": "https://image_0.jpeg",
    "created_at": "2025-08-19T23:07:28.936Z",
    "createTime": "2025-08-19T23:07:28.936Z",
    "timestamp": 1755616048327,
    "status": "text",
    "title": "xxxx",
    "prompt": "xxxxxxxxx",
    "tags": "xxx",
    "duration": "",
    "model_name": "chirp-v3-5",
    "extra_message": "Text generated successfully.",
    "fail_message": "",
    "error_message": ""
  },
  {
    "id": "2a20be9d-c876-45e3-a3ed-867b5bf3c4e6",
    "audio_url": "",
    "image_url": "https://image_.jpeg",
    "image_large_url": "https://image_.jpeg",
    "created_at": "2025-08-19T23:07:28.936Z",
    "createTime": "2025-08-19T23:07:28.936Z",
    "timestamp": 1755616048327,
    "status": "text",
    "title": "xxxx",
    "prompt": "xxxxxxxx",
    "tags": "xxxxx",
    "duration": "",
    "model_name": "chirp-v3-5",
    "extra_message": "Text generated successfully.",
    "fail_message": "",
    "error_message": ""
  }
]
[
  {
    "id": "081a452c-45e2-44d2-88cc-15e06fb2544d",
    "audio_url": "https://xxxx.mp3",
    "image_url": "https://xxxx.jpeg",
    "image_large_url": "https://xxxx.jpeg",
    "created_at": "2025-08-19T23:09:09.050Z",
    "createTime": "2025-08-19T23:09:09.050Z",
    "timestamp": 1755616048327,
    "status": "first",
    "title": "xxxx",
    "prompt": "xxxxx",
    "tags": "xxx",
    "duration": 156.36,
    "model_name": "chirp-v3-5",
    "extra_message": "First audio generated successfully.",
    "fail_message": "",
    "error_message": ""
  },
  {
    "id": "2a20be9d-c876-45e3-a3ed-867b5bf3c4e6",
    "audio_url": "",
    "image_url": "https://xxxx.jpeg",
    "image_large_url": "https://xxxxx.jpeg",
    "created_at": "2025-08-19T23:09:09.050Z",
    "createTime": "2025-08-19T23:09:09.050Z",
    "timestamp": 1755616048327,
    "status": "first",
    "title": "xxxx",
    "prompt": "xxxxxxx",
    "tags": "xxxxx",
    "duration": "",
    "model_name": "chirp-v3-5",
    "extra_message": "First audio generated successfully.",
    "fail_message": "",
    "error_message": ""
  }
]
[
  {
    "id": "94316433-5bf5-4fb2-9285-83e60aaca920",
    "audio_url": "https://xxxx.mp3",
    "image_url": "https://xxx.jpeg",
    "image_large_url": "https://xxx.jpeg",
    "created_at": "2025-08-19T23:20:53.879Z",
    "createTime": "2025-08-19T23:20:53.879Z",
    "timestamp": 1755616853152,
    "status": "complete",
    "title": "xxxx",
    "prompt": "xxxxx",
    "tags": "xxxx",
    "duration": 122,
    "model_name": "chirp-v3-5",
    "extra_message": "All generated successfully.",
    "fail_message": "",
    "error_message": ""
  },
  {
    "id": "8206443a-1bd8-4cfd-8ef2-29c16b25c8b7",
    "audio_url": "https://xxxxx.mp3",
    "image_url": "https://xxxxxx.jpeg",
    "image_large_url": "https://xxxxx.jpeg",
    "created_at": "2025-08-19T23:20:53.879Z",
    "createTime": "2025-08-19T23:20:53.879Z",
    "timestamp": 1755616853152,
    "status": "complete",
    "title": "xxxx",
    "prompt": "xxx",
    "tags": "xxxx",
    "duration": 178.64,
    "model_name": "chirp-v3-5",
    "extra_message": "All generated successfully.",
    "fail_message": "",
    "error_message": ""
  }
]

codeExamples

curl -X POST "https://udioapi.pro/api/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://your-domain.com/api/callback",
    "model": "chirp-v4-5",
    "gpt_description_prompt": "A upbeat pop song about summer vacation with catchy melody",
    "make_instrumental": false,
    "gender": "female",
    "style_weight": 0.65,
    "weirdness_constraint": 0.65,
    "audio_weight": 0.65
  }'
curl -X POST "https://udioapi.pro/api/generate" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://your-domain.com/api/callback",
    "model": "chirp-v4-5",
    "prompt": "Verse 1: Walking down the street, feeling so free\nChorus: Summer dreams are calling me",
    "style": "pop, upbeat, electronic, 120 bpm",
    "title": "Summer Dreams",
    "make_instrumental": false,
    "gender": "female",
    "style_weight": 0.65,
    "weirdness_constraint": 0.65,
    "audio_weight": 0.65
  }'
const response = await fetch('https://udioapi.pro/api/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    callback_url: 'https://your-domain.com/api/callback',
    model: 'chirp-v4-5',
    gpt_description_prompt: 'A upbeat pop song about summer vacation with catchy melody',
    make_instrumental: false,
    gender: 'female',
    style_weight: 0.65,
    weirdness_constraint: 0.65,
    audio_weight: 0.65
  })
});

const data = await response.json();
console.log(data);
const response = await fetch('https://udioapi.pro/api/generate', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    callback_url: 'https://your-domain.com/api/callback',
    model: 'chirp-v4-5',
    prompt: 'Verse 1: Walking down the street, feeling so free\nChorus: Summer dreams are calling me',
    style: 'pop, upbeat, electronic, 120 bpm',
    title: 'Summer Dreams',
    make_instrumental: false,
    gender: 'female',
    style_weight: 0.65,
    weirdness_constraint: 0.65,
    audio_weight: 0.65
  })
});

const data = await response.json();
console.log(data);
import requests

url = "https://udioapi.pro/api/generate"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "callback_url": "https://your-domain.com/api/callback",
    "model": "chirp-v4-5",
    "gpt_description_prompt": "A upbeat pop song about summer vacation with catchy melody",
    "make_instrumental": False,
    "gender": "female",
    "style_weight": 0.65,
    "weirdness_constraint": 0.65,
    "audio_weight": 0.65
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
import requests

url = "https://udioapi.pro/api/generate"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "callback_url": "https://your-domain.com/api/callback",
    "model": "chirp-v4-5",
    "prompt": "Verse 1: Walking down the street, feeling so free\nChorus: Summer dreams are calling me",
    "style": "pop, upbeat, electronic, 120 bpm",
    "title": "Summer Dreams",
    "make_instrumental": False,
    "gender": "female",
    "style_weight": 0.65,
    "weirdness_constraint": 0.65,
    "audio_weight": 0.65
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
// Example callback endpoint to receive generation results
app.post('/api/callback', express.json(), (req, res) => {
  const results = req.body; // Array of generation results
  
  console.log('Received callback:', results);
  
  // Process each result
  results.forEach(result => {
    console.log(`Task ${result.id} status: ${result.status}`);
    
    switch(result.status) {
      case 'text':
        console.log('Lyrics generated:', result.title);
        break;
      case 'first':
        console.log('First audio ready:', result.audio_url);
        break;
      case 'complete':
        console.log('All audio complete:', result.audio_url);
        // Save to database, notify user, etc.
        break;
    }
  });
  
  // Always respond with 200 OK
  res.status(200).json({ received: true });
});