Sign in

v1

latestOpenAPI 3.0.02026-07-26355125.0 KB

Upload And Extend Audio

post/api/v1/generate/upload-extend

Request body

uploadUrlstring uri required

The URL for uploading audio files, required regardless of whether defaultParamFlag is true or false. Ensure the uploaded audio does not exceed 8 minutes in length.

defaultParamFlagboolean required

Enable custom mode for advanced audio generation settings.

  • Set to true to use custom parameter mode (requires style, title, and uploadUrl; if instrumental is false, uploadUrl and prompt are required). If instrumental is false, the prompt will be strictly used as lyrics.
  • Set to false to use non-custom mode (only uploadUrl required). Lyrics will be automatically generated based on the prompt.
instrumentalboolean

Determines whether the audio is instrumental (without lyrics).

  • In custom parameter mode (defaultParamFlag: true):
    • If true: only style, title, and uploadUrl are required.
    • If false: style, title, prompt (prompt will be used as exact lyrics), and uploadUrl are required.
  • In non-custom parameter mode (defaultParamFlag: false): does not affect required fields (only uploadUrl needed). If false, lyrics will be automatically generated.
promptstring

Description of how the music should be extended. Required when defaultParamFlag is true. Character limits by model:

  • V4: Maximum 3000 characters
  • V4_5, V4_5PLUS, V4_5ALL, V5 & V5_5: Maximum 5000 characters
stylestring

Music style, e.g., Jazz, Classical, Electronic. Character limits by model:

  • V4: Maximum 200 characters
  • V4_5, V4_5PLUS, V4_5ALL, V5 & V5_5: Maximum 1000 characters
titlestring

Music title. Character limits by model:

  • V4 & V4_5ALL: Maximum 80 characters
  • V4_5, V4_5PLUS, V5 & V5_5: Maximum 100 characters
continueAtnumber

The time point (in seconds) from which to start extending the music.

  • Required when defaultParamFlag is true.
  • Value range: greater than 0 and less than the total duration of the uploaded audio.
  • Specifies the position in the original track where the extension should begin.
personaIdstring

Only available when custom parameters are enabled. Persona ID to apply to the generated music. Optional. You can use either:

  • A Persona ID generated by the Generate Persona endpoint. Use personaModel: style_persona or omit personaModel to use the default.
  • A voiceId generated by the Suno Voice workflow. When using a voice-generated ID, you must set personaModel: voice_persona.
personaModel'style_persona' | 'voice_persona'

Persona model type to apply when using personaId. Optional.

  • style_persona (default): Use this for Persona IDs generated by the Generate Persona endpoint.
  • voice_persona: Use this when personaId is a voiceId generated by Suno Voice. This option is only available with V5 and V5_5 models.
model'V4' | 'V4_5' | 'V4_5PLUS' | 'V4_5ALL' | 'V5' | 'V5_5' required

Model version to use, must be consistent with the source audio

negativeTagsstring

Music styles to exclude from generation

vocalGender'm' | 'f'

Preferred vocal gender for generated vocals. Optional.

styleWeightnumber

Weight of the provided style guidance. Range 0.00–1.00.

weirdnessConstraintnumber

Constraint on creative deviation/novelty. Range 0.00–1.00.

audioWeightnumber

Weight of the input audio influence (where applicable). Range 0.00–1.00.

callBackUrlstring uri required

The URL to receive task completion notifications when music extension is complete.

  • For detailed callback format and implementation guide, see Upload and Extend Audio Callbacks
  • Alternatively, you can use the get music generation details endpoint to poll task status

Example request

{
  "uploadUrl": "https://storage.example.com/upload",
  "defaultParamFlag": true,
  "instrumental": true,
  "prompt": "Extend the music with more relaxing notes",
  "style": "Classical",
  "title": "Peaceful Piano Extended",
  "continueAt": 60,
  "personaId": "persona_123",
  "personaModel": "style_persona",
  "model": "V4_5ALL",
  "negativeTags": "Relaxing Piano",
  "vocalGender": "m",
  "styleWeight": 0.65,
  "weirdnessConstraint": 0.65,
  "audioWeight": 0.65,
  "callBackUrl": "https://api.example.com/callback"
}

Response

Request successful

code200 | 400 | 401 | 404 | 405 | 413 | 429 | 430 | 455 | 500

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
msgstring

Error message when code != 200

Example response

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