POST /generate
Generate music using AI with callback support. Supports both inspiration mode (text description) and custom mode (lyrics, style, title).
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_promptto generate music from a text description - Custom Mode: Use
prompt,style, andtitlefor detailed control
Callbacks are sent at each stage: text generation, first audio, and completion.
requestHeaders
| name | required | description |
|---|---|---|
| Authorization | yes | Bearer token for authentication |
| Content-Type | yes | application/json |
Bearer token for authentication
application/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_prompt | string | Yes | Text description of the music you want to generate. Max length: 400 chars for chirp-v3-5/chirp-v4-0 | A upbeat pop song about summer vacation with catchy melody |
Custom Mode
Generate music with custom lyrics, style, and title
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| prompt | string | Yes | Custom 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... |
| style | string | No | Musical 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 |
| title | string | No | Song title. Max length: 80 characters | Summer Dreams |
| tags | string | No | Negative tags to avoid in generation | sad, slow |
Common Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| callback_url | string | Yes | URL to receive generation results callbacks. Must be publicly accessible. | https://your-domain.com/api/callback |
| model | string | No | AI model to use. Options: 'chirp-v3-5' (default), 'chirp-v4-0', 'chirp-v4-5', 'chirp-v4-5-plus', 'chirp-v5'. | chirp-v5 |
| make_instrumental | boolean | No | Generate instrumental music without vocals | false |
| gender | string | No | Vocal gender preference. Use 'male' or 'female' | female |
| style_weight | number | No | Strength of adherence to style. Range 0–1, up to 2 decimals | 0.65 |
| weirdness_constraint | number | No | Controls creative deviation. Range 0–1, up to 2 decimals | 0.65 |
| audio_weight | number | No | Balance weight for audio features. Range 0–1, up to 2 decimals | 0.65 |
responses
{
"code": 200,
"message": "success",
"workId": "gen2abc123def456bksv",
"data": {
"task_id": "gen2abc123def456bksv"
}
}codeExamples
curl -X POST "https://giftasong.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
}'POST /generate
Generate music using AI with callback support. Supports both inspiration mode (text description) and custom mode (lyrics, style, title).
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_promptto generate music from a text description - Custom Mode: Use
prompt,style, andtitlefor detailed control
Callbacks are sent at each stage: text generation, first audio, and completion.
requestHeaders
| name | required | description |
|---|---|---|
| Authorization | yes | Bearer token for authentication |
| Content-Type | yes | application/json |
Bearer token for authentication
application/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_prompt | string | Yes | Text description of the music you want to generate. Max length: 400 chars for chirp-v3-5/chirp-v4-0 | A upbeat pop song about summer vacation with catchy melody |
Custom Mode
Generate music with custom lyrics, style, and title
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| prompt | string | Yes | Custom 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... |
| style | string | No | Musical 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 |
| title | string | No | Song title. Max length: 80 characters | Summer Dreams |
| tags | string | No | Negative tags to avoid in generation | sad, slow |
Common Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
| callback_url | string | Yes | URL to receive generation results callbacks. Must be publicly accessible. | https://your-domain.com/api/callback |
| model | string | No | AI model to use. Options: 'chirp-v3-5' (default), 'chirp-v4-0', 'chirp-v4-5', 'chirp-v4-5-plus', 'chirp-v5'. | chirp-v5 |
| make_instrumental | boolean | No | Generate instrumental music without vocals | false |
| gender | string | No | Vocal gender preference. Use 'male' or 'female' | female |
| style_weight | number | No | Strength of adherence to style. Range 0–1, up to 2 decimals | 0.65 |
| weirdness_constraint | number | No | Controls creative deviation. Range 0–1, up to 2 decimals | 0.65 |
| audio_weight | number | No | Balance weight for audio features. Range 0–1, up to 2 decimals | 0.65 |
responses
{
"code": 200,
"message": "success",
"workId": "gen2abc123def456bksv",
"data": {
"task_id": "gen2abc123def456bksv"
}
}codeExamples
curl -X POST "https://giftasong.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
}'