Generate Music - PoYo AI

curl --request POST \
  --url https://api.poyo.ai/api/generate/submit \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "model": "generate-music",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "A calm and relaxing piano track with soft melodies",
    "style": "Classical",
    "title": "Peaceful Piano Meditation",
    "custom_mode": true,
    "instrumental": true,
    "mv": "V5_5",
    "negative_tags": "Heavy Metal, Upbeat Drums",
    "style_weight": 0.65
  }
}
'

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "not_started",
    "created_time": "2025-11-12T10:30:00"
  }
}

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": "generate-music",
  "callback_url": "https://your-domain.com/callback",
  "input": {
    "prompt": "A calm and relaxing piano track with soft melodies",
    "style": "Classical",
    "title": "Peaceful Piano Meditation",
    "custom_mode": true,
    "instrumental": true,
    "mv": "V5_5",
    "negative_tags": "Heavy Metal, Upbeat Drums",
    "style_weight": 0.65
  }
}
'

{
  "code": 200,
  "data": {
    "task_id": "task-unified-1757165031-uyujaw3d",
    "status": "not_started",
    "created_time": "2025-11-12T10:30:00"
  }
}

After submission, a task_id will be returned. If you provided a callback_url, when the task status becomes finished or failed, a POST request will be sent to the callback_url.
Regardless of whether callback_url is provided, you can retrieve the response result through the unified Query Music Detail endpoint.

Usage Guide

This endpoint creates music based on your text prompt
Multiple variations will be generated for each request
You can control detail level with custom mode and instrumental settings

Parameter Details

In Custom Mode ( custom_mode: true ):
- title is required
- At least one of style, lyrics, or negative_tags is required
- prompt is optional. When lyrics is also provided, lyrics is used as the sung text
- Character limits vary by model:
  - V4: prompt 3000 characters, style 200 characters
  - V4_5 & V4_5PLUS: prompt 5000 characters, style 1000 characters
  - V4_5ALL: prompt 5000 characters, style 1000 characters
  - V5: prompt 5000 characters, style 1000 characters
  - V5_5: prompt 5000 characters, style 1000 characters
  - V6, V6_MINI, and V6_WILD: lyrics 5000 characters, style 1000 characters
In Non-custom Mode ( custom_mode: false ):
- prompt length limit: 3000 characters
- Provide prompt, or at least one of style, lyrics, image_urls, video_urls, or audio_urls
- image_urls, video_urls, and audio_urls are only accepted in this mode. Together with style and lyrics, the attachment count must not exceed 10

Developer Notes

Recommendation for new users: Start with custom_mode: false for simpler usage

Optional parameters

vocal_gender (string): Vocal gender preference. Use m for male, f for female. Note: This parameter is only effective when custom_mode is true . Based on practice, this parameter can only increase the probability but cannot guarantee adherence to male/female voice instructions.
style_weight (number): Strength of adherence to style. Range 0-1, up to 2 decimals. Example: 0.65 .
weirdness_constraint (number): Controls creative deviation. Range 0-1, up to 2 decimals. Example: 0.65 .
audio_weight (number): Balance weight for audio features. Range 0-1, up to 2 decimals. Example: 0.65 .
persona_id (string): Persona ID to apply to the generated music. Use this to apply a specific persona style to your music generation. Only available when Custom Mode is enabled. How to generate persona_id, visit generate-persona.
lyrics (string): Lyrics content, maximum 5000 characters. In custom mode it takes priority over prompt.
variety (integer): Diversity from 0 to 4. Only applied when custom_mode is true.
image_urls, video_urls, audio_urls: Reference files for non-custom mode. Images allow up to 5 URLs and video allows 1 URL.
persona_model (string): style_persona or voice_persona. Requires persona_id and V5, V5_5, V6, V6_MINI, or V6_WILD.
duration (integer): Custom length from 10–360 seconds. Only supported when custom_mode: true and mv is V5_5, V6, V6_MINI, or V6_WILD.

Authorizations

Authorization

string

header

required

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

model

enum<string>

required

API model identifier.

Must be generate-music for this endpoint.

Available options:

generate-music

Example:

"generate-music"

input

object

required

Input parameters for music generation

Show child attributes

callback_url

string<uri>

Webhook callback URL for result notifications

Example:

"https://your-domain.com/callback"

Response

200 - application/json

Task submitted successfully

code

enum<integer>

required

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: Success
400: Invalid request parameters
401: Missing or invalid API key
402: Insufficient credits
403: Permission denied
404: Resource not found
408: Request timeout
429: Rate limit exceeded
500: Internal server error
502: Upstream service error
503: Service unavailable

See Error Codes for details.

Available options:

200,

400,

401,

402,

403,

404,

408,

429,

500,

502,

503

Example:

200

data

object

required

Show child attributes

​Usage Guide

​Parameter Details

​Developer Notes

​Optional parameters

Authorizations

Body

Response

Usage Guide

Parameter Details

Developer Notes

Optional parameters