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.

​
Generate Song (v6)

  • The API supports both streaming and synchronous responses

​
Endpoints

  • POST /v6/generate/song - streaming
  • POST /v6/generate/song/sync - synchronous

​
Request Parameters

ParameterTypeDescriptionRequiredDefault Value
promptstringText prompt describing the desired song.YesN/A
lyricsstringLyrics for the song (generated if not provided).NoN/A
reference_urlstringURL of reference audio to guide the generation (optional).NoN/A
instrumental_urlstringURL of instrumental audio to incorporate (optional).NoN/A
vocal_urlstringURL of vocal audio to incorporate (optional).NoN/A
melody_urlstringURL of melody audio to guide the generation (optional).NoN/A

​
Example Request

{
  "prompt": "A cheerful pop song about friendship and adventure.",
  "lyrics": "Through every road we roam, together we are home"
}

​
Code Examples - Streaming

import requests
import json

url = "https://api.soundverse.ai/v6/generate/song"
headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "prompt": "A cheerful pop song about friendship and adventure.",
    "lyrics": "Through every road we roam, together we are home"
}

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

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

​
Code Examples - Synchronous

import requests

url = "https://api.soundverse.ai/v6/generate/song/sync"
headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "prompt": "A cheerful pop song about friendship and adventure.",
    "lyrics": "Through every road we roam, together we are home"
}

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

​
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 extension process.
chunkIndexintegerIndex of the current chunk in the streaming sequence.
message_idstringUnique identifier for the extension 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.
versionintegerVersion number of the generated audio.
audio_urlstringURL of the generated audio file.
errorstringError message if any issues occurred during processing.
operationstringType of operation being performed (e.g., “extend_song”).

​
Stages of Streaming Response

Initialization
sent immediately after the request is received 
data: {"isComplete": false, "status": "initializing", "chunkIndex": 0}
fields sent: isComplete, status, chunkIndex
Validation
validates the request and bills the user 
data: {"message_id": "...", "isComplete": false, "status": "validated", "album_art": "https://storage.soundverse.ai/...", "song_name": "Song Title", "chunkIndex": 1}
message_id can be used to track the request using the /status/generation/ endpoint
fields sent: message_id, isComplete, status, album_art, song_name, chunkIndex
Streaming
begins generating the content and streams updates 
data: {"message_id": "...", "isComplete": false, "status": "streaming", "album_art": "https://storage.soundverse.ai/...", "song_name": "Song Title", "chunkIndex": 2}
fields sent: message_id, isComplete, status, album_art, song_name, chunkIndex
Processing & Running
provides progress updates during generation 
data: {"message_id": "...", "isComplete": false, "chunkIndex": 3, "status": "processing", "album_art": "https://storage.soundverse.ai/...", "song_name": "Song Title"}
data: {"message_id": "...", "isComplete": false, "chunkIndex": 4, "status": "running", "album_art": "https://storage.soundverse.ai/...", "song_name": "Song Title", "progress": 2}
fields sent: message_id, isComplete, chunkIndex, status, album_art, song_name, progress
Streaming Ready
indicates that the stream url is ready and can be used for playback 
data: {"message_id": "...", "isComplete": false, "status": "streaming", "chunkIndex": 8, "stream_url": "https://api.soundverse.ai/...", "version": 1, "streaming_ready": true, "album_art": "https://storage.soundverse.ai/...", "song_name": "Song Title"}
fields sent: message_id, isComplete, status, chunkIndex, stream_url, version, streaming_ready, album_art, song_name
🛈 Note: Two versions of the generated content are created per request (version 1 and version 2).
Completed Generation
indicates that the generation is complete 
data: {"message_id": "...", "isComplete": false, "chunkIndex": 10, "status": "completed", "album_art": "https://storage.soundverse.ai/...", "audio_url": "https://storage.soundverse.ai/...", "song_name": "Song Title", "progress": 100}
fields sent: message_id, isComplete, chunkIndex, status, album_art, song_name, progress, audio_url
Uploading
indicates that the generated content is being uploaded for further processing 
data: {"message_id": "...", "isComplete": false, "status": "uploading", "version": 1, "chunkIndex": 11}
fields sent: message_id, isComplete, status, version, chunkIndex
Final Completed Response
provides the final details of the generated content including lyrics sections 
data: {"message_id": "...", "isComplete": false, "status": "completed", "version": 1, "lyrics_sections": [...], "chunkIndex": 12}
fields sent: message_id, isComplete, status, version, lyrics_sections, chunkIndex

​
Synchronous Response

​
Sample Synchronous Output

{
  "message_id": "...",
  "album_art": "https://storage.soundverse.ai/x-one/.../userData/album-arts/album_art_1766599034.webp",
  "song_name": "Midnight Drizzle Beats",
  "audio_data": [
    {
      "audio_url": "https://storage.soundverse.ai/x-one/.../userData/generated-audio/midnight_drizzle_beats_v1.mp3",
      "song_name": "Midnight Drizzle Beats",
    },
    {
      "audio_url": "https://storage.soundverse.ai/x-one/.../userData/generated-audio/midnight_drizzle_beats_v2.mp3",
      "song_name": "Midnight Drizzle Beats",
    }
  ] 
}

​
Possible Errors

Rate Limit Exceeded: 
{
  "success": false,
  "message": "Rate limits have been passed for the user."
}
Insufficient Balance: 
{
  "success": false,
  "message": "Insufficient balance for this operation."
}
Invalid Prompt: 
{
  "detail": "Invalid or empty prompt provided"
}
NSFW Content Detected: 
{
  "success": false,
  "message": "NSFW words detected. Please try again with different lyrics."
}
Service Unavailable: 
{
  "success": false,
  "message": "Service temporarily unavailable. Please try again in a moment.",
  "error": "Database connection pool exhausted"
}