curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "add-vocals",
"callback_url": "https://your-domain.com/callback",
"input": {
"upload_url": "https://storage.example.com/instrumental.mp3",
"prompt": "A heartfelt ballad about love and memories",
"title": "Memories of You",
"style": "Pop Ballad",
"negative_tags": "rap, heavy metal"
}
}
'{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "not_started",
"created_time": "2025-11-12T10:30:00"
}
}Suno AI
Add Vocals
Layer AI-generated vocals on top of an existing instrumental
POST
/
api
/
generate
/
submit
curl --request POST \
--url https://api.poyo.ai/api/generate/submit \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"model": "add-vocals",
"callback_url": "https://your-domain.com/callback",
"input": {
"upload_url": "https://storage.example.com/instrumental.mp3",
"prompt": "A heartfelt ballad about love and memories",
"title": "Memories of You",
"style": "Pop Ballad",
"negative_tags": "rap, heavy metal"
}
}
'{
"code": 200,
"data": {
"task_id": "task-unified-1757165031-uyujaw3d",
"status": "not_started",
"created_time": "2025-11-12T10:30:00"
}
}- After submission, a
task_idwill be returned. If you provided acallback_url, when the task status becomesfinishedorfailed, a POST request will be sent to thecallback_url. - Regardless of whether
callback_urlis provided, you can retrieve the response result through the unified Query Music Detail endpoint.
Usage Guide
- This endpoint adds AI-generated vocals to an existing instrumental track
- Upload an instrumental file and provide lyrics or a description for the vocals
- Perfect for transforming instrumental tracks into complete songs
Parameter Details
-
Required parameters:
-
upload_url: URL of the instrumental audio file -
prompt: Lyrics or description for the vocals -
title: Name for the generated track -
style: Music style to guide vocal delivery -
negative_tags: Styles to exclude from generation
-
-
Model selection:
- V6: Greater musical expression with more natural vocals.
- V6_MINI: Lightweight and fast.
- V6_WILD: Bolder, more distinctive musical expression.
- V5_5: Personalized model tuned to your unique taste.
- V5: Superior musical expressiveness with faster generation
- V4_5PLUS: Enhanced tonal richness (default)
Developer Notes
- The
promptparameter serves as both lyrics and creative direction for the vocals - Use
styleto specify the vocal delivery style (e.g., “Pop Ballad”, “Rock”, “R&B”) - Combine with
vocal_genderfor more control over the vocal output
Optional parameters
-
mv(string): AI model version. Options:V4_5PLUS(default),V5,V5_5,V6,V6_MINI,V6_WILD. -
vocal_gender(string): Vocal gender preference. Usemfor male,ffor female. Note: This parameter can only increase the probability but cannot guarantee the specified gender. -
style_weight(number): Strength of adherence to style. Range 0-1, up to 2 decimals. -
weirdness_constraint(number): Controls creative deviation. Range 0-1, up to 2 decimals. -
audio_weight(number): Balance weight for audio features. Range 0-1, up to 2 decimals.
Authorizations
All API endpoints require Bearer Token authentication.
Create an API key: sign in to PoYo, open Dashboard → API Key at poyo.ai/dashboard/api-key, and click to create a key.
Add it to the request header:
Authorization: Bearer YOUR_API_KEY
Body
application/json
API model identifier.
Must be add-vocals for this endpoint.
Available options:
add-vocals Example:
"add-vocals"
Input parameters for vocal generation
Show child attributes
Show child attributes
Webhook callback URL for result notifications
Example:
"https://your-domain.com/callback"
Response
200 - application/json
Task submitted successfully
Business status code. 200 means success; any other value means the request failed. Always check this field: some validation errors return HTTP 200 with code: 400 in the body.
200: Success400: Invalid request parameters401: Missing or invalid API key402: Insufficient credits403: Permission denied404: Resource not found408: Request timeout429: Rate limit exceeded500: Internal server error502: Upstream service error503: Service unavailable
See Error Codes for details.
Available options:
200, 400, 401, 402, 403, 404, 408, 429, 500, 502, 503 Example:
200
Show child attributes
Show child attributes