Skip to main content
POST
/
api
/
v1
/
generate
/
upload-cover
{
  "customMode": true,
  "instrumental": false,
  "prompt": "Cover with a darker cinematic vibe",
  "style": "Cinematic",
  "title": "Dark Reprise",
  "uploadUrl": "https://storage.example.com/upload",
  "model": "V4_5ALL",
  "callBackUrl": "https://example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65
}

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "5c79****be8e"
  }
}

​
Parameter Usage Guide

  • 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 (based on model):
      • V4_5, V4_5PLUS, V5, V5_5 models: prompt max 5000 characters, style max 1000 characters, title max 100 characters
      • V4 model: prompt max 3000 characters, style max 200 characters, title max 80 characters
      • V4_5ALL model: prompt max 5000 characters, style max 1000 characters, title max 80 characters
    • model (string, required): V4_5ALL, V4, V4_5, V4_5PLUS, V5, V5_5. V5_5: Unleash Your Voice: Custom Models Tailored to Your Unique Taste — same limits as V5 where applicable.
    • 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: 500 characters
    • Other parameters should be left empty

​
Optional parameters

The following fields are optional controls available for this endpoint:
  • vocalGender (string): Preferred vocal gender. Allowed values: m (male), f (female)
  • styleWeight (number): Style adherence weight in range 0–1 (recommended two decimals)
  • weirdnessConstraint (number): Creativity/novelty constraint in range 0–1 (recommended two decimals)
  • audioWeight (number): Relative weight of audio consistency in range 0–1 (recommended two decimals)
  • personaId (string): Persona ID to apply a specific persona style to your music generation. Only available when Custom Mode is enabled. To obtain one, use the Generate Persona endpoint.
  • audioWeight (number): Relative weight of audio consistency in range 0–1 (recommended two decimals)
{
  "customMode": true,
  "instrumental": false,
  "prompt": "Cover with a darker cinematic vibe",
  "style": "Cinematic",
  "title": "Dark Reprise",
  "uploadUrl": "https://storage.example.com/upload",
  "model": "V4_5ALL",
  "callBackUrl": "https://example.com/callback",
  "vocalGender": "m",
  "styleWeight": 0.61,
  "weirdnessConstraint": 0.72,
  "audioWeight": 0.65
}

​
Developer Notes

  1. 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.
  2. Generated files will be deleted after 15 days
  3. Ensure all required parameters are provided based on customMode and instrumental settings to avoid errors
  4. Pay attention to character limits for prompt, style, and title to ensure successful processing
  5. Callback process has three stages: text (text generation complete), first (first track complete), complete (all tracks complete)
  6. You can use the Get Music Generation Details endpoint to actively check task status instead of waiting for callbacks
  7. The uploadUrl parameter is used to specify the upload location of the audio file; please provide a valid URL.

Authorizations

​
Authorization
string
header
required

🔑 API Authentication

All endpoints require authentication using Bearer Token.

Get API Key

  1. Visit the API Key Management Page to obtain your API Key

Usage

Add to request headers:

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 from the management page

Body

application/json
​
uploadUrl
string<uri>
required

The URL for uploading audio files, required regardless of whether customMode and instrumental are true or false.

Upload Audio Duration Limits: Maximum upload duration is 8 minutes

Example:

"https://storage.example.com/upload"

​
customMode
boolean
required

Enables Custom Mode for advanced audio generation settings.

  • Set to true to use Custom Mode (requires style and title; prompt required if instrumental is false). The prompt will be strictly used as lyrics if instrumental is false.
  • Set to false for Non-custom Mode (only prompt is required). Lyrics will be auto-generated based on the prompt.
Example:

true

​
instrumental
boolean
required

Determines if the audio should be instrumental (no lyrics).

  • In Custom Mode (customMode: true):
    • If true: Only style and title are required.
    • If false: style, title, and prompt are required (with prompt used as the exact lyrics).
  • In Non-custom Mode (customMode: false): No impact on required fields (prompt only). Lyrics are auto-generated if instrumental is false.
Example:

true

​
model
enum<string>
required

The AI model version to use for generation.

  • Required for all requests.
  • Available options:
    • V5: Superior musical expression, faster generation.
    • V5_5: Unleash Your Voice: Custom Models Tailored to Your Unique Taste. Same custom-mode prompt and style character limits as V5 (5000 / 1000).
    • 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.
    • V4_5ALL: V4.5-all is better song structure,max 8 min.
Available options:
V4_5ALL,
V4,
V4_5,
V4_5PLUS,
V5,
V5_5
Example:

"V4_5ALL"

​
callBackUrl
string<uri>
required

The URL to receive task completion notifications when upload and cover audio is complete. The callback process has three stages: text (text generation), first (first track complete), complete (all tracks complete). Note: In some cases, text and first stages may be skipped, directly returning complete.

  • For detailed callback format and implementation guide, see Upload and Cover Audio Callbacks
  • Alternatively, you can use the Get Music Generation Details interface to poll task status
Example:

"https://api.example.com/callback"

​
prompt
string

A description of the desired audio content.

  • In Custom Mode (customMode: true): Required if instrumental is false. The prompt will be strictly used as the lyrics and sung in the generated track. Character limits by model:
    • V4: Maximum 3000 characters
    • V4_5, V4_5PLUS, V5, V5_5 & V4_5ALL: Maximum 5000 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). Maximum 500 characters.
    Example: "A short relaxing piano tune"
Example:

"A calm and relaxing piano track with soft melodies"

​
style
string

The music style or genre for the audio.

  • Required in Custom Mode (customMode: true). Examples: "Jazz", "Classical", "Electronic".
    • For V4 model: Max length: 200 characters.
    • For V4_5, V4_5PLUS, V5, V5_5 and V4_5ALL models: Max length: 1000 characters.
      Example: "Classical"
  • In Non-custom Mode (customMode: false): Leave empty.
Example:

"Classical"

​
title
string

The title of the generated music track.

  • Required in Custom Mode (customMode: true). Character limits by model:
    • V4 & V4_5ALL: Max length: 80 characters
    • V4_5, V4_5PLUS, V5 & V5_5: Max length: 100 characters
      Example: "Peaceful Piano Meditation"
  • In Non-custom Mode (customMode: false): Leave empty.
Example:

"Peaceful Piano Meditation"

​
personaId
string

Persona ID to apply to the generated music. Optional. Only available when Custom Mode is enabled. Use this to apply a specific persona style to your music generation.

To generate a persona ID, use the Generate Persona endpoint to create a personalized music Persona based on generated music.

Example:

"persona_123"

​
personaModel
enum<string>
default:style_persona

Persona model type to apply when using personaId. Optional.

  • style_persona (default): Applies style-focused persona characteristics.
  • voice_persona: Applies voice-focused persona characteristics (only available with V5 and V5_5 models).
Available options:
style_persona,
voice_persona
Example:

"style_persona"

​
negativeTags
string

Music styles or traits to exclude from the generated audio.

  • Optional. Use to avoid specific styles.
    Example: "Heavy Metal, Upbeat Drums"
Example:

"Heavy Metal, Upbeat Drums"

​
vocalGender
enum<string>

Preferred vocal gender. Optional. Allowed values: 'm' (male), 'f' (female).

Available options:
m,
f
Example:

"m"

​
styleWeight
number

Style adherence weight. Optional. Range: 0-1. Two decimal places recommended.

Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.65

​
weirdnessConstraint
number

Creativity/novelty constraint. Optional. Range: 0-1. Two decimal places recommended.

Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.65

​
audioWeight
number

Relative weight of audio consistency versus other controls. Optional. Range: 0-1. Two decimal places recommended.

Required range: 0 <= x <= 1Must be a multiple of 0.01
Example:

0.65

Response

Request successful

​
code
enum<integer>

Status Codes

  • ✅ 200 - Request successful
  • ⚠️ 400 - Invalid parameters
  • ⚠️ 401 - Unauthorized access
  • ⚠️ 404 - Invalid request method or path
  • ⚠️ 405 - Rate limit exceeded
  • ⚠️ 413 - Theme or prompt too long
  • ⚠️ 429 - Insufficient credits
  • ⚠️ 430 - Your call frequency is too high. Please try again later.
  • ⚠️ 455 - System maintenance
  • ❌ 500 - Server error
Available options:
200,
400,
401,
404,
405,
413,
429,
430,
455,
500
Example:

200

​
msg
string

Error message when code != 200

Example:

"success"

​
data
object