Parameter Usage Guide
- For models V4_5PLUS and V4_5: style (max 1000 chars), title (max 100 chars), prompt (max 5000 chars)
- For models V3_5 and V4: style (max 200 chars), title (max 80 chars), prompt (max 3000 chars)
- When customMode is true (Custom Mode):
- If instrumental is true: style, title and uploadUrl are required
- If instrumental is false: style, prompt, title and uploadUrl are required
- Character limits vary by model version (see note above)
- uploadUrl is used to specify the upload location of the audio file; ensure the uploaded audio does not exceed 8 minutes in length.
- When customMode is false (Non-custom Mode):
- Only prompt and uploadUrl are required regardless of instrumental setting
- prompt length limit: 400 characters
- Other parameters should be left empty
Developer Notes
- Recommended settings for new users: Set customMode to false, instrumental to false, and only provide prompt and uploadUrl. This is the simplest configuration to quickly test the API and experience the results.
- Generated files will be deleted after 15 days
- Ensure all required parameters are provided based on customMode and instrumental settings to avoid errors
- Pay attention to character limits for prompt, style, and title to ensure successful processing
- Callback process has three stages: text (text generation complete), first (first track complete), complete (all tracks complete)
- You can use the Get Music Generation Details endpoint to actively check task status instead of waiting for callbacks
- The uploadUrl parameter is used to specify the upload location of the audio file; please provide a valid URL.
Optional parameters
vocalGender
(string): Vocal gender preference. Usem
for male,f
for female.styleWeight
(number): Strength of adherence to style. Range 0–1, up to 2 decimals. Example:0.65
.weirdnessConstraint
(number): Controls creative deviation. Range 0–1, up to 2 decimals. Example:0.65
.audioWeight
(number): Balance weight for audio features. Range 0–1, up to 2 decimals. Example:0.65
.
Authorizations
All APIs require authentication via Bearer Token.
Get API Key:
- Visit API Key Management Page to get your API Key
Usage: Add to request header: Authorization: Bearer YOUR_API_KEY
Note:
- Keep your API Key secure and do not share it with others
- If you suspect your API Key has been compromised, reset it immediately in the management page
Body
The URL for uploading audio files, required regardless of whether customMode and instrumental are true or false. Ensure the uploaded audio does not exceed 2 minutes in length.
"https://storage.example.com/upload"
A description of the desired audio content.
- In Custom Mode (
customMode: true
): Required ifinstrumental
isfalse
. The prompt will be strictly used as the lyrics and sung in the generated track. Character limits by model:- V4_5PLUS & V4_5: Maximum 5000 characters
- V3_5 & V4: Maximum 3000 characters
Example: "A calm and relaxing piano track with soft melodies"
- In Non-custom Mode (
customMode: false
): Always required. The prompt serves as the core idea, and lyrics will be automatically generated based on it (not strictly matching the input). Max length: 400 characters.
Example: "A short relaxing piano tune"
"A calm and relaxing piano track with soft melodies"
Enables Custom Mode for advanced audio generation settings.
- Set to
true
to use Custom Mode (requiresstyle
andtitle
;prompt
required ifinstrumental
isfalse
). The prompt will be strictly used as lyrics ifinstrumental
isfalse
. - Set to
false
for Non-custom Mode (onlyprompt
is required). Lyrics will be auto-generated based on the prompt.
true
Determines if the audio should be instrumental (no lyrics).
- In Custom Mode (
customMode: true
):- If
true
: Onlystyle
andtitle
are required. - If
false
:style
,title
, andprompt
are required (withprompt
used as the exact lyrics).
- If
- In Non-custom Mode (
customMode: false
): No impact on required fields (prompt
only). Lyrics are auto-generated ifinstrumental
isfalse
.
true
The AI model version to use for generation.
- Required for all requests.
- Available options:
V4_5PLUS
: V4.5+ is richer sound, new waysto create, max 8 min.V4_5
: V4.5 is smarter prompts, fastergenerations, max 8 min.V4
: V4 is improved vocal quality,max 4 min.V3_5
: V3.5 is better song structure,max 4 min.
V3_5
, V4
, V4_5
, V4_5PLUS
"V3_5"
The URL to receive audio covering task completion updates. Required for all audio covering requests.
- System will POST task status and results to this URL when audio covering completes
- Callback includes generated covered audio files with new style while preserving original melody
- Your callback endpoint should accept POST requests with JSON payload containing covered track results and audio URLs
- For detailed callback format and implementation guide, see Audio Covering Callbacks
- Alternatively, use the Get Music Details endpoint to poll task status
"https://api.example.com/callback"
The music style or genre for the audio.
- Required in Custom Mode (
customMode: true
). Examples: "Jazz", "Classical", "Electronic". Character limits by model:- V4_5PLUS & V4_5: Maximum 1000 characters
- V3_5 & V4: Maximum 200 characters
Example: "Classical"
- In Non-custom Mode (
customMode: false
): Leave empty.
"Classical"
The title of the generated music track.
- Required in Custom Mode (
customMode: true
). Character limits by model:- V4_5PLUS & V4_5: Maximum 100 characters
- V3_5 & V4: Maximum 80 characters
Example: "Peaceful Piano Meditation"
- In Non-custom Mode (
customMode: false
): Leave empty.
"Peaceful Piano Meditation"
Music styles or traits to exclude from the generated audio.
- Optional. Use to avoid specific styles.
Example: "Heavy Metal, Upbeat Drums"
"Heavy Metal, Upbeat Drums"
Vocal gender preference for the singing voice. Optional. Use 'm' for male and 'f' for female.
m
, f
"m"
Strength of adherence to the specified style. Optional. Range 0–1, up to 2 decimal places.
0 <= x <= 1
Must be a multiple of 0.01
0.65
Controls experimental/creative deviation. Optional. Range 0–1, up to 2 decimal places.
0 <= x <= 1
Must be a multiple of 0.01
0.65
Balance weight for audio features vs. other factors. Optional. Range 0–1, up to 2 decimal places.
0 <= x <= 1
Must be a multiple of 0.01
0.65
Response
Request successful
Response status code
- 200: Success - Request has been processed successfully
- 401: Unauthorized - Authentication credentials are missing or invalid
- 402: Insufficient Credits - Account does not have enough credits to perform the operation
- 404: Not Found - The requested resource or endpoint does not exist
- 409: Conflict - WAV record already exists
- 422: Validation Error - The request parameters failed validation checks
- 429: Rate Limited - Request limit has been exceeded for this resource
- 451: Unauthorized - Failed to fetch the image. Kindly verify any access limits set by you or your service provider.
- 455: Service Unavailable - System is currently undergoing maintenance
- 500: Server Error - An unexpected error occurred while processing the request
200
, 401
, 402
, 404
, 409
, 422
, 429
, 451
, 455
, 500
Error message when code != 200
"success"