# 🎵 Sonauto API Documentation (Lengkap)

> **Beta** - Dokumentasi resmi untuk Sonauto Developer API  
> Build with the Sonauto API. Generate AI music programmatically and integrate music generation into your applications.  
> 🌐 Source: [sonauto.ai/developers](https://sonauto.ai/developers)  
> 📅 Last Updated: April 2026

---

## 📋 Daftar Isi

1. [Gambaran Umum](#-gambaran-umum)
2. [Harga & Kredit API](#-harga--kredit-api)
3. [Autentikasi](#-autentikasi)
4. [Parameter Generasi (Core)](#-parameter-generasi-core)
5. [Format Output Audio](#-format-output-audio)
6. [Status Generasi](#-status-generasi)
7. [Endpoint Generasi](#-endpoint-generasi)
   - [v3 Preview (Beta)](#-v3-preview-beta)
   - [v2 - Generate Song](#-v2-generate-song)
   - [v2/extend - Extend Song](#-v2extend-extend-song)
   - [v2/inpaint - Inpaint Section](#-v2inpaint-inpaint-section)
8. [Generation History & Data Fetching](#-generation-history--data-fetching)
   - [⚠️ Penting: Masa Simpan Lagu](#️-penting-masa-simpan-lagu)
   - [GET /v1/generations/{task_id}](#-get-v1generationstask_id)
   - [GET /v1/generations/status/{task_id}](#-get-v1generationsstatustask_id)
   - [Flow Status Generasi](#-flow-status-generasi-reference)
9. [Streaming (v3 Only)](#-streaming-v3-only)
10. [Lyrics Alignment](#-lyrics-alignment)
11. [Contoh Kode](#-contoh-kode)
12. [Best Practices & Tips](#-best-practices--tips)
13. [Referensi GitHub Examples](#-referensi-github-examples)
14. [Troubleshooting](#-troubleshooting)
15. [Dukungan & Komunitas](#-dukungan--komunitas)

---

## 🔍 Gambaran Umum

Sonauto adalah platform AI music generation yang memungkinkan developer untuk:

- ✅ Membuat lagu lengkap dari prompt teks, lirik, atau tag gaya musik
- ✅ Memperpanjang lagu yang sudah ada (`extend`)
- ✅ Mengganti bagian tertentu dari lagu (`inpaint`)
- ✅ Streaming audio real-time (v3)
- ✅ Sinkronisasi lirik ke audio (`align_lyrics`)

**API Domain:** `https://api.sonauto.ai/v1`  
**Streaming Domain:** `https://api-stream.sonauto.ai`

> ⚠️ **PENTING:** Lagu yang dihasilkan akan dihapus dari server **7 hari (168 jam)** setelah generasi. Pastikan untuk mengunduh lagu yang ingin Anda simpan!

---

## 💰 Harga & Kredit API

> Pricing untuk API saja. Generasi lagu via website Sonauto tetap **gratis**!

### 🎁 Free Trial
| Item | Detail |
|------|--------|
| Kredit Gratis | **1,500 credits** setelah registrasi |
| Estimasi Lagu | ~15 lagu (1 lagu = 100 credits) |

### 💡 Sistem Kredit
| Aksi | Kredit |
|------|--------|
| 1 lagu (1:35 menit) via v2 | 100 credits |
| 2 lagu sekaligus (`num_songs=2`) | 150 credits |
| Lagu v3 (variable length 2-4 menit) | 100 credits |

### 📦 Paket Berlangganan

| Paket | Harga/Bulan | Kredit | Kredit/Lagu | Kredit Tambahan |
|-------|-------------|--------|-------------|----------------|
| **Starter** | $11 | 20,000 | 200 lagu | $0.06 / 100 credits |
| **Pro** | $88 | 160,000 | 1,600 lagu | $0.06 / 100 credits |
| **Scale** | $330 | 660,000 | 6,600 lagu | $0.05 / 100 credits |
| **Enterprise** | $1,150 | 2,875,000 | 28,750 lagu | $0.04 / 100 credits |
| **Pay As You Go** | - | Beli sesuai kebutuhan | - | $0.06 / 100 credits |

> 📌 **Attribution Required:** Implementasi user-facing API Sonauto **wajib** mencantumkan atribusi ke Sonauto.

---

## 🔐 Autentikasi

Semua endpoint memerlukan API Key di header `Authorization`:

```http
Authorization: Bearer your_api_key_here
Content-Type: application/json

01. RECEIVED                    → Request diterima & diparsing
02. TRANSCRIBE_TASK_STARTED     → (inpaint/extend only)
03. TRANSCRIBE_STAGE_1          → (inpaint/extend only)
04. TRANSCRIBE_STAGE_2          → (inpaint/extend only)
05. TRANSCRIBE_STAGE_3          → (inpaint/extend only)
06. TRANSCRIBE_DONE             → (inpaint/extend only)
07. PROMPT                      → Konversi prompt ke tags/lyrics
08. TASK_SENT                   → Task dikirim ke GPU cluster
09. GENERATE_TASK_STARTED       → GPU worker mulai mengerjakan
10. LOADING_SOURCE              → (inpaint/extend) Fetch source audio
11. BEGINNING_GENERATION        → Persiapan akhir sebelum generate
12. GENERATING                  → 🎵 Lagu sedang digenerate!
13. GENERATING_STREAMING_READY  → (v3 only) Siap untuk streaming
14. DECOMPRESSING               → Decompress dari latent space
15. SAVING                      → Upload ke CDN
16. ✅ SUCCESS                  → Selesai! URL lagu di `song_paths`
17. ❌ FAILURE                  → Error (tidak ada kredit dipotong)

{
  "tags": ["rock", "energetic"],
  "lyrics": "Optional lyrics here...",
  "prompt": "An upbeat rock song with heavy guitar riffs",
  "instrumental": false,
  "prompt_strength": 2.0,
  "webhook_url": "https://your-webhook.com/sonauto",
  "output_format": "ogg",
  "output_bit_rate": null,
  "enable_streaming": true,
  "stream_format": "ogg",
  "align_lyrics": false
}

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

{
  "tags": ["rock", "energetic"],
  "lyrics": "Optional lyrics...",
  "prompt": "An upbeat rock song with heavy guitar riffs",
  "instrumental": false,
  "prompt_strength": 2.0,
  "balance_strength": 0.7,
  "seed": 42,
  "webhook_url": "https://your-webhook.com/sonauto",
  "num_songs": 1,
  "output_format": "ogg",
  "output_bit_rate": null,
  "align_lyrics": false,
  "bpm": "auto"
}

{
  "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}

{
  "audio_url": "https://cdn.sonauto.ai/generations2/audio_xxx.ogg",
  "audio_base64": "optional_base64_string",
  "side": "right",
  "extend_duration": 45.0,
  "crop_duration": 0.0,
  "tags": ["rock", "energetic"],
  "lyrics": "New lyrics for extension...",
  "prompt": "Continue the song with a guitar solo",
  "instrumental": false,
  "prompt_strength": 2.0,
  "balance_strength": 0.7,
  "seed": 42,
  "webhook_url": "https://your-webhook.com/sonauto",
  "num_songs": 1,
  "output_format": "ogg",
  "output_bit_rate": null,
  "align_lyrics": false
}

{
  "audio_url": "https://cdn.sonauto.ai/generations2/audio_xxx.ogg",
  "audio_base64": "optional_base64_string",
  "sections": [[0.0, 30.0]],
  "selection_crop": false,
  "tags": ["rock", "energetic"],
  "lyrics": "New lyrics for the section",
  "prompt": "Replace with a drum break",
  "instrumental": false,
  "prompt_strength": 2.0,
  "balance_strength": 0.7,
  "seed": 42,
  "webhook_url": "https://your-webhook.com/sonauto",
  "num_songs": 1,
  "output_format": "ogg",
  "output_bit_rate": null,
  "align_lyrics": false
}

🗓️ Songs will be deleted from our servers ONE WEEK (168 hours) after generation.

GET https://api.sonauto.ai/v1/generations/{task_id}
Authorization: Bearer your_api_key_here

import requests

task_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
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())

curl -X GET "https://api.sonauto.ai/v1/generations/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
  -H "Authorization: Bearer your_api_key_here"

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "created_at": "2026-04-06T10:30:00Z",
  "status": "SUCCESS",
  "alignment_status": "SUCCESS",
  "model_version": "v3-preview",
  "song_paths": [
    "https://cdn.sonauto.ai/generations3/audio_xxx.ogg"
  ],
  "error_message": null,
  "lyrics": "Generated or provided lyrics here...",
  "prompt": "An upbeat rock song with heavy guitar riffs",
  "prompt_strength": 2.0,
  "tags": ["rock", "energetic", "male vocals"],
  "v2_params": {
    "balance_strength": 0.7,
    "seed": 42,
    "bpm": "auto"
  },
  "inpaint_params": null,
  "extend_params": null
}

GET https://api.sonauto.ai/v1/generations/status/{task_id}?include_alignment=true
Authorization: Bearer your_api_key_here

"SUCCESS"

{
  "status": "SUCCESS",
  "alignment_status": "SUCCESS"
}

01. RECEIVED                    
02. TRANSCRIBE_TASK_STARTED     → (inpaint/extend only)
03. TRANSCRIBE_STAGE_1-3        → (inpaint/extend only)  
04. TRANSCRIBE_DONE             → (inpaint/extend only)
05. PROMPT                      → Konversi prompt ke tags/lyrics
06. TASK_SENT                   → Task dikirim ke GPU cluster
07. GENERATE_TASK_STARTED       → GPU worker mulai mengerjakan
08. LOADING_SOURCE              → (inpaint/extend) Fetch source audio
09. BEGINNING_GENERATION        → Persiapan akhir sebelum generate
10. GENERATING                  → 🎵 Lagu sedang digenerate!
11. GENERATING_STREAMING_READY  → (v3 only) Siap untuk streaming
12. DECOMPRESSING               → Decompress dari latent space
13. SAVING                      → Upload ke CDN
14. ✅ SUCCESS                  → Selesai! URL lagu di `song_paths`
15. ❌ FAILURE                  → Error (tidak ada kredit dipotong)

Content-Type: audio/ogg; codecs="opus"
# atau
Content-Type: audio/mpeg  (jika stream_format: "mp3")

<audio controls autoplay>
  <source 
    src="https://api-stream.sonauto.ai/stream/a1b2c3d4-e5f6-7890-abcd-ef1234567890" 
    type="audio/ogg" 
  />
  Your browser does not support the audio element.
</audio>

import requests

task_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
url = f"https://api-stream.sonauto.ai/stream/{task_id}"
headers = {"Authorization": "Bearer your_api_key_here"}

with requests.get(url, headers=headers, stream=True) as r:
    r.raise_for_status()
    with open("streaming_output.ogg", "wb") as f:
        for chunk in r.iter_content(chunk_size=8192):
            f.write(chunk)

REQUESTED → TASK_SENT → ALIGNING → ✅ SUCCESS / ❌ FAILURE

GET /v1/generations/status/{task_id}?include_alignment=true

{
  "status": "SUCCESS",
  "alignment_status": "SUCCESS"
}

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",
    "num_songs": 1,
    "output_format": "mp3",
    "output_bit_rate": 320
}

response = requests.post(url, json=payload, headers=headers)
task_id = response.json()["task_id"]
print(f"Task ID: {task_id}")

# Polling status
import time
while True:
    status_url = f"https://api.sonauto.ai/v1/generations/status/{task_id}"
    status = requests.get(status_url, headers=headers).json()
    print(f"Status: {status}")
    if status in ["SUCCESS", "FAILURE"]:
        break
    time.sleep(5)

# Ambil hasil
if status == "SUCCESS":
    result = requests.get(
        f"https://api.sonauto.ai/v1/generations/{task_id}",
        headers=headers
    ).json()
    print(f"Download URL: {result['song_paths'][0]}")

# 1. Request generasi
curl -X POST https://api.sonauto.ai/v1/generations/v3 \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A chill lofi beat for studying",
    "tags": ["lofi", "chill", "instrumental"],
    "instrumental": true,
    "enable_streaming": true,
    "stream_format": "mp3"
  }'

# 2. Streaming (setelah status GENERATING_STREAMING_READY)
curl -H "Authorization: Bearer your_api_key_here" \
  https://api-stream.sonauto.ai/stream/YOUR_TASK_ID \
  --output song_stream.mp3

import base64
import requests

# Baca file audio & encode ke base64
with open("source_song.ogg", "rb") as f:
    audio_b64 = base64.b64encode(f.read()).decode("utf-8")

url = "https://api.sonauto.ai/v1/generations/v2/extend"
headers = {
    "Authorization": "Bearer your_api_key_here",
    "Content-Type": "application/json"
}
payload = {
    "audio_base64": audio_b64,
    "side": "right",
    "extend_duration": 30.0,
    "prompt": "Add a guitar solo outro",
    "tags": ["rock", "guitar"]
}

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

import time
import requests

def wait_for_completion(task_id, api_key, interval=5, timeout=300):
    """Poll status dengan exponential backoff sederhana"""
    url = f"https://api.sonauto.ai/v1/generations/status/{task_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    start_time = time.time()
    while time.time() - start_time < timeout:
        response = requests.get(url, headers=headers)
        status = response.json()
        
        if status in ["SUCCESS", "FAILURE"]:
            return status
        elif status == "GENERATING":
            print(f"⏳ Masih generating... ({int(time.time()-start_time)}s)")
        
        time.sleep(interval)
    
    raise TimeoutError(f"Task {task_id} belum selesai dalam {timeout} detik")

def download_song(task_id, api_key, output_path="song.ogg"):
    """Ambil hasil dan download langsung"""
    headers = {"Authorization": f"Bearer {api_key}"}
    
    # 1. Cek status dulu
    status_url = f"https://api.sonauto.ai/v1/generations/status/{task_id}"
    if requests.get(status_url, headers=headers).json() != "SUCCESS":
        return False
    
    # 2. Ambil detail + URL
    detail_url = f"https://api.sonauto.ai/v1/generations/{task_id}"
    data = requests.get(detail_url, headers=headers).json()
    
    # 3. Download audio
    song_url = data["song_paths"][0]
    audio = requests.get(song_url).content
    
    with open(output_path, "wb") as f:
        f.write(audio)
    
    print(f"✅ Downloaded: {output_path}")
    return True

git clone https://github.com/Sonauto/sonauto-api-examples.git
cd sonauto-api-examples
pip install -r requirements.txt

# Setup environment
cp .env.example .env
# Edit .env: tambahkan SONAUTO_API_KEY dan (opsional) LEMONSLICE_API_KEY

# Transisi dari Smash Mouth ke Rick Astley
python transition_generator.py ec1LhrCmzwI dQw4w9WgXcQ \
  --trim-to-start 13 \
  --trim-from-end 0.5 \
  --silence 20 \
  --output my_transition.ogg

Attribution Required:
Implementasi user-facing API Sonauto wajib mencantumkan atribusi ke Sonauto.

Contoh atribusi:
"Music generated with Sonauto AI - sonauto.ai"

> 🔄 *Dokumentasi ini berdasarkan konten resmi sonauto.ai/developers. Selalu cek sumber untuk update terbaru.*