> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Generasi Musik

> Buat tugas musik atau lirik, polling untuk audio akhir, dan simpan keluaran musik yang terlihat oleh pengguna dengan aman.

Generasi musik bersifat asinkron. `POST /v1/music/generations` membuat tugas TokenLab publik dan mengembalikan `id` / `task_id`, `status`, dan biasanya `poll_url`. Aplikasi Anda harus menyimpan identitas tugas tersebut, menunjukkan kemajuan, dan melakukan polling hingga status terminal.

## Pilih Alur Kerja

| Alur Kerja                   | Bidang kunci                                                   | Catatan                                                                     |
| ---------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Lagu penuh atau instrumental | `model`, `prompt`, opsional `title`, `tags`, `action: "MUSIC"` | Gunakan ketika pengguna mengharapkan audio akhir                            |
| Hanya lirik                  | `model`, `prompt`, `action: "LYRICS"`                          | Gunakan hanya dengan model yang mengekspos generasi lirik                   |
| Melanjutkan klip yang ada    | `continue_clip_id`, opsional `continue_at`                     | Simpan identitas klip/tugas publik sebelumnya sebelum menawarkan kelanjutan |

Kueri katalog model saat ini sebelum mengirim daftar model yang dikodekan keras:

```bash theme={null}
curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
  -H "Authorization: Bearer sk-your-api-key"
```

Contoh publik saat ini menggunakan `suno_music` untuk generasi musik. Untuk alur hanya lirik, kirim `action: "LYRICS"` dengan model yang dokumen kontrak publiknya mencantumkan generasi lirik. Perlakukan ID model sebagai ID TokenLab publik, bukan sebagai jaminan bahwa bidang spesifik penyedia adalah bidang kontrak publik.

## Buat Tugas Musik

```bash theme={null}
curl https://api.tokenlab.sh/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno_music",
    "prompt": "Lagu synth-pop ceria dengan vokal hangat dan chorus yang bersih",
    "title": "Morning Static",
    "tags": "synth-pop, ceria",
    "action": "MUSIC"
  }'
```

Simpan prompt, judul, dan tag yang terlihat oleh pengguna dan aman untuk disimpan. Jangan tempatkan kunci API, URL pribadi, atau informasi routing internal di bidang prompt mana pun.

## Poll Untuk Penyelesaian

Gunakan `poll_url` terlebih dahulu. Jika klien Anda memerlukan rute tetap, panggil `GET /v1/tasks/{id}` dengan `id` atau `task_id` yang dikembalikan.

```bash theme={null}
curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"
```

Status publik yang diharapkan adalah `pending`, `processing`, `completed`, dan `failed`. Tugas musik yang selesai dapat mencakup `audio_url`, `video_url`, `title`, `lyrics`, dan metadata yang dinormalisasi. Simpan URL akhir di database Anda sendiri sehingga pengguna dapat membuka kembali hasil tanpa memulai ulang generasi.

## UI Dan Penanganan Status

* Tampilkan status pending segera setelah tugas dibuat.
* Lakukan polling setiap `5-10s` untuk tugas yang panjang, kemudian berhenti pada `completed` atau `failed`.
* Jangan tampilkan pemutar akhir sampai tugas `completed` dan `audio_url` ada.
* Untuk tugas hanya lirik, render output teks terpisah dari tugas audio sehingga pengguna memahami apa yang mereka beli.
* Saat menyegarkan, lanjutkan dari `task_id` yang disimpan alih-alih membuat tugas baru.

## Penagihan Dan Rekonsiliasi

Tugas musik dapat memesan jumlah yang diperkirakan pada saat pembuatan dan menyelesaikan setelah status terminal diketahui. Simpan `request_id`, `task_id`, model, endpoint, dan `billing_transaction_id` saat muncul. Gunakan catatan penggunaan API Manajemen untuk rekonsiliasi alih-alih ID tugas penyedia.

## Kesalahan Umum

| Gejala                                | Penyebab yang Mungkin                              | Perbaikan                                                                                                        |
| ------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| Tugas dibuat tetapi tidak ada pemutar | Tugas masih pending atau selesai tanpa `audio_url` | Terus lakukan polling hingga terminal, kemudian tangani output yang hilang sebagai pekerjaan pengguna yang gagal |
| Lagu duplikat setelah penyegaran      | UI membuat ulang tugas alih-alih melanjutkan       | Simpan dan gunakan kembali `task_id`                                                                             |
| Tugas lirik tidak mengembalikan audio | `action: "LYRICS"` hanya teks                      | Pisahkan jalur UI lirik dan musik                                                                                |
| Parameter tidak didukung              | Bidang tidak ada dalam kontrak publik model        | Hapus bidang spesifik penyedia atau pilih model yang mendokumentasikannya                                        |

## Referensi API

| Topik                 | Referensi                                                         |
| --------------------- | ----------------------------------------------------------------- |
| Buat Musik            | [Buat Musik](/id/api-reference/music/create-music)                |
| Dapatkan Status Musik | [Dapatkan Status Musik](/id/api-reference/music/get-music-status) |
| Dapatkan Status Tugas | [Dapatkan Status Tugas](/id/api-reference/tasks/get-task-status)  |
| Daftar Model          | [Daftar Model](/id/api-reference/models/list-models)              |
| Penagihan & Harga     | [Penagihan & Harga](/id/guides/billing)                           |