Sonauto API

https://sonauto.ai/developers
Admin
The Sonauto API provides programmatic access to generate, extend, and manipulate AI-created music,...
Tokens:12,551
Snippets:66
Trust Score:9.2
Update:8 months ago
Show doc for...
Tokens:
Raw
### Stream Audio with HTML

Source: https://sonauto.ai/developers/index

Embeds a streaming audio source directly into an HTML page for real-time playback of v3 generation. This example uses the `<audio>` tag with the `src` attribute pointing to the Sonauto AI streaming endpoint.

```html
<audio controls autoplay>
  <source src="https://api-stream.sonauto.ai/stream/your_task_id" type="audio/ogg" />
</audio>
```

--------------------------------

### GET /credits/balance

Source: https://sonauto.ai/developers/index

Retrieves the current credit balance for the account.

```APIDOC
## GET /credits/balance

### Description
Check the number of credits you have left on your account.

### Method
GET

### Endpoint
`/credits/balance`

### Parameters
This endpoint does not require any parameters.

### Request Example
```python
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
#### Success Response (200)
Returns a JSON object containing the subscription and pay-as-you-go credit balances.

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

- **num_credits** (integer) - The number of subscription credits remaining.
- **num_credits_payg** (integer) - The number of pay-as-you-go credits remaining.

#### Response Example
```json
{
  "num_credits": 150,
  "num_credits_payg": 25
}
```
```

--------------------------------

### GET /generations/{task_id}

Source: https://sonauto.ai/developers/index

Retrieve the final generated song and all the parameters used for its generation. The audio URL is also sent via the webhook if provided.

```APIDOC
## GET /generations/{task_id}

### Description
Retrieve the final generated song and all the parameters used for its generation. The audio URL is also sent via the webhook if provided.

### Method
GET

### Endpoint
/generations/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The ID of the generation task.

#### Query Parameters
None

### Request Example
```
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
#### Success Response (200)
- **id** (string) - Unique identifier for the generation (UUID).
- **created_at** (string) - ISO 8601 timestamp of when the generation was created.
- **status** (string) - Current status of the generation task (e.g., 'processing', 'completed', 'failed').
- **alignment_status** (string | null) - Status of lyric alignment, if applicable.
- **model_version** (string) - The version of the model used for generation (e.g., 'v2.2', 'v3-preview').
- **song_paths** (array[string]) - URLs to the generated audio files. These URLs expire one week after generation.
- **error_message** (string | null) - If the task failed, this contains an error message.
- **lyrics** (string) - The lyrics used for the generation.
- **prompt** (string | null) - The text prompt used, if any.
- **prompt_strength** (float) - The strength of the prompt.
- **tags** (array[string]) - Tags associated with the generation.
- **v2_params** (object) - Parameters specific to v2 generation.
  - **balance_strength** (float) - Controls the balance between prompt and original audio.
  - **seed** (integer) - Seed for reproducible generation.
  - **bpm** ('auto' | integer | null) - Beats per minute for the audio.
- **inpaint_params** (object) - Parameters used for inpainting.
  - **sections** (array[array[float]]) - The sections that were inpainted.
  - **selection_crop** (boolean) - Whether the output was cropped to the inpainted section.
  - **audio_url** (string) - The URL of the original audio used for inpainting.
  - **lyrics** (string) - The lyrics used for the inpainting.
- **extend_params** (object) - Parameters used for extending audio.
  - **side** (string) - The side of the audio that was extended ('start' or 'end').
  - **crop_duration** (float) - Duration to crop from the original audio before extending.
  - **audio_url** (string) - The URL of the original audio used for extending.
  - **duration** (float) - The desired duration of the extended audio.
  - **lyrics** (string) - The lyrics used for the extension.

#### Response Example
```json
{
  "id": "string (UUID)",
  "created_at": "string (ISO 8601 timestamp)",
  "status": "string",
  "alignment_status": "string | null",
  "model_version": "string (e.g. 'v2.2', 'v3-preview')",
  "song_paths": [
    "string (URLs)"
  ],
  "error_message": "string | null",
  "lyrics": "string",
  "prompt": "string | null",
  "prompt_strength": "float",
  "tags": [
    "string"
  ],
  "v2_params": {
    "balance_strength": "float",
    "seed": "integer",
    "bpm": "'auto' | integer | null"
  },
  "inpaint_params": {
    "sections": [
      [
        "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"
  }
}
```
```

--------------------------------

### Check Generation Status with cURL

Source: https://sonauto.ai/developers/index

A cURL command to check the status of a generation task. This example shows how to make a GET request to the Sonauto AI API, including the necessary Authorization header with your API key.

```bash
curl -X GET "https://api.sonauto.ai/v1/generations/status/your_task_id" \
     -H "Authorization: Bearer your_api_key_here"
```

--------------------------------

### GET /generations/status/{task_id}

Source: https://sonauto.ai/developers/index

Retrieves the status of a music generation task. Optionally includes alignment status.

```APIDOC
## GET /generations/status/{task_id}

### Description
Check the status of a generation task. This endpoint can optionally return both the generation status and the lyrics alignment status.

### Method
GET

### Endpoint
`/generations/status/{task_id}`

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The ID of the generation task.

#### Query Parameters
- **include_alignment** (boolean) - Optional - Defaults to `false`. When `true`, returns a JSON object with both the generation status and alignment status. Alignment is an optional post-processing step that syncs lyrics to the audio.

### Request Example
```python
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
#### Success Response (200)
By default, returns a plain string with the generation status (e.g., `"SUCCESS"`).

With `include_alignment=true`, returns a JSON object:
```json
{
  "status": "string",
  "alignment_status": "string | null"
}
```

- **status** (string) - The current status of the generation.
- **alignment_status** (string | null) - The status of lyrics alignment post-processing (null if alignment was not requested).

#### Response Example (Default)
```
"GENERATING"
```

#### Response Example (with include_alignment=true)
```json
{
  "status": "SUCCESS",
  "alignment_status": "SUCCESS"
}
```
```

--------------------------------

### Extend Song (Python)

Source: https://sonauto.ai/developers/index

Extends an existing song using the v2 model. Requires an API key for authorization. Can extend from the start or end of the song, specifying the duration and optional crop duration. Accepts audio URL or base64 encoded audio bytes.

```python
import requests

url = "https://api.sonauto.ai/v1/generations/v2/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())
```

--------------------------------

### Extend Song (cURL)

Source: https://sonauto.ai/developers/index

Extends an existing song using the v2 model via cURL. Requires an API key for authorization. Can extend from the start or end of the song, specifying the duration and optional crop duration. Accepts audio URL or base64 encoded audio bytes.

```bash
curl -X POST "https://api.sonauto.ai/v1/generations/v2/extend" \
     -H "Authorization: Bearer your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{ "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 }'
```

--------------------------------

### GET /generations/{task_id}

Source: https://sonauto.ai/developers/index

Retrieve the current status and song paths for a specific generation task using its task ID.

```APIDOC
## GET /generations/{task_id}

### Description
Retrieve the current status and song paths for a specific generation task using its task ID. This endpoint can be polled to check the progress of a song generation request.

### Method
GET

### Endpoint
/generations/{task_id}

### Parameters
#### Path Parameters
* **task_id** (string) - Required - The unique identifier for the generation task.

### Response
#### Success Response (200)
* **task_id** (string) - The unique identifier for the generation task.
* **status** (string) - The current status of the generation task (e.g., RECEIVED, GENERATING, SUCCESS, FAILURE).
* **song_paths** (array) - An array of URLs to the generated song(s). This field is populated upon successful generation. Note: These URLs expire.

#### Response Example
```json
{
  "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "status": "GENERATING",
  "song_paths": []
}
```

#### Error Response (404)
* **message** (string) - Error message indicating the task was not found.

#### Error Response Example
```json
{
  "message": "Generation task not found."
}
```
```

--------------------------------

### Check Generation Status with Alignment (Python)

Source: https://sonauto.ai/developers/index

Checks the status of a generation task and includes alignment status if requested. This Python code snippet demonstrates how to query the API with the `include_alignment=true` parameter to get both generation and alignment statuses.

```python
import requests

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

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

--------------------------------

### Check Credit Balance with Python

Source: https://sonauto.ai/developers/index

Retrieves the remaining credit balance using the Sonauto AI API. This Python script utilizes the 'requests' library to send a GET request to the /credits/balance endpoint, requiring an API key for authentication.

```python
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())
```

--------------------------------

### Check Generation Status with Python

Source: https://sonauto.ai/developers/index

Retrieves the status of a music generation task using the provided task ID. This Python script uses the 'requests' library to make a GET request to the API. It requires an API key for authorization and prints the JSON response, which typically indicates the generation status.

```python
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())  # Returns: "GENERATING"
```

--------------------------------

### Check Generation and Alignment Status (JSON)

Source: https://sonauto.ai/developers/index

This JSON object demonstrates how to check the status of both a generation and its associated lyric alignment. The `status` field indicates the main generation's state, while `alignment_status` shows the progress of the lyric alignment process. This is typically retrieved using a GET request to an API endpoint.

```json
{
  "status": "SUCCESS",
  "alignment_status": "ALIGNING"
}
```

--------------------------------

### Generate Song with v3 Model (cURL)

Source: https://sonauto.ai/developers/index

Generates a new song using the v3 model via cURL. Requires an API key for authorization. Accepts optional tags, lyrics, prompt, instrumental flag, prompt strength, webhook URL, output format, output bit rate, streaming enablement, stream format, and lyric alignment.

```bash
curl -X POST "https://api.sonauto.ai/v1/generations/v3" \
     -H "Authorization: Bearer your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{ "tags": ["rock", "energetic"], "prompt": "An upbeat rock song with heavy guitar riffs" }'
```

--------------------------------

### Generate Song with v3 Model (Python)

Source: https://sonauto.ai/developers/index

Generates a new song using the v3 model. Requires an API key for authorization. Accepts optional tags, lyrics, prompt, instrumental flag, prompt strength, webhook URL, output format, output bit rate, streaming enablement, stream format, and lyric alignment.

```python
import requests

url = "https://api.sonauto.ai/v1/generations/v3"
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())
```

--------------------------------

### Generate Song with v2 Model (Python)

Source: https://sonauto.ai/developers/index

Generates a new song using the v2 model. Requires an API key for authorization. Accepts optional tags, lyrics, prompt, instrumental flag, prompt strength, balance strength, seed, webhook URL, number of songs, output format, output bit rate, lyric alignment, and BPM.

```python
import requests

url = "https://api.sonauto.ai/v1/generations/v2"
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())
```

--------------------------------

### Generate Song with v2 Model (cURL)

Source: https://sonauto.ai/developers/index

Generates a new song using the v2 model via cURL. Requires an API key for authorization. Accepts optional tags, lyrics, prompt, instrumental flag, prompt strength, balance strength, seed, webhook URL, number of songs, output format, output bit rate, lyric alignment, and BPM.

```bash
curl -X POST "https://api.sonauto.ai/v1/generations/v2" \
     -H "Authorization: Bearer your_api_key_here" \
     -H "Content-Type: application/json" \
     -d '{ "tags": ["rock", "energetic"], "prompt": "An upbeat rock song with heavy guitar riffs" }'
```

--------------------------------

### Inpaint Audio Sections using URL (Python)

Source: https://sonauto.ai/developers/index

Replaces specified sections of an existing audio file with newly generated content using a provided audio URL. Requires an API key for authentication. The response contains a task ID for tracking the generation process.

```Python
import requests

url = "https://api.sonauto.ai/v1/generations/v2/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())
```

--------------------------------

### POST /v1/generations/v2

Source: https://sonauto.ai/developers/index

Generates a new song using the v2 model, with specific parameters for duration and tempo control.

```APIDOC
## POST /v1/generations/v2

### Description
Generates a new song using the v2 model, with specific parameters for duration and tempo control.

### Method
POST

### Endpoint
/v1/generations/v2

### Parameters
#### Request Body
- **tags** (array[string]) - Optional - Tags to categorize the song.
- **lyrics** (string) - Optional - Lyrics for the song.
- **prompt** (string) - Optional - A text prompt describing the desired song.
- **instrumental** (boolean) - Optional (default: false) - Whether to generate an instrumental track.
- **prompt_strength** (float) - Required - Strength of the prompt's influence.
- **balance_strength** (float) - Optional (default: 0.7) - Strength of the balance between different audio elements.
- **seed** (integer) - Optional - Seed for reproducible generation.
- **webhook_url** (string) - Optional - URL to send notifications to upon completion.
- **num_songs** (integer) - Optional (default: 1) - Number of songs to generate.
- **output_format** (string) - Optional (default: ogg) - Desired audio output format.
- **output_bit_rate** (integer) - Optional - Desired audio bit rate.
- **align_lyrics** (boolean) - Optional (default: false) - Whether to align lyrics with the audio.
- **bpm** ('auto' or integer) - Optional - Beats per minute of the song. Can be set to 'auto' or an integer. Set to null to not condition on BPM.

### Request Example
```json
{
  "tags": ["rock", "energetic"],
  "prompt": "An upbeat rock song with heavy guitar riffs"
}
```

### Response
#### Success Response (200)
- **task_id** (string) - The unique identifier for the generation task.

#### Response Example
```json
{
  "task_id": "string"
}
```
```

--------------------------------

### POST /generations/v2/inpaint

Source: https://sonauto.ai/developers/index

Replace sections of an existing audio with newly generated content. You can provide the audio via a URL or as a base64 encoded string.

```APIDOC
## POST /generations/v2/inpaint

### Description
Replace sections of an existing audio with newly generated content. You can provide the audio via a URL or as a base64 encoded string.

### Method
POST

### Endpoint
/generations/v2/inpaint

### Parameters
#### Query Parameters
None

#### Request Body
- **audio_url** (string) - URL of the audio file to modify. Required if `audio_base64` is not provided.
- **audio_base64** (string) - Base64 encoded audio file bytes. Max 40MB. Required if `audio_url` is not provided.
- **sections** (array[array[float]]) - A list containing one inner list with two floats representing the start and end timestamps (in seconds) of the section to replace. Currently, only one section can be inpainted.
- **selection_crop** (boolean) - Optional. Defaults to false. If true, crops the final output to only contain the inpainted section.
- **tags** (array[string]) - Optional. Tags for the generated audio.
- **lyrics** (string) - The lyrics for the inpainted section.
- **prompt** (string) - Optional. A text prompt to guide the generation.
- **instrumental** (boolean) - Optional. Defaults to false. If true, generates instrumental audio.
- **prompt_strength** (float) - The strength of the prompt.
- **balance_strength** (float) - Optional. Defaults to 0.7. Controls the balance between prompt and original audio.
- **seed** (integer) - Optional. Seed for reproducible generation.
- **webhook_url** (string) - Optional. URL to send notifications to upon task completion.
- **num_songs** (integer) - Optional. Defaults to 1. The number of songs to generate.
- **output_format** (string) - Optional. Defaults to 'ogg'. The desired output audio format.
- **output_bit_rate** (integer) - Optional. The desired output audio bit rate.
- **align_lyrics** (boolean) - Optional. Defaults to false. If true, attempts to align lyrics with the audio.

### Request Example
```json
{
  "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
#### Success Response (200)
- **task_id** (string) - The ID of the submitted task.

#### Response Example
```json
{
  "task_id": "string"
}
```
```

--------------------------------

### POST /v1/generations/v3

Source: https://sonauto.ai/developers/index

Generates a new song using the v3 model. This endpoint allows for detailed customization through various optional parameters.

```APIDOC
## POST /v1/generations/v3

### Description
Generates a new song using the v3 model. This endpoint allows for detailed customization through various optional parameters.

### Method
POST

### Endpoint
/v1/generations/v3

### Parameters
#### Request Body
- **tags** (array[string]) - Optional - Tags to categorize the song.
- **lyrics** (string) - Optional - Lyrics for the song.
- **prompt** (string) - Optional - A text prompt describing the desired song.
- **instrumental** (boolean) - Optional (default: false) - Whether to generate an instrumental track.
- **prompt_strength** (float) - Optional (default: 2.0) - Strength of the prompt's influence.
- **webhook_url** (string) - Optional - URL to send notifications to upon completion.
- **output_format** (string) - Optional (default: ogg) - Desired audio output format.
- **output_bit_rate** (integer) - Optional - Desired audio bit rate.
- **enable_streaming** (boolean) - Optional (default: false) - Whether to enable audio streaming.
- **stream_format** (string) - Optional (default: ogg, options: 'ogg' | 'mp3') - Format for streaming audio.
- **align_lyrics** (boolean) - Optional (default: false) - Whether to align lyrics with the audio.

### Request Example
```json
{
  "tags": ["rock", "energetic"],
  "prompt": "An upbeat rock song with heavy guitar riffs"
}
```

### Response
#### Success Response (200)
- **task_id** (string) - The unique identifier for the generation task.

#### Response Example
```json
{
  "task_id": "string"
}
```
```

--------------------------------

### Authentication

Source: https://sonauto.ai/developers/index

All endpoints require an API key for authentication.

```APIDOC
## Authentication

### Description
All endpoints require an API key to be passed in the Authorization header.

### Method
All

### Endpoint
All

### Headers
- **Authorization** (string) - Required - Bearer token format.

### Request Example
```
Authorization: Bearer your_api_key_here
```
```

--------------------------------

### POST /v1/generations/v2/extend

Source: https://sonauto.ai/developers/index

Extends an existing song by adding new audio content to either the beginning or the end.

```APIDOC
## POST /v1/generations/v2/extend

### Description
Extends an existing song by adding new audio content to either the beginning or the end.

### Method
POST

### Endpoint
/v1/generations/v2/extend

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **tags** (array[string]) - Optional - Tags to categorize the song.
- **lyrics** (string) - Optional - Lyrics for the song.
- **prompt** (string) - Optional - A text prompt describing the desired extension.
- **instrumental** (boolean) - Optional (default: false) - Whether to generate an instrumental extension.
- **prompt_strength** (float) - Required - Strength of the prompt's influence.
- **balance_strength** (float) - Optional (default: 0.7) - Strength of the balance between different audio elements.
- **seed** (integer) - Optional - Seed for reproducible generation.
- **webhook_url** (string) - Optional - URL to send notifications to upon completion.
- **num_songs** (integer) - Optional (default: 1) - Number of extended songs to generate.
- **output_format** (string) - Optional (default: ogg) - Desired audio output format.
- **output_bit_rate** (integer) - Optional - Desired audio bit rate.
- **align_lyrics** (boolean) - Optional (default: false) - Whether to align lyrics with the audio.
- **audio_url** (string) - Required (URL) - The URL of the audio file to extend.
- **audio_base64** (string) - Required (base64) - Base64 encoded audio file to extend (max 40MB).
- **side** (string) - Required (left | right) - The side to extend from (start or end).
- **extend_duration** (float) - Optional - Duration in seconds to extend the audio by (0 to 85.0).
- **crop_duration** (float) - Optional (default: 0.0) - Duration in seconds to crop from the original audio before extending.

### Request Example
```json
{
  "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
#### Success Response (200)
- **task_id** (string) - The unique identifier for the generation task.

#### Response Example
```json
{
  "task_id": "string"
}
```
```

--------------------------------

### Inpaint Audio Sections using URL (cURL)

Source: https://sonauto.ai/developers/index

Replaces specified sections of an existing audio file with newly generated content using a provided audio URL. Requires an API key for authentication. The response contains a task ID for tracking the generation process.

```cURL
curl -X POST https://api.sonauto.ai/v1/generations/v2/inpaint \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ 
    "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"
  }'
```

--------------------------------

### POST /generations/v3

Source: https://sonauto.ai/developers/index

Generate a new song using the v3 model. This endpoint supports variable-length songs with improved audio quality and real-time streaming capabilities.

```APIDOC
## POST /generations/v3

### Description
Generate a new song using our v3 model. V3 produces variable-length songs (typically 2-4 minutes) with improved audio quality. See the parameter details at the top of these docs for more information.
v3 takes a longer time than v2 to fully generate a song. However, you can start listening to a v3 song much faster than a v2 song since v3 songs can be streamed in real time while they generate. To enable streaming, set `enable_streaming` to `true` in your request. See the Streaming section for more information. Use the `stream_format` parameter to control the audio format of the stream (ogg or mp3).

### Method
POST

### Endpoint
/generations/v3

### Parameters
#### Core Parameters
* **tags** (string) - Optional - Tags to guide song generation. If blank, AI generates based on prompt.
* **lyrics** (string) - Optional - Lyrics for the song. If blank, AI generates based on prompt.
* **prompt** (string) - Optional - Text prompt to guide song generation. If blank, AI generates based on tags/lyrics.
* **instrumental** (boolean) - Optional - Set to true for instrumental songs. Do not pass lyrics when true.

#### Other Parameters
* **prompt_strength** (number) - Optional - Controls adherence to the prompt. Higher values mean more adherence but less natural sound.
* **balance_strength** (number) - Optional - Controls vocal naturalness vs. instrumental sharpness. Recommended: 0.7.
* **seed** (integer) - Optional - Seed for the random number generator. Same inputs with the same seed produce the same song.
* **webhook_url** (string) - Optional - URL to receive POST requests with status updates during generation.
* **num_songs** (integer) - Optional - Number of songs to generate (1 or 2). Generating 2 songs uses 150 credits.
* **align_lyrics** (boolean) - Optional - If true, performs lyrics alignment after generation. Requires `num_songs=1` for v3.

#### Output Audio Formats
* **output_format** (string) - Optional - Desired audio output format. Supported: mp3, flac, wav, ogg, m4a. Defaults to ogg (opus).
* **output_bit_rate** (integer) - Optional - Bitrate for mp3 or m4a formats (kbps). Supported: 128, 192, 256, 320. Null uses defaults.

#### v3 Specific Parameters
* **enable_streaming** (boolean) - Optional - Set to true to enable real-time streaming of the song while it generates.
* **stream_format** (string) - Optional - Audio format for streaming. Supported: ogg, mp3.

### Request Example
```json
{
  "tags": "upbeat pop",
  "lyrics": "We are going to the moon",
  "prompt_strength": 0.8,
  "enable_streaming": true,
  "stream_format": "mp3"
}
```

### Response
#### Success Response (200)
* **task_id** (string) - Unique identifier for the generation task.
* **song_paths** (array) - Array of URLs to the generated song(s). These URLs expire.
* **status** (string) - Current status of the generation task.

#### Response Example
```json
{
  "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "song_paths": [
    "https://example.com/song1.ogg"
  ],
  "status": "RECEIVED"
}
```
```

--------------------------------

### Data Fetching Endpoints

Source: https://sonauto.ai/developers/index

Endpoints for fetching generation details and credit balance.

```APIDOC
## GET /generations/{task_id}

### Description
Fetches details for a specific generation task.

### Method
GET

### Endpoint
/generations/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The ID of the generation task.

### Response
#### Success Response (200)
- **status** (string) - The status of the generation task (e.g., 'processing', 'completed', 'failed').
- **audio_url** (string) - The URL of the generated audio file (if completed).
- **error** (string) - Error message if the task failed.

#### Response Example
```json
{
  "status": "completed",
  "audio_url": "https://api.sonauto.ai/audio/generated_song.mp3"
}
```
```

```APIDOC
## GET /generations/status/{task_id}

### Description
Fetches the status of a specific generation task.

### Method
GET

### Endpoint
/generations/status/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The ID of the generation task.

### Response
#### Success Response (200)
- **status** (string) - The status of the generation task (e.g., 'processing', 'completed', 'failed').

#### Response Example
```json
{
  "status": "processing"
}
```
```

```APIDOC
## GET /credits/balance

### Description
Fetches the current credit balance for the authenticated user.

### Method
GET

### Endpoint
/credits/balance

### Response
#### Success Response (200)
- **credits** (integer) - The remaining credit balance.

#### Response Example
```json
{
  "credits": 1200
}
```
```

--------------------------------

### Lyrics Alignment Endpoint

Source: https://sonauto.ai/developers/index

Endpoint for lyrics alignment.

```APIDOC
## POST /lyrics/align

### Description
Aligns lyrics with an existing audio track.

### Method
POST

### Endpoint
/lyrics/align

### Parameters
#### Request Body
- **audio_file** (file) - Required - The audio file to align lyrics with.
- **lyrics** (string) - Required - The lyrics to align.

### Response
#### Success Response (200)
- **aligned_lyrics** (array) - An array of objects, each containing timing information for words or lines.

#### Response Example
```json
{
  "aligned_lyrics": [
    {
      "word": "Hello",
      "start_time": 0.5,
      "end_time": 1.0
    },
    {
      "word": "World",
      "start_time": 1.1,
      "end_time": 1.5
    }
  ]
}
```
```

--------------------------------

### Retrieve Generation Task Status (Python)

Source: https://sonauto.ai/developers/index

Fetches the status and details of a previously submitted audio generation task using its unique task ID. This includes information about the generated song, parameters used, and any potential errors. The final audio URL is also provided if a webhook was configured.

```Python
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())
```

--------------------------------

### Generation Endpoints

Source: https://sonauto.ai/developers/index

Endpoints for generating songs using different API versions.

```APIDOC
## POST /v3

### Description
Generates songs using API version 3.

### Method
POST

### Endpoint
/v3

### Parameters
#### Query Parameters
- **num_songs** (integer) - Optional - The number of songs to generate in a single request.

### Request Body
[Details about the request body for v3 generation would go here, e.g., fields for lyrics, genre, etc.]

### Response
#### Success Response (200)
- **task_id** (string) - The ID of the generation task.

#### Response Example
```json
{
  "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```
```

```APIDOC
## POST /v2

### Description
Generates songs using API version 2.

### Method
POST

### Endpoint
/v2

### Parameters
#### Query Parameters
- **num_songs** (integer) - Optional - The number of songs to generate in a single request.

### Request Body
[Details about the request body for v2 generation would go here, e.g., fields for lyrics, genre, etc.]

### Response
#### Success Response (200)
- **task_id** (string) - The ID of the generation task.

#### Response Example
```json
{
  "task_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef"
}
```
```

```APIDOC
## POST /v2/extend

### Description
Extends an existing song generation using API version 2.

### Method
POST

### Endpoint
/v2/extend

### Parameters
#### Request Body
- **task_id** (string) - Required - The ID of the task to extend.
- **new_lyrics** (string) - Required - The new lyrics to append.

### Response
#### Success Response (200)
- **task_id** (string) - The ID of the extended generation task.

#### Response Example
```json
{
  "task_id": "b2c3d4e5-f6a7-8901-2345-67890abcdef1"
}
```
```

```APIDOC
## POST /v2/inpaint

### Description
Performs inpainting on a song generation using API version 2.

### Method
POST

### Endpoint
/v2/inpaint

### Parameters
#### Request Body
- **task_id** (string) - Required - The ID of the task to inpaint.
- **time_range** (object) - Required - The time range for inpainting.
  - **start_time** (float) - Required - Start time in seconds.
  - **end_time** (float) - Required - End time in seconds.
- **new_audio_prompt** (string) - Required - The audio prompt for inpainting.

### Response
#### Success Response (200)
- **task_id** (string) - The ID of the inpainting task.

#### Response Example
```json
{
  "task_id": "c3d4e5f6-a7b8-9012-3456-7890abcdef12"
}
```
```

--------------------------------

### Streaming Audio API

Source: https://sonauto.ai/developers/index

Stream audio for v3 generations in real-time as it is being created.

```APIDOC
## GET https://api-stream.sonauto.ai/stream/{task_id}

### Description
Stream audio for a v3 generation as it's being created. The endpoint returns audio chunks as they are produced by the model. If you connect after generation has started, you will receive all previously generated audio immediately, then continue receiving new chunks as they are generated. **Streaming is only available for v3 generations and must be enabled during generation request by setting `enable_streaming` to `true`.**

### Method
GET

### Endpoint
`https://api-stream.sonauto.ai/stream/{task_id}`

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The task ID returned when you created the v3 generation.

### Request Example
#### HTML
```html
<audio controls autoplay>
  <source src="https://api-stream.sonauto.ai/stream/your_task_id" type="audio/ogg" />
</audio>
```

#### Python
```python
import requests

task_id = "your_task_id"
url = f"https://api-stream.sonauto.ai/stream/{task_id}"

response = requests.get(url, stream=True)

with open("output.ogg", "wb") as f:
    for chunk in response.iter_content(chunk_size=8192):
        f.write(chunk)
```

#### cURL
```bash
curl -o output.ogg https://api-stream.sonauto.ai/stream/your_task_id
```

### Response
#### Success Response (200)
Returns a streaming audio response. The `Content-Type` header will indicate the audio format:
- `audio/ogg; codecs="opus"` (default)
- `audio/mpeg` (if requested during generation)

### Errors
#### Error Response (400 Bad Request)
- **Description**: The track is not ready for streaming yet. Wait for the generation to reach the `GENERATING_STREAMING_READY` status before attempting to stream.
```json
{
  "error": "Track not ready for streaming"
}
```
```

--------------------------------

### Check Credit Balance with cURL

Source: https://sonauto.ai/developers/index

A cURL command to check the user's remaining credit balance on Sonauto AI. This demonstrates how to authenticate with an API key via the Authorization header for the /credits/balance endpoint.

```bash
curl -X GET "https://api.sonauto.ai/v1/credits/balance" \
     -H "Authorization: Bearer your_api_key_here"
```

--------------------------------

### Lyric Alignment Requirements and Status

Source: https://sonauto.ai/developers/index

Details the requirements for lyric alignment, including version-specific settings and the status flow for the alignment process.

```APIDOC
## Lyric Alignment Requirements and Status

### Description
This section outlines the conditions and steps involved in lyric alignment for song generation.

### Requirements
- Alignment only functions for non-instrumental songs with lyrics.
- For v2 generations, `num_songs` must be set to 1 when `align_lyrics` is true.

### Alignment Status Flow
When `align_lyrics=true` is set:
1. `REQUESTED`: Alignment requested, to run after generation.
2. `TASK_SENT`: Generation succeeded, alignment task dispatched.
3. `ALIGNING`: Alignment is actively being processed.
4. `SUCCESS`: Alignment completed successfully; aligned lyrics available.
5. `FAILURE`: Alignment process encountered an error.

### Important Notes
- If the main generation fails, `alignment_status` remains `REQUESTED`.
- Always check the main `status` before `alignment_status`.
- Credits are deducted if alignment fails but generation succeeds.

### Checking Alignment Status
Use the `GET /generations/status/{task_id}` endpoint with `include_alignment=true`.

#### Example Request
`GET /generations/status/{task_id}?include_alignment=true`

#### Example Response
```json
{
  "status": "SUCCESS",
  "alignment_status": "ALIGNING"
}
```

### Webhook Updates
If a `webhook_url` is provided, updates including `alignment_status` will be sent upon status changes.
```

--------------------------------

### Retrieve Generation Task Status (cURL)

Source: https://sonauto.ai/developers/index

Fetches the status and details of a previously submitted audio generation task using its unique task ID. This includes information about the generated song, parameters used, and any potential errors. The final audio URL is also provided if a webhook was configured.

```cURL
curl -X GET https://api.sonauto.ai/v1/generations/your_task_id \
  -H "Authorization: Bearer your_api_key_here"
```

--------------------------------

### Streaming Endpoint

Source: https://sonauto.ai/developers/index

Endpoint for streaming audio content.

```APIDOC
## GET /stream/{task_id}

### Description
Streams the audio content for a given task ID.

### Method
GET

### Endpoint
/stream/{task_id}

### Parameters
#### Path Parameters
- **task_id** (string) - Required - The ID of the task to stream.

### Response
#### Success Response (200)
- **Audio Stream** - The audio content is streamed directly.

#### Response Example
[This would typically be a binary stream, not a JSON example.]
```

--------------------------------

### API Authentication Header

Source: https://sonauto.ai/developers/index

This code snippet demonstrates how to include the API key in the Authorization header for authenticating requests to the Sonauto AI API. Ensure you replace 'your_api_key_here' with your actual API key.

```http
Authorization: Bearer your_api_key_here
```
Tokens:
Raw