Skip to main content

​
Generate Song (v7)

  • The API supports both streaming and synchronous responses.
  • Every streaming response begins with a job_created event containing a job_id, allowing you to safely disconnect and poll /v7/status for the result.

​
Endpoints

  • /v7/generate/song - streaming
  • /v7/generate/song/sync - synchronous

​
Request Parameters

At least one of prompt or an audio URL (reference_url, instrumental_url, vocal_url, melody_url) must be provided.
ParameterTypeDescriptionRequiredConstraints
promptstringText prompt describing the desired song.ConditionalMax 1024 chars
lyricsstringLyrics for the song. Generated automatically if not provided.No—
reference_urlstringURL of reference audio to guide the style of the generation.ConditionalMax 10 MB
instrumental_urlstringURL of instrumental audio to incorporate into the song.ConditionalMax 10 MB
vocal_urlstringURL of vocal audio to incorporate into the song.ConditionalMax 10 MB
melody_urlstringURL of melody audio to guide the melodic direction of the generation.ConditionalMax 10 MB

​
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/v7/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)

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/v7/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. Not all fields appear in every chunk — see the stage breakdown below.
ParameterTypeDescription
typestringEvent type. "job_created" on the first chunk only.
job_idstringPersistent job identifier. Use this to poll /v7/status if you disconnect.
message_idstringUnique identifier for the generation request.
isCompletebooltrue only on the final chunk of the stream.
statusstringCurrent status. One of: validated, streaming, uploading, completed, failed.
chunkIndexintegerIndex of the current chunk in the streaming sequence.
operationstringOperation type. "song_generate" (prompt only) or "song_with_reference" (audio URLs).
contentstringHuman-readable description of the current stage.
album_artstringURL of the generated album art.
song_namestringName of the generated track.
versionintegerVersion number of the audio output (1 or 2).
task_idstringInternal task identifier for the generation job.
stream_urlstringProxy URL for previewing audio before the final upload is complete.
streaming_readybooltrue when the preview stream URL is ready for playback.
audio_urlstringFinal URL of the uploaded audio file.
audio_idstringDatabase ID of the generated audio asset.
audio_readybooltrue when the final audio file is available for download.
durationfloatDuration of the generated audio in seconds.
bpmintegerBeats per minute of the generated track.
lyrics_sectionsarrayStructured lyrics broken into labelled sections with timestamps.
tokensintegerTokens consumed by this chunk.
totalTokensintegerTotal tokens consumed for the request so far.
total_versionsintegerTotal number of audio versions generated. Sent in the final completed chunk.
errorbooltrue if this chunk represents an error.
detailstringError detail message when error is true.

​
Stages of Streaming Response

Job Created
always the very first chunk; guarantees job_id is available before any processing begins 
data: {"type": "job_created", "job_id": "...", "message_id": "...", "status": "processing", "isComplete": false, "chunkIndex": 0}
Save job_id immediately — if your connection drops, you can resume tracking via /v7/status.
fields sent: type, job_id, message_id, status, isComplete, chunkIndex
Validated
request has been validated and billing authorised; song name and album art are assigned 
data: {"message_id": "...", "status": "validated", "isComplete": false, "album_art": "https://storage.soundverse.ai/...", "song_name": "Song Title", "operation": "song_generate", "content": "Request validated", "chunkIndex": 1}
fields sent: message_id, status, isComplete, album_art, song_name, operation, content, chunkIndex
Streaming
audio generation is in progress; sent once per version when the preview stream becomes available 
data: {"message_id": "...", "status": "streaming", "isComplete": false, "version": 1, "task_id": "...", "stream_url": "https://api.soundverse.ai/...", "streaming_ready": true, "content": "Streaming audio...", "chunkIndex": 2}
fields sent: message_id, status, isComplete, version, task_id, stream_url, streaming_ready, content, chunkIndex
🛈 Two versions are generated per request (version: 1 and version: 2). A separate streaming chunk is sent for each version.
Uploading
generated audio is being uploaded to permanent storage 
data: {"message_id": "...", "status": "uploading", "isComplete": false, "version": 1, "content": "Uploading audio...", "chunkIndex": 3}
fields sent: message_id, status, isComplete, version, content, chunkIndex
Completed (per version)
final audio file is ready; includes the permanent URL and metadata for that version 
data: {"message_id": "...", "status": "completed", "isComplete": false, "version": 1, "audio_url": "https://storage.soundverse.ai/...", "audio_id": "...", "audio_ready": true, "duration": 60.0, "bpm": 120, "lyrics_sections": [...], "tokens": 100, "totalTokens": 200, "content": "Audio ready", "chunkIndex": 4}
fields sent: message_id, status, isComplete, version, audio_url, audio_id, audio_ready, duration, bpm, lyrics_sections, tokens, totalTokens, content, chunkIndex
Completed (final)
stream termination; confirms all versions are done 
data: {"message_id": "...", "status": "completed", "isComplete": true, "operation": "song_generate", "total_versions": 2, "album_art": "https://storage.soundverse.ai/...", "song_name": "Song Title", "content": "Generation complete", "chunkIndex": 5}
fields sent: message_id, status, isComplete, operation, total_versions, album_art, song_name, content, chunkIndex

​
Synchronous Response

​
Sample Synchronous Output

{
  "job_id": "...",
  "message_id": "...",
  "album_art": "https://storage.soundverse.ai/x-one/.../userData/album-arts/album_art_1766599034.webp",
  "audio_data": [
    {
      "audio_url": "https://storage.soundverse.ai/x-one/.../userData/generated-audio/song_title_v1.mp3",
      "song_name": "Song Title"
    },
    {
      "audio_url": "https://storage.soundverse.ai/x-one/.../userData/generated-audio/song_title_v2.mp3",
      "song_name": "Song Title"
    }
  ]
}

​
Possible Errors

Missing prompt and audio URL: 
{
  "detail": "Either prompt or at least one of reference_url, instrumental_url, vocal_url, or melody_url must be provided"
}
Prompt too long (> 1024 characters): 
{
  "detail": "Prompt exceeds maximum length of 1024 characters"
}
Audio file too large (> 10 MB): 
{
  "success": false,
  "message": "Reference audio file error: File too large"
}
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"
}