Extend Music
Extend or modify existing music by creating a continuation based on a source audio track.
Usage Guide
- This endpoint allows you to extend existing music tracks
- You can choose to use original parameters or set new custom parameters
- Extended music will maintain style consistency with the source track
Parameter Details
-
With Custom Parameters (
defaultParamFlag: true):prompt,style,titleandcontinueAtare required- Character limits vary by model:
- V4:
prompt3000 characters,style200 characters,title80 characters - V4_5 & V4_5PLUS:
prompt5000 characters,style1000 characters,title100 characters - V4_5ALL:
prompt5000 characters,style1000 characters,title80 characters - V5:
prompt5000 characters,style1000 characters,title100 characters
- V4:
-
With Original Parameters (
defaultParamFlag: false):- Only
audioIdis required - Other parameters will be inherited from the source audio
- Only
Developer Notes
- Generated files are retained for 14 days
- Model version must match the source audio’s model version
- Callback process follows the same pattern as the music generation endpoint
Optional parameters
vocalGender(string): Vocal gender preference. Usemfor male,ffor 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.personaId(string): Persona ID to apply to the generated music. Only available when Custom Mode is enabled. To create one, use Generate Persona.
Rate limits and quotas are enforced by Apikley and may differ from upstream providers.
OpenAPI
suno-api/suno-api.json post /api/v1/generate/extend
Copy
openapi: 3.0.0
info:
title: Suno API
description: Apikley Suno API Documentation
version: 1.0.0
contact:
name: Technical Support
email: [email protected]
servers:
- url: https://api.apikley.ru
description: API Server
security:
- BearerAuth: []
paths:
/api/v1/generate/extend:
post:
summary: Extend Music
description: >-
Extend or modify existing music by creating a continuation based on a
source audio track.
### Usage Guide
- This endpoint allows you to extend existing music tracks
- You can choose to use original parameters or set new custom parameters
- Extended music will maintain style consistency with the source track
### Parameter Details
- With Custom Parameters (`defaultParamFlag: true`):
- `prompt`, `style`, `title` and `continueAt` are required
- Character limits vary by model:
- **V4**: `prompt` 3000 characters, `style` 200 characters, `title` 80 characters
- **V4_5 & V4_5PLUS**: `prompt` 5000 characters, `style` 1000 characters, `title` 100 characters
- **V4_5ALL**: `prompt` 5000 characters, `style` 1000 characters, `title` 80 characters
- **V5**: `prompt` 5000 characters, `style` 1000 characters, `title` 100 characters
- With Original Parameters (`defaultParamFlag: false`):
- Only `audioId` is required
- Other parameters will be inherited from the source audio
### Developer Notes
- Generated files are retained for 14 days
- Model version must match the source audio's model version
- Callback process follows the same pattern as the music generation
endpoint
operationId: extend-music
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- defaultParamFlag
- audioId
- callBackUrl
- model
- prompt
properties:
defaultParamFlag:
type: boolean
description: >-
Controls parameter source for extension.
- If `true`: Use custom parameters specified in this
request. Requires `continueAt`, `prompt`, `style`, and
`title`.
- If `false`: Use original audio parameters. Only `audioId`
is required, other parameters are inherited.
example: true
audioId:
type: string
description: >-
Unique identifier of the audio track to extend. Required for
all extension requests.
example: e231****-****-****-****-****8cadc7dc
prompt:
type: string
description: >-
Description of the desired audio extension content.
- Required when `defaultParamFlag` is `true`.
- Character limits by model:
- **V4**: Maximum 3000 characters
- **V4_5 & V4_5PLUS**: Maximum 5000 characters
- **V4_5ALL**: Maximum 5000 characters
- **V5**: Maximum 5000 characters
- Describes how the music should continue or change in the
extension.
example: >-
Extend the music with more relaxing notes and a gentle
bridge section
style:
type: string
description: >-
Music style specification for the extended audio.
- Required when `defaultParamFlag` is `true`.
- Character limits by model:
- **V4**: Maximum 200 characters
- **V4_5 & V4_5PLUS**: Maximum 1000 characters
- **V4_5ALL**: Maximum 1000 characters
- **V5**: Maximum 1000 characters
- Should typically align with the original audio's style for
best results.
example: Classical
title:
type: string
description: |-
Title for the extended music track.
- Required when `defaultParamFlag` is `true`.
- Character limits by model:
- **V4**: Maximum 80 characters
- **V4_5 & V4_5PLUS**: Maximum 100 characters
- **V4_5ALL**: Maximum 80 characters
- **V5**: Maximum 100 characters
- Will be displayed in player interfaces and filenames.
example: Peaceful Piano Extended
continueAt:
type: number
description: >-
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 generated audio.
- Specifies the position in the original track where the
extension should begin.
example: 60
model:
type: string
description: |-
The AI model version to use for generation.
- Required for all requests.
- Available options:
- **`V5`**: Superior musical expression, faster generation.
- **`V4_5PLUS`**: V4.5+ delivers richer sound, new ways to create, max 8 min.
- **`V4_5`**: V4.5 enables smarter prompts, faster generations, max 8 min.
- **`V4_5ALL`**: V4.5ALL enables smarter prompts, faster generations, max 8 min.
- **`V4`**: V4 improves vocal quality, max 4 min.
enum:
- V4
- V4_5
- V4_5PLUS
- V4_5ALL
- V5
example: V4
callBackUrl:
type: string
format: uri
description: >-
The URL to receive music extension task completion updates.
Required for all music extension requests.
- System will POST task status and results to this URL when
extension completes
- Callback process has three stages: `text` (text
generation), `first` (first track complete), `complete` (all
tracks complete)
- Your callback endpoint should accept POST requests with
JSON payload containing extended track results and audio
URLs
- For detailed callback format and implementation guide, see
[Music Extension
Callbacks](https://docs.apikley.ru/suno-api/extend-music-callbacks)
- Alternatively, use the Get Music Details endpoint to poll
task status
example: https://api.example.com/callback
negativeTags:
type: string
description: >-
Music styles or traits to exclude from the extended audio.
Optional. Use to avoid specific undesired characteristics.
example: Heavy Metal, Upbeat Drums
vocalGender:
type: string
description: >-
Vocal gender preference for the singing voice. Optional. Use
'm' for male and 'f' for female. Based on practice, this
parameter can only increase the probability but cannot
guarantee adherence to male/female voice instructions.
enum:
- m
- f
example: m
styleWeight:
type: number
description: >-
Strength of adherence to the specified style. Optional.
Range 0–1, up to 2 decimal places.
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
weirdnessConstraint:
type: number
description: >-
Controls experimental/creative deviation. Optional. Range
0–1, up to 2 decimal places.
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
audioWeight:
type: number
description: >-
Balance weight for audio features vs. other factors.
Optional. Range 0–1, up to 2 decimal places.
minimum: 0
maximum: 1
multipleOf: 0.01
example: 0.65
personaId:
type: string
description: >-
Only available when Custom Mode (`customMode: true`) is
enabled. Persona ID to apply to the generated music.
Optional. 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
responses:
'200':
description: Request successful
content:
application/json:
schema:
allOf:
- type: object
properties:
code:
type: integer
enum:
- 200
- 401
- 402
- 404
- 409
- 422
- 429
- 451
- 455
- 500
description: >-
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
msg:
type: string
description: Error message when code != 200
example: success
- type: object
properties:
data:
type: object
properties:
taskId:
type: string
description: >-
Task ID for tracking task status. Use this ID with
the "Get Music Details" endpoint to query
extension task details and results.
example: 5c79****be8e
'500':
$ref: '#/components/responses/Error'
callbacks:
audioExtend:
'{$request.body#/callBackUrl}':
post:
description: >-
System will call this callback when audio generation is
complete.
### Callback Example
```json
{
"code": 200,
"msg": "All generated successfully.",
"data": {
"callbackType": "complete",
"task_id": "2fac****9f72",
"data": [
{
"id": "e231****-****-****-****-****8cadc7dc",
"audio_url": "https://example.cn/****.mp3",
"stream_audio_url": "https://example.cn/****",
"image_url": "https://example.cn/****.jpeg",
"prompt": "[Verse] Night city lights shining bright",
"model_name": "chirp-v3-5",
"title": "Iron Man",
"tags": "electrifying, rock",
"createTime": "2025-01-01 00:00:00",
"duration": 198.44
},
{
"id": "bd15****1873",
"audio_url": "https://example.cn/****.mp3",
"stream_audio_url": "https://example.cn/****",
"image_url": "https://example.cn/****.jpeg",
"prompt": "[Verse] Night city lights shining bright",
"model_name": "chirp-v3-5",
"title": "Iron Man",
"tags": "electrifying, rock",
"createTime": "2025-01-01 00:00:00",
"duration": 228.28
}
]
}
}
```
requestBody:
content:
application/json:
schema:
type: object
properties:
code:
type: integer
description: Status code
example: 200
msg:
type: string
description: Response message
example: All generated successfully
data:
type: object
properties:
callbackType:
type: string
description: >-
Callback type: text (text generation complete),
first (first track complete), complete (all
tracks complete)
enum:
- text
- first
- complete
task_id:
type: string
description: Task ID
data:
type: array
items:
type: object
properties:
id:
type: string
description: Audio unique identifier (audioId)
audio_url:
type: string
description: Audio file URL
stream_audio_url:
type: string
description: Streaming audio URL
image_url:
type: string
description: Cover image URL
prompt:
type: string
description: Generation prompt/lyrics
model_name:
type: string
description: Model name used
title:
type: string
description: Music title
tags:
type: string
description: Music tags
createTime:
type: string
description: Creation time
format: date-time
duration:
type: number
description: Audio duration (seconds)
responses:
'200':
description: Callback received successfully
content:
application/json:
schema:
allOf:
- type: object
properties:
code:
type: integer
enum:
- 200
- 400
- 408
- 413
- 500
- 501
- 531
description: >-
Response status code
- **200**: Success - Request has been
processed successfully
- **400**: Validation Error - Lyrics contained
copyrighted material.
- **408**: Rate Limited - Timeout.
- **413**: Conflict - Uploaded audio matches
existing work of art.
- **500**: Server Error - An unexpected error
occurred while processing the request
- **501**: Audio generation failed.
- **531**: Server Error - Sorry, the
generation failed due to an issue. Your
credits have been refunded. Please try again.
msg:
type: string
description: Error message when code != 200
example: success
example:
code: 200
msg: success
components:
responses:
Error:
description: Server Error
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: API Key
description: >-
All APIs require authentication via Bearer Token.
Get API Key:
1. Visit [API Key Management Page](https://app.apikley.ru/keys) to get your
API Key
Usage:
Add to request header:
Authorization: Bearer APIKLEY_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
To find navigation and other pages in this documentation, fetch the llms.txt file at: https://docs.apikley.ru/llms.txt