> ## Documentation Index
> Fetch the complete documentation index at: https://docs.musicgpt.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Extend
> This endpoint allows users to extend an existing audio file or stream by appending new audio content after a specific timestamp. The new audio is generated using a prompt (e.g., describing the desired sound) and optional lyrics.
Extend an existing audio file by generating new content after a specific timestamp.
***
## Endpoint
```http theme={null}
POST /extend
```
This endpoint allows users to extend an existing audio file or stream by appending new audio content after a specific timestamp. The new content is generated using a prompt and optional lyrics.
***
## Request Parameters
| Parameter | Type | Required | Description |
| -------------------------- | ------------ | -------- | -------------------------------------------------------------------------------- |
| `audio_file` | `UploadFile` | Optional | Upload the audio file to extend. Required if `audio_url` is not provided. |
| `audio_url` | `String` | Optional | Public or S3 URL to the input audio. Required if `audio_file` is not provided. |
| `extend_after` | `Float` | Required | Time (in seconds) after which new audio is generated. |
| `prompt` | `String` | Optional | Describes the desired extension sound. Example: "Add a melodic flute section" |
| `lyrics` | `String` | Optional | Original lyrics of song. Max 2000 characters. |
| `lyrics_section_to_extend` | `String` | Optional | Optional lyrics for the extended segment. Max 3000 characters. |
| `gender` | `String` | Optional | Voice style if vocals are generated. Must be one of `male`, `female`, `neutral`. |
| `num_outputs` | int | Optional | The number of outputs to generate (1 or 2 only, default : 2). |
| `webhook_url` | `String` | Optional | Callback URL for async result delivery. |
> 💡 **Note:** You must provide either `audio_file` or `audio_url` — at least one is required.
> **content-type:** multipart/form-data
***
## Sample Output
Listen to the extended audio.
Prompt: loud drums sound - audio input : Rose and Bruno Mars - APT
extend after: 6
Download Audio
***
## Try it Yourself
Visit the [Extend Endpoint Explorer](/api-documentation/endpoint/extend) to play around — set your payload, hit send, and listen to the generated results live.
***
## Sample Request
### cURL
```bash theme={null}
curl -X POST "https://api.musicgpt.com/api/public/v1/extend" \
-H "accept: application/json" \
-H "Authorization: " \
-F "audio_file=@/path/to/audio.mp3" \
-F "extend_after=35.0" \
-F "prompt=Add a calming piano outro" \
-F "lyrics=Let the journey fade away" \
-F "gender=neutral" \
-F "webhook_url=https://example.com/webhook"
```
### Python
```python theme={null}
import requests
url = "https://api.musicgpt.com/api/public/v1/extend"
headers = {"Authorization": ""}
data = {
"prompt": "Add a calming piano outro",
"lyrics": "Let the journey fade away",
"extend_after": 35.0,
"gender": "neutral",
"webhook_url": "https://example.com/webhook"
}
# Option 1: audio_url
files = {}
data["audio_url"] = "https://lalals.s3.amazonaws.com/audio/example.mp3"
response = requests.post(url, headers=headers, data=data, files=files)
# Option 2: File Upload
# with open("audio.mp3", "rb") as f:
# files = {"audio_file": f}
# response = requests.post(url, headers=headers, data=data, files=files)
# print(response.json())
```
> 🔐 Replace `{path_to_your_audio_file}`, `api_key`, and `webhook_url` before executing.
***
## Sample Response
### Success (200 OK)
```json theme={null}
{
"success": true,
"message": "Extend request submitted successfully",
"task_id": "task-extend-789",
"conversion_id_1": "extend-a1b2",
"conversion_id_2": "extend-c3d4",
"eta": 38,
"credit_estimate": 42
}
```
***
## Webhook Response
When the extension process completes, the webhook receives:
```json theme={null}
{
"success": true,
"conversion_type": "Extend",
"task_id": "task-extend-789",
"conversion_id": "extend-a1b2",
"conversion_path": "https://lalals.s3.amazonaws.com/conversions/extend-a1b2.mp3",
"conversion_path_wav": "https://lalals.s3.amazonaws.com/conversions/extend-a1b2.wav",
"conversion_duration": 192.12,
"is_flagged": false,
"reason": "",
"lyrics": "Let the journey fade away",
"lyrics_timestamped": [],
"title": "Outro Symphony"
}
```
***
## Webhook Delivery
Once the generation is complete, **webhooks** will be triggered to deliver the following:
#### Standard Requests (non-instrumental):
* 2 (webhooks) x Extend conversion details (one per version)
* 2 (webhooks) x Lyrics with timestamp data
* 1 Album Cover Image
> Webhook responses include detailed metadata including task\_id, conversion\_id, audio files (conversion\_path), lyrics etc.
***
## Common Errors
* **422 Unprocessable Entity**: Missing required fields like `extend_after`, or neither `audio_file` nor `audio_url` provided.
* **500 Internal Server Error**: An unexpected error occurred during processing.
***
The response provides a downloadable or streamable extended audio file.
## OpenAPI
````yaml POST /v1/extend
openapi: 3.1.0
info:
title: Musicgpt API
version: 1.0.0
description: API for retrieving conversion details by ID.
servers:
- url: https://api.musicgpt.com/api/public
description: Production server
security: []
paths:
/v1/extend:
post:
summary: Extend Audio Using Prompt and Optional Lyrics
description: >-
This endpoint allows users to extend an existing audio file or stream by
appending new audio content after a specific timestamp. The new audio is
generated using a prompt (e.g., describing the desired sound) and
optional lyrics.
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
audio_file:
type: string
format: binary
description: Uploaded audio file to be extended.
audio_url:
type: string
description: URL or S3 path to the input audio.
example: https://mybucket.s3.amazonaws.com/song.mp3
extend_after:
type: number
format: float
description: Time in seconds after which to start the extension.
example: 35
prompt:
type: string
description: Describes how the extended section should sound.
example: Add a calming piano outro
lyrics:
type: string
description: Original lyrics of song
example: Let the journey fade away
maxLength: 2000
lyrics_section_to_extend:
type: string
description: >-
Lyrics to be used for the extended portion(optional, max
3000 characters).
maxLength: 3000
gender:
type: string
description: Voice style if vocal content is generated.
enum:
- male
- female
- neutral
example: neutral
num_outputs:
type: number
format: integer
description: >-
The number of outputs to generate (1 or 2 only):default is
2.
webhook_url:
type: string
description: Callback URL for async processing results.
example: https://example.com/webhook
required:
- extend_after
anyOf:
- required:
- audio_url
- required:
- audio_file
responses:
'200':
description: Successfully initiated extend task
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
task_id:
type: string
conversion_id_1:
type: string
conversion_id_2:
type: string
eta:
type: integer
description: Estimated processing time in seconds
credit_estimate:
type: number
format: float
example:
success: true
message: Extend request submitted successfully
task_id: task-extend-789
conversion_id_1: extend-a1b2
conversion_id_2: extend-c3d4
eta: 38
credit_estimate: 42
'422':
description: Validation Error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: audio_file or audio_url and extend_after are required.
'500':
description: Server Error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
example: false
error:
type: string
example: Internal Server Error
security:
- ApiKeyAuth: []
x-codeSamples:
- lang: Python
source: >-
import requests
url = "https://api.musicgpt.com/api/public/v1/extend"
headers = {"Authorization": ""}
data = {
"extend_after": 35.0,
"prompt": "Add a calming piano outro",
"lyrics": "Let the journey fade away",
"gender": "neutral",
"lyrics_section_to_extend": "New lyrics",
"num_outputs": 1,
"webhook_url": "https://example.com/webhook"
}
# Option 1: audio_url
data["audio_url"] = "https://mybucket.s3.amazonaws.com/song.mp3"
response = requests.post(url, headers=headers, data=data)
# Option 2: File Upload
# with open("song.mp3", "rb") as f:
# files = {"audio_file": f}
# response = requests.post(url, headers=headers, data=data,
files=files)
# print(response.json())
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
````