Skip to main content

Documentation Index

Fetch the complete documentation index at: https://help.soundverse.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
AI Remix (v7)

  • The API supports streaming responses only.
  • Provide an existing song as a reference URL and a style prompt to generate a remixed version.

​
Endpoint

  • /v7/generate/remix - streaming

​
Request Parameters

ParameterTypeDescriptionRequiredDefault Value
song_reference_urlstringPublicly accessible URL of the source audio file to remix (max 10 MB, 10–350 s).YesN/A
promptstringStyle or genre prompt for the remix (e.g. "jazz remix with horns"). At least one of prompt or lyrics is required.ConditionalN/A
lyricsstringNew lyrics for the remixed track. Falls back to prompt if omitted. At least one of prompt or lyrics is required.ConditionalN/A
parametersobjectAdditional generation parameters passed through to the model.No{}

​
Example Request

{
  "song_reference_url": "https://storage.soundverse.ai/.../original_song.mp3",
  "prompt": "upbeat jazz remix with brass horns"
}

​
Code Examples

import requests
import json

url = "https://api.soundverse.ai/v7/generate/remix"
headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "song_reference_url": "https://storage.soundverse.ai/.../original_song.mp3",
    "prompt": "upbeat jazz remix with brass horns"
}

response = requests.post(url, json=payload, headers=headers, stream=True)

for line in response.iter_lines():
    if line:
        text = line.decode('utf-8')
        if text.startswith('data: '):
            data = json.loads(text[6:])
            print(data)

​
Streaming Response

​
Fields

🛈 The fields below are used in the chunks sent by SSE during the streaming process.
ParameterTypeDescription
isCompleteboolIndicates if the streaming response is complete.
statusstringCurrent status of the remix process.
chunkIndexintegerIndex of the current chunk in the streaming sequence.
message_idstringUnique identifier for the remix request.
stream_urlstringURL to access the generated audio stream when ready.
versionintegerVersion of the generated content.
album_artstringURL of the album art associated with the generated content.
song_namestringName of the generated track.
progressintegerProgress percentage of the generation process (0–100).
streaming_readyboolIndicates if audio is ready for streaming.
audio_urlstringURL of the final generated audio file.
errorstringError message if any issues occurred during processing.
operationstringType of operation being performed ("remix_song").

​
Stages of Streaming Response

Validating
sent immediately after the request is received and validated 
data: {"isComplete": false, "status": "validating", "chunkIndex": 0}
Queued
request has been accepted and is waiting to be processed 
data: {"message_id": "...", "isComplete": false, "status": "queued", "album_art": "https://storage.soundverse.ai/...", "song_name": "Remix Title", "chunkIndex": 1}
message_id can be used to track the request using the /status/generation/ endpoint
Starting / Initializing
the remix job is being prepared 
data: {"message_id": "...", "isComplete": false, "status": "starting", "chunkIndex": 2}
data: {"message_id": "...", "isComplete": false, "status": "initializing", "chunkIndex": 3}
Uploading
the reference audio is being uploaded to the model 
data: {"message_id": "...", "isComplete": false, "status": "uploading", "chunkIndex": 4}
Streaming (with progress)
remix is generating; progress increments from 0 to 100 
data: {"message_id": "...", "isComplete": false, "status": "streaming", "progress": 0, "chunkIndex": 5}
data: {"message_id": "...", "isComplete": false, "status": "streaming", "progress": 50, "chunkIndex": 6}
data: {"message_id": "...", "isComplete": false, "status": "streaming", "progress": 100, "stream_url": "https://api.soundverse.ai/...", "streaming_ready": true, "version": 1, "chunkIndex": 7}
Note: progress may hold at 90 for several minutes while the model finalizes and uploads the output audio. This is expected. The SSE connection remains open and active during this time. The stream will resume with a completed chunk and audio_url once the file is ready.
Completed
remix is finished and the final audio is available 
data: {"message_id": "...", "isComplete": true, "status": "completed", "audio_url": "https://storage.soundverse.ai/...", "album_art": "https://storage.soundverse.ai/...", "song_name": "Remix Title", "progress": 100, "chunkIndex": 8}

​
Possible Errors

Missing prompt and lyrics: 
{
  "detail": "Either prompt or lyrics must be provided"
}
Reference audio too large (> 10 MB): 
{
  "success": false,
  "message": "Reference audio error: File too large: 12657318 bytes (max: 10485760)"
}
Rate Limit Exceeded: 
{
  "success": false,
  "message": "Rate limits have been passed for the user."
}
Insufficient Balance: 
{
  "success": false,
  "message": "Insufficient balance for this operation."
}
Service Unavailable: 
{
  "success": false,
  "message": "Service temporarily unavailable. Please try again in a moment.",
  "error": "Database connection pool exhausted"
}