Generate Music
POST
/api/v1/jobs/createTask
Document updated
Usage Guide
Parameter Details
custom_mode, instrumental, modelcustom_mode: true):title is required, maximum 80 charactersprompt is optional; when provided, it is used strictly as lyrics and sung in the generated track. If lyrics is also provided, lyrics takes prioritystyle, lyrics, or negative_tags must be provided; generation is rejected if all are emptyinstrumental: true: generate instrumental music (no vocals)instrumental: false: use lyrics as lyrics (fall back to prompt if lyrics is not provided)duration, negative_tags, vocal_gender, style_weight, weirdness_constraint, audio_weight, variety, persona_id, persona_modelprompt 3000 characters, style 200 charactersprompt 5000 characters, style 1000 charactersstyle 1000 characters; lyrics 5000 characterstitle length limit: 80 characters (all models)custom_mode: false):prompt is optional; it serves as the core idea, and lyrics are generated automatically (not a strict match), maximum 3000 characterslyrics can be used as a lyrics attachment together with promptimage_urls, video_urls, audio_urls, style, or lyrics must be provided; generation is rejected if all are emptyimage_urls, video_urls, and audio_urls are only valid in this modeduration, vocal_gender, style_weight, weirdness_constraint, audio_weight, varietystyle + lyrics + image_urls + video_urls + audio_urlsOptional Parameters
prompt (string): Description of the desired audio content. Optional. Used as lyrics in custom mode; used as the core idea in non-custom mode (maximum 3000 characters).lyrics (string): Lyrics content. Optional. V6 maximum 5000 characters. In custom mode, takes priority over prompt as lyrics; in non-custom mode, can be used as a lyrics attachment together with prompt.image_urls (array): Image references. Only effective when custom_mode is false. Up to 5 images, each no more than 10 MB. Supported formats: jpeg, png, webp, bmp.video_urls (array): Video references. Only effective when custom_mode is false. Up to 1 file, each no more than 100 MB, duration no more than 241 seconds. Supported formats: mp4, mov, webm.audio_urls (array): Audio references. Only effective when custom_mode is false. Duration must be between 6 seconds and 30 minutes; each file no more than 500 MB.style (string): Music style specification. See character limits in Parameter Details above.negative_tags (string): Music styles or traits to exclude from the generated audio. Optional.vocal_gender (string): Vocal gender preference. m for male, f for female. Only effective when custom_mode is true. In practice, this only increases probability and cannot guarantee the instruction is followed.style_weight (number): Strength of adherence to the specified style. Range 0–1, up to 2 decimal places. Only effective when custom_mode is true.weirdness_constraint (number): Creative/experimental deviation. Range 0–1, up to 2 decimal places. Only effective when custom_mode is true.audio_weight (number): Relative weight of audio features. Range 0–1, up to 2 decimal places. Only effective when custom_mode is true. Not supported when there are no vocals.variety (number): Diversity of generated results. Integer from 0–4, default 1. Only effective when custom_mode is true. 0 off (exact style), 1 normal (default, balanced), 2 high (distinct styles), 3 extra (bold exploration), 4 max (maximum variation).persona_id (string): Persona ID or Voice ID. Optional. To generate a Persona ID, see Generate Persona.persona_model (string): Persona model, style_persona or voice_persona. Only available for V5 (Discontinued), V5.5 (Discontinued), V6, V6_MINI, and V6_WILD.duration (number): Audio duration in seconds. Range 10–360, default 20. Only valid when custom_mode is true and the model is Developer Notes
custom_mode: false for simpler usagetext (text generation), first (first track complete), complete (all tracks complete)Callbacks
Request
Body Params application/jsonRequired
Responses
Request Request Example
Shell
JavaScript
Java
Swift
curl --location 'https://api.kie.ai/api/v1/jobs/createTask' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"model": "ai-music-api/generate",
"callBackUrl": "https://api.example.com/callback",
"input": {
"prompt": "A calm and relaxing piano track with soft melodies",
"custom_mode": true,
"instrumental": true,
"model": "V4",
"style": "Classical",
"title": "Peaceful Piano Meditation",
"negative_tags": "Heavy Metal, Upbeat Drums",
"vocal_gender": "m",
"style_weight": 0.65,
"weirdness_constraint": 0.65,
"audio_weight": 0.65,
"persona_id": "persona_123",
"persona_model": "style_persona",
"duration": 20
}
}'Response Response Example
{
"code": 200,
"msg": "success",
"data": {
"taskId": "5c79****be8e"
}
}