Generasi Musik - TokenLab

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`, `mv`, `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:

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 dan menyertakan mv dengan versi model Suno resmi seperti chirp-v4. Untuk alur hanya lirik, kirim action: "LYRICS" dengan model yang dokumen detail modelnya mencantumkan generasi lirik dan hilangkan mv. Perlakukan ID model sebagai ID TokenLab publik, bukan sebagai jaminan bahwa bidang spesifik penyedia adalah bidang detail model.

Buat Tugas Musik

curl https://api.tokenlab.sh/v1/music/generations \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno_music",
    "mv": "chirp-v4",
    "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 diagnostik pribadi 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.

curl "https://api.tokenlab.sh/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer sk-your-api-key"

Bentuk respons

Respons pembuatan adalah catatan tugas yang dapat di-polling, bukan audio final:

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "pending",
  "created": 1706000000,
  "model": "suno_music"
}

Respons polling yang selesai dapat menyertakan field media final:

{
  "id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "status": "completed",
  "audio_url": "https://cdn.example.com/music/abc123.mp3",
  "video_url": "https://cdn.example.com/music/abc123.mp4",
  "stream_audio_url": "https://cdn.example.com/music/abc123-stream.mp3",
  "image_url": "https://cdn.example.com/music/cover.jpg",
  "title": "Morning Static",
  "lyrics": "[Verse 1]\n..."
}

Field media final tidak ada sampai status menjadi completed. Tugas yang gagal mengembalikan status: "failed" dengan error. 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 detail model model	Hapus bidang spesifik penyedia atau pilih model yang mendokumentasikannya

Referensi API

Topik	Referensi
Buat Musik	Buat Musik
Dapatkan Status Musik	Dapatkan Status Musik
Dapatkan Status Tugas	Dapatkan Status Tugas
Daftar Model	Daftar Model
Penagihan & Harga	Penagihan & Harga

​Pilih Alur Kerja

​Buat Tugas Musik

​Poll Untuk Penyelesaian

​Bentuk respons

​UI Dan Penanganan Status

​Penagihan Dan Rekonsiliasi

​Kesalahan Umum

​Referensi API