Generate Music
POST
/api/v1/generate
Usage Guide
Parameter Details
customMode, instrumental, modelcustomMode: true):title is optional, maximum 80 characters. Only available in this modeprompt 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 negativeTags 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, negativeTags, vocalGender, styleWeight, weirdnessConstraint, audioWeight, variety, personaId, personaModelprompt 3000 characters, style 200 charactersprompt 5000 characters, style 1000 charactersstyle 1000 characters; lyrics 5000 characters; negativeTags 1000 characterstitle length limit: 80 characters (all models)customMode: 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 promptimageUrls, videoUrls, audioUrls, style, or lyrics must be provided; generation is rejected if all are emptyimageUrls, videoUrls, and audioUrls are only valid in this modetitle, negativeTags, duration, vocalGender, styleWeight, weirdnessConstraint, audioWeight, varietystyle + lyrics + imageUrls + videoUrls + audioUrlsOptional 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.imageUrls (array): Image references. Only effective when customMode is false. Up to 5 images, each no more than 10 MB. Supported formats: jpeg, png, webp, bmp.videoUrls (array): Video references. Only effective when customMode is false. Up to 1 file, each no more than 100 MB, duration no more than 241 seconds. Supported formats: mp4, mov, webm.audioUrls (array): Audio references. Only effective when customMode 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.title (string): Track title. Optional. Only available when customMode is true. Maximum 80 characters. Displayed in player interfaces and filenames.negativeTags (string): Music styles or traits to exclude from the generated audio. Only available when customMode is true. For V6, V6_MINI, and V6_WILD: maximum 1000 characters.vocalGender (string): Vocal gender preference. m for male, f for female. Only available when customMode is true. In practice, this only increases probability and cannot guarantee the instruction is followed.styleWeight (number): Strength of adherence to the specified style. Range 0–1, up to 2 decimal places. Only effective when customMode is true.weirdnessConstraint (number): Creative/experimental deviation. Range 0–1, up to 2 decimal places. Only effective when customMode is true.audioWeight (number): Relative weight of audio features. Range 0–1, up to 2 decimal places. Only effective when customMode is true. Not supported when there are no vocals.variety (number): Diversity of generated results. Integer from 0–4, default 1. Only effective when customMode is true. 0 off (exact style), 1 normal (default, balanced), 2 high (distinct styles), 3 extra (bold exploration), 4 max (maximum variation).personaId (string): Persona ID or Voice ID. Optional. To generate a Persona ID, see Generate Persona.personaModel (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 available when customMode is true, and only valid when the model is Developer Notes
customMode: 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/generate' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
"prompt": "A calm and relaxing piano track with soft melodies",
"customMode": true,
"instrumental": true,
"model": "V4",
"callBackUrl": "https://api.example.com/callback",
"style": "Classical",
"title": "Peaceful Piano Meditation",
"negativeTags": "Heavy Metal, Upbeat Drums",
"vocalGender": "m",
"styleWeight": 0.65,
"weirdnessConstraint": 0.65,
"audioWeight": 0.65,
"personaId": "persona_123",
"personaModel": "style_persona",
"duration": 20
}'Response Response Example
{
"code": 200,
"msg": "success",
"data": {
"taskId": "5c79****be8e"
}
}