Developers (API)

Beta

API Pricing Plans

This is pricing for the API only. Generating songs using our website is free!

FREE TRIAL: Simply by registering an account, you will receive 1,500 credits for FREE. This is enough to generate at least 15 songs to test out the API.

Currently, one 1 minute 35 second song costs 100 credits. Generating 2 songs in one request by setting num_songs to 2 costs 150 credits. This pricing is subject to change.

Any user-facing implementation of our API requires proper attribution to Sonauto.

Starter

$11/month

20,000 credits (200 songs) per month
Additional credits for $0.06 per 100 credits
Priority support

Pro

$88/month

160,000 credits (1,600 songs) per month
Additional credits for $0.06 per 100 credits
Priority support

Scale

$330/month

660,000 credits (6,600 songs) per month
Additional credits for $0.05 per 100 credits
Priority support

Enterprise

$1,150/month

2,875,000 credits (28,750 songs) per month
Additional credits for $0.04 per 100 credits
Priority support

Need an even bigger plan? Contact us.

Pay As You Go

Purchase credits as needed. Your current plan's price is $0.06 per 100 credits.

API Documentation

Our api domain is https://api.sonauto.ai/v1

Authentication

All endpoints require an API key to be passed in the Authorization header:

Authorization: Bearer your_api_key_here

Generation Endpoints

Core Parameters

For all generation endpoints, you must provide at least one of tags, lyrics, or prompt. If tags or lyrics is left blank, then it will be generated by AI based on the prompt. You can view a list of supported tags using our Tag Explorer.
Providing only lyrics or tags (without a prompt) is not supported. However, you can pass an empty string as the prompt to leave the style/lyrics entirely up to the AI.
For instrumental songs, set instrumental to true and don't pass any lyrics. In the instrumental case, only the tags or prompt can be set (where the prompt will only be used to generate tags).

Other Parameters

prompt_strength - Higher values result in less natural vocals but fewer hallucinations.
seed - The number used to seed the random number generator. The same tags and lyrics with the same seed will generate the same song.
webhook_url - This URL will receive POST requests while the song is being generated with status updates.
num_songs - The number of songs to generate. Must be 1 or 2. Generating 2 songs will use 150 credits instead of 100! Also, this value controls the length of the song_paths array returned by the status endpoint.

Output Audio Formats

The default output format is variable bitrate opus in an ogg container (a .ogg file). You can change this by setting the output_format option.
Supported formats: mp3, flac, wav, ogg (opus), m4a (aac)
Additionally, for mp3 and m4a, you can set a bitrate with the output_bit_rate option. This can be left null to use reasonable defaults. Supported bit rates for mp3 and m4a (in kbps): 128, 192, 256, 320.

Statuses

You can view the current status of your generation request using the GET /generations/{task_id} endpoint described below. Alternatively, you can specify a webhook_url to get updates in real-time. Either way, you will recieve the following status updates in order:

RECEIVED - Sent immediately after we parse your request.
TRANSCRIBE_TASK_STARTED (inpaint/extend only)
TRANSCRIBE_STAGE_1 (inpaint/extend only)
TRANSCRIBE_STAGE_2 (inpaint/extend only)
TRANSCRIBE_STAGE_3 (inpaint/extend only)
TRANSCRIBE_DONE (inpaint/extend only)
PROMPT - We are converting your prompt to tags and/or lyrics.
TASK_SENT - Everything is ready and we've sent your task to our GPU cluster.
GENERATE_TASK_STARTED - A GPU worker has been assigned to your task and has started working on it.
LOADING_SOURCE (inpaint/extend only) - We are fetching your source song to inpaint or extend.
BEGINNING_GENERATION - Sent right before your song starts generating.
GENERATING - The main event! Your song is being generated.
DECOMPRESSING - Decompressing your song from our latent space.
SAVING - Uploading your song to our CDN.
SUCCESS - Everything worked! Your song URL(s) will be posted in the body of this request at the key song_paths, or you can fetch them using the GET /generations/{task_id} endpoint. Note: These URLs expire and are not permanent. See Data Fetching Endpoints for more information.
FAILURE - Something went wrong. Don't worry, no credits were deducted. Please try again or contact us :)

POST

/generations

Generate a new 1 minute 35 second song. See the parameter details above.

Request Body

{
  "tags": "array[string] (optional)",
  "lyrics": "string (optional)",
  "prompt": "string (optional)",
  "instrumental": "boolean (default: false)",
  "prompt_strength": "float (default: 2.3)",
  "seed": "integer (optional)",
  "webhook_url": "string (optional)",
  "num_songs": "integer (default: 1)",
  "output_format": "string (default: ogg)",
  "output_bit_rate": "integer (optional)"
}

Code Samples

import requests

url = "https://api.sonauto.ai/v1/generations"
headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "tags": ["rock", "energetic"],
    "prompt": "An upbeat rock song with heavy guitar riffs"
}

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

Response

{
  "task_id": "string"
}

POST

/generations/extend

Extend an existing song.

Set the audio_url to the song you want to extend. This must be a publicly available URL. Alternatively, you can directly pass the audio file bytes as a base64 encoded string using the audio_base64 parameter (see the "Python (upload)" example below). Please note the the file size limit for base64 encoded audio is 40MB.
You can extend from the start or end of the song by setting the side to "left" or "right," respectively. extend_duration determines how much new audio to generate. This must be between 0 and 85.0 seconds.
Finally, the crop_duration can be used to crop the end (or start, depending on the value of side) of the original audio before extending.

Note

If you want to extend a generation you created with Sonauto, please set the audio_url to the path of the audio file on our CDN (instead of a version you downloaded, for instance). This will prevent quality degradation over time because, internally, we will reuse our latent representation of the song instead of re-encoding the audio.

Request Body

{
  "tags": "array[string] (optional)",
  "lyrics": "string (optional)",
  "prompt": "string (optional)",
  "instrumental": "boolean (default: false)",
  "prompt_strength": "float (default: 2.3)",
  "seed": "integer (optional)",
  "webhook_url": "string (optional)",
  "num_songs": "integer (default: 1)",
  "output_format": "string (default: ogg)",
  "output_bit_rate": "integer (optional)",
  "audio_url": "string (URL)",
  "audio_base64": "string (base64)",
  "side": "string (left | right)",
  "extend_duration": "float (optional)",
  "crop_duration": "float (default: 0.0)"
}

import requests

url = "https://api.sonauto.ai/v1/generations/extend"
headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "audio_url": "https://cdn.sonauto.ai/generations2/audio_a598194b-d464-474c-b1e6-1c99f8f8e457_0.ogg",
    "tags": ["rock", "energetic"],
    "prompt": "Write another verse for my song",
    "side": "right",
    "extend_duration": 45.0
}

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

Response

{
  "task_id": "string"
}

POST

/generations/inpaint

Replace sections of an existing audio with newly generated content.

Set the audio_url to the song you want to extend. This must be a publicly available URL. Alternatively, you can directly pass the audio file bytes as a base64 encoded string using the audio_base64 parameter (see the "Python (upload)" example below). Please note the the file size limit for base64 encoded audio is 40MB.
sections represents the sections you want to replace. Currently, it is only possible to inpaint one section. Thus, the outer list must be of length 1. The inner list must have two floats representing the start and end timestamps (in seconds) of the section to replace.
selection_crop will crop the final output to only contain the inpainted section.

Note

If you want to inpaint a generation you created with Sonauto, please set the audio_url to the path of the audio file on our CDN (instead of a version you downloaded, for instance). This will prevent quality degradation over time because, internally, we will reuse our latent representation of the song instead of re-encoding the audio.

Request Body

{
  "tags": "array[string] (optional)",
  "lyrics": "string",
  "prompt": "string (optional)",
  "instrumental": "boolean (default: false)",
  "prompt_strength": "float (default: 2.3)",
  "seed": "integer (optional)",
  "webhook_url": "string (optional)",
  "num_songs": "integer (default: 1)",
  "output_format": "string (default: ogg)",
  "output_bit_rate": "integer (optional)",
  "audio_url": "string (URL)",
  "audio_base64": "string (base64)",
  "sections": "array[array[float]]",
  "selection_crop": "boolean (default: false)"
}

import requests

url = "https://api.sonauto.ai/v1/generations/inpaint"
headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "audio_url": "https://cdn.sonauto.ai/generations2/audio_a598194b-d464-474c-b1e6-1c99f8f8e457_0.ogg",
    "tags": ["rock", "energetic"],
    "sections": [[0.0, 30.0]],
    "lyrics": "New lyrics for the sections"
}

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

Response

{
  "task_id": "string"
}

Data Fetching Endpoints

Important Details

Songs will be deleted from our severs one week (168 hours) after they were generated. This means the URLs in song_paths will not work after this time. In some circumstances, songs may be accessible after this time, but this is not guaranteed. Make sure to download any songs you want to keep!

GET

/generations/{task_id}

Retrieve the final generated song and all the parameters you used to generate it. The final audio URL is also sent over the webhook_url if you set it.

Code Samples

import requests

task_id = "your_task_id"
url = f"https://api.sonauto.ai/v1/generations/{task_id}"
headers = {
    "Authorization": "Bearer your_api_key_here"
}

response = requests.get(url, headers=headers)
print(response.json())

Response

{
  "id": "string (UUID)",
  "created_at": "string (ISO 8601 timestamp)",
  "status": "string",
  "song_paths": "array[string] (URLs)",
  "error_message": "string | null",
  "lyrics": "string",
  "prompt": "string | null",
  "prompt_strength": "float",
  "tags": "array[string]",
  "seed": "integer",
  "inpaint_params": {
    "sections": "array[array[float]]",
    "selection_crop": "boolean",
    "audio_url": "string (URL)",
    "lyrics": "string"
  },
  "extend_params": {
    "side": "string",
    "crop_duration": "float",
    "audio_url": "string (URL)",
    "duration": "float",
    "lyrics": "string"
  }
}

Field Descriptions

id: Unique identifier for the generation
created_at: Timestamp when the generation was created
status: Current status of the generation
song_paths: Array of URLs to the generated audio files
error_message: If the generation state is FAILURE, this may contain helpful information to understand what went wrong.
lyrics: Generated or provided lyrics
prompt: The prompt used for generation (if any)
prompt_strength: Strength of the prompt in generation
tags: Array of musical style tags
seed: Random seed used for generation
inpaint_params: Parameters used if this was an inpainting operation
extend_params: Parameters used if this was an extension operation

GET

/generations/status/{task_id}

Check the status of a generation task.

Parameters

task_id - The ID of the generation task

import requests

task_id = "your_task_id"
url = f"https://api.sonauto.ai/v1/generations/status/{task_id}"
headers = {
    "Authorization": "Bearer your_api_key_here"
}

response = requests.get(url, headers=headers)
print(response.json())

Response (not JSON)

'string (status)'

GET

/credits/balance

Check the number of credits you have left.

import requests

url = "https://api.sonauto.ai/v1/credits/balance"
headers = {
  "Authorization": "Bearer your_api_key_here"
}

response = requests.get(url, headers=headers)
print(response.json())

Response

{
  "num_credits": "integer",
  "num_credits_payg": "integer"
}

Field Descriptions

num_credits: The number of subscription credits remaining
num_credits_payg: The number of pay-as-you-go credits remaining