Panduan media
Pembuatan musik
Buat lagu atau lirik dan tunggu hingga audio selesai
Pembuatan musik bersifat asinkron. POST /v1/music/generations mengembalikan ID tugas, status, dan biasanya poll_url. Lakukan polling GET /v1/tasks/{id} dengan ID tersebut sampai tugas berstatus completed atau failed.
Pilih apa yang ingin dibuat
| Apa yang dibuat | Bidang kunci | Catatan |
|---|---|---|
| Lagu penuh atau instrumental | model, mv, prompt, opsional title, tags, action: "MUSIC" | Gunakan saat pengguna mengharapkan audio akhir |
| Lirik saja | model, prompt, action: "LYRICS" | Gunakan hanya dengan model yang menyediakan pembuatan lirik |
| Melanjutkan klip yang ada | model, mv, prompt, continue_clip_id, opsional continue_at | Pertahankan ID klip sebelumnya |
| Sampul atau memperpanjang audio Anda sendiri | model, mv, prompt, audio_url, opsional audio_operation | audio_url harus berupa URL publik. audio_operation secara default adalah upload-cover; upload-extend juga memerlukan continue_at |
| Menambahkan instrumental, mengganti bagian, atau memisahkan stem | audio_operation: add-instrumental, replace-section, vocal-separate, multi-stem-separation, atau advanced-split | Setiap operasi memiliki bidang wajibnya sendiri; lihat Buat Musik |
Dapatkan daftar model musik saat ini dari:
curl "https://api.tokenlab.sh/v1/models?recommended_for=music" \
-H "Authorization: Bearer sk-your-api-key"Contoh di bawah menggunakan suno-music dengan mv: "chirp-v6". Model musik lain, seperti stable-audio-3, menggunakan bidang yang berbeda seperti duration dan output_format; baca detail model terlebih dahulu. Untuk lirik saja, pilih model yang mendokumentasikan pembuatan lirik, kirim action: "LYRICS", dan hilangkan mv.
Membuat 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-v6",
"prompt": "An upbeat synth-pop track with warm vocals and a clean chorus",
"title": "Morning Static",
"tags": "synth-pop, upbeat",
"action": "MUSIC"
}'Prompt, judul, dan tag mungkin muncul di riwayat produk Anda. Jangan pernah memasukkan kunci API, URL pribadi, atau data diagnostik di dalamnya.
Mendapatkan audio yang sudah selesai
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, bukan audio akhir:
{
"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 bidang media akhir:
{
"id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"task_id": "ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"poll_url": "/v1/tasks/ldtask_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
"status": "completed",
"audio_url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
"video_url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
"image_url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
"title": "Morning Static",
"lyrics": "[Verse 1]\n...",
"media_retention": {
"days": 30,
"items": [
{
"url": "https://api.tokenlab.sh/v1/media-results/2d7e9a41-8c3b-4b6f-a1e5-7f0c3d9b8e26.mp3?token=…",
"kind": "audio",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
},
{
"url": "https://api.tokenlab.sh/v1/media-results/9a3f5c17-2e8d-4b0a-b6c4-1d7e8f2a5b39.mp4?token=…",
"kind": "video",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
},
{
"url": "https://api.tokenlab.sh/v1/media-results/c4e8b2d6-7a1f-4e3c-9d5b-3f6a0e8c1b72.jpg?token=…",
"kind": "image",
"status": "saving",
"expires_at": "2024-02-22T08:54:20.000Z"
}
]
}
}Bidang media akhir tidak ada sampai status menjadi completed. Tugas yang gagal mengembalikan status: "failed" dengan error.
Statusnya adalah pending, processing, completed, dan failed. Tugas yang selesai dapat menyertakan audio_url, video_url, title, lyrics, dan metadata lainnya. URL media adalah URL TokenLab yang tetap valid selama 30 hari; unduh atau simpan hasil yang Anda perlukan untuk waktu lebih lama.
Menampilkan status yang tepat
- Tampilkan status tertunda (pending) segera setelah pembuatan tugas.
- Lakukan polling setiap
5-10 detikuntuk tugas yang lama, lalu berhenti saatcompletedataufailed. - Jangan menampilkan pemutar akhir sampai tugas
completeddanaudio_urltersedia. - Untuk tugas lirik saja, render output teks secara terpisah dari tugas audio agar pengguna memahami apa yang mereka beli.
- Saat penyegaran (refresh), lanjutkan dari
task_idyang tersimpan alih-alih membuat tugas baru.
Catatan penagihan
Tugas musik dapat mencadangkan jumlah estimasi saat dibuat. Jumlah akhir dicatat setelah selesai atau gagal. Simpan request_id, task_id, model, endpoint, dan billing_transaction_id saat muncul; gunakan catatan penggunaan Management API untuk biaya akhir.
Kesalahan Umum
| Gejala | Penyebab umum | Perbaikan |
|---|---|---|
| Tugas dibuat tetapi tidak ada pemutar | Tugas masih tertunda atau selesai tanpa audio_url | Terus lakukan polling hingga terminal, lalu tangani output yang hilang sebagai pekerjaan pengguna yang gagal |
| Lagu duplikat setelah penyegaran | UI membuat ulang tugas alih-alih melanjutkannya | Simpan dan gunakan kembali task_id |
| Tugas lirik tidak mengembalikan audio | action: "LYRICS" hanya berupa teks | Pisahkan jalur UI lirik dan musik |
| Parameter tidak didukung | Model yang dipilih tidak menerima bidang tersebut | Hapus 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 |