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 dibuatBidang kunciCatatan
Lagu penuh atau instrumentalmodel, mv, prompt, opsional title, tags, action: "MUSIC"Gunakan saat pengguna mengharapkan audio akhir
Lirik sajamodel, prompt, action: "LYRICS"Gunakan hanya dengan model yang menyediakan pembuatan lirik
Melanjutkan klip yang adamodel, mv, prompt, continue_clip_id, opsional continue_atPertahankan ID klip sebelumnya
Sampul atau memperpanjang audio Anda sendirimodel, mv, prompt, audio_url, opsional audio_operationaudio_url harus berupa URL publik. audio_operation secara default adalah upload-cover; upload-extend juga memerlukan continue_at
Menambahkan instrumental, mengganti bagian, atau memisahkan stemaudio_operation: add-instrumental, replace-section, vocal-separate, multi-stem-separation, atau advanced-splitSetiap 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 detik untuk tugas yang lama, lalu berhenti saat completed atau failed.
  • Jangan menampilkan pemutar akhir sampai tugas completed dan audio_url tersedia.
  • 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_id yang 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

GejalaPenyebab umumPerbaikan
Tugas dibuat tetapi tidak ada pemutarTugas masih tertunda atau selesai tanpa audio_urlTerus lakukan polling hingga terminal, lalu tangani output yang hilang sebagai pekerjaan pengguna yang gagal
Lagu duplikat setelah penyegaranUI membuat ulang tugas alih-alih melanjutkannyaSimpan dan gunakan kembali task_id
Tugas lirik tidak mengembalikan audioaction: "LYRICS" hanya berupa teksPisahkan jalur UI lirik dan musik
Parameter tidak didukungModel yang dipilih tidak menerima bidang tersebutHapus atau pilih model yang mendokumentasikannya

Referensi API

TopikReferensi
Buat MusikBuat Musik
Dapatkan Status MusikDapatkan Status Musik
Dapatkan Status TugasDapatkan Status Tugas
Daftar ModelDaftar Model
Penagihan & HargaPenagihan & Harga

Di halaman ini