API kloning suara dan pembuatan dengan suara yang ditentukan (tidak disarankan)

Diperbarui 2026-09-18 · tim Suno-API

⛔ Jalur lama, tidak disarankan untuk integrasi baru. Halaman ini menjelaskan jalur persona awal (voice_task_id / generate-with-voice). Masih berfungsi, tetapi tidak lagi disarankan kepada pelanggan; menu di kiri menandainya "tidak disarankan".

Untuk integrasi baru gunakan 【Disarankan】 API profil suara: buat profil suara dari satu sampel vokal (POST /api/music/voice-profile/create), lalu pakai untuk meng-cover lagu tertentu atau menyanyikan lagu baru. Profil suara adalah sumber daya kelas satu: bisa didaftar, diambil, dan dihapus, serta audio sumbernya disimpan permanen.

Jika produk Anda memerlukan siklus lengkap "buat suara → pakai ulang jangka panjang → cover", prioritaskan jalur baru.

Penting: suara hasil kloning bisa kedaluwarsa.

voice_id / voice_task_id yang dihasilkan kloning suara bukan sumber daya yang bisa dipakai selamanya: bisa berhenti berfungsi karena masa berlaku, status akun, atau perubahan status suara. Pihak yang mengintegrasikan tidak boleh mengkloning sekali lalu memakai ulang ID suara yang di-cache lokal selamanya.

Praktik yang disarankan:

• Simpan voice_task_id, voice_id, is_available, updated_at, dan waktu pembuatan sukses terakhir.
• Sebelum setiap pembuatan memakai suara hasil kloning, panggil GET /api/voice/clone/tasks/{voice_task_id} atau POST /api/voice/clone/tasks/{voice_task_id}/check dan pastikan is_available=true.
• Jika endpoint menjawab suara tidak tersedia, tugas tidak ada, atau selected voice is not ready, minta pengguna mengkloning ulang atau memilih suara lain yang tersedia.
• Jangan menjanjikan ke pengguna akhir bahwa suara hasil kloning adalah "aset permanen"; tampilkan di antarmuka produk bahwa "suara bisa kedaluwarsa dan perlu validasi ulang atau kloning ulang".

Deskripsi endpoint

Grup endpoint ini membuat suara yang dapat dipakai ulang dan membuat lagu dengan suara itu. Pemanggil hanya perlu API Key dari platform; server menangani pengiriman tugas, sinkronisasi status, penagihan, dan unduhan.

Autentikasi: Authorization: Bearer YOUR_API_KEY

Biaya:

• Validasi suara, kloning suara, kueri status, penghapusan, dan unduhan: gratis.
• Pintu kloning satu langkah di ruang kerja: 5 ¥ tetap per panggilan; menyelesaikan validasi suara sumber dan audio verifikasi kedua secara otomatis, dan mengembalikan dana jika gagal.
• Lanjut otomatis ke audio verifikasi setelah kloning biasa: 5 ¥ tetap per panggilan; jika gagal dikembalikan sesuai alur yang berlaku.
• Membuat lagu dengan suara hasil kloning: berbayar, 1,2 ¥ tetap per panggilan; tiap panggilan biasanya mengembalikan 2 tugas placeholder.
• Saat Max Mode aktif (max_mode: true pada POST /api/music/generate-with-voice), tarif 1,2 ¥ per panggilan ditagih 2×, yaitu 2,4 ¥ per panggilan; pembuatan suara juga mendukung variety (0-4, tanpa biaya tambahan); aturan nilainya ada di bagian "Parameter lanjutan" pada ringkasan API baru.

Alur pemanggilan

1. Panggil POST /api/voice/clone/validate untuk mengunggah suara sumber dan mendapatkan voice_task_id.
2. Tunggu atau polling GET /api/voice/clone/tasks/{voice_task_id} sampai mendapat validate_info.
3. Pengguna membacakan teks itu dan merekam audio verifikasi.
4. Panggil POST /api/voice/clone/tasks/{voice_task_id}/generate untuk mengirim audio verifikasi.
5. Panggil POST /api/voice/clone/tasks/{voice_task_id}/check atau terus kueri tugasnya sampai is_available=true.
6. Panggil POST /api/music/generate-with-voice untuk membuat lagu dengan suara itu.
7. Endpoint pembuatan mengembalikan tugas placeholder lebih dulu; setelah pembuatan selesai dan Anda mendapat song_id sebenarnya, gunakan endpoint unduhan untuk mengambil satu berkas atau satu paket.
8. (Opsional) Saat suara tidak diperlukan lagi, panggil DELETE /api/voice/clone/voices/{voice_task_id} untuk menghapusnya; semantiknya di bagian 6.

Ada juga kloning satu langkah: pada halaman perekaman/pengunggahan suara sumber pertama di ruang kerja, Anda bisa memilih selesai dalam satu langkah; sistem menyelesaikan validasi dan pembuatan suara sekaligus, sehingga Anda tidak perlu merekam audio verifikasi kedua; biayanya 5 ¥ per panggilan dan dikembalikan jika gagal.

Field tugas suara

1. Kirim suara sumber untuk divalidasi

Endpoint: POST /api/voice/clone/validate

Parameter body

vocal_end_s - vocal_start_s harus memenuhi syarat minimum segmen vokal. Unggah rekaman vokal yang bersih, tanpa iringan atau derau yang mencolok.

Contoh permintaan

curl -X POST https://www.suno-api.io/api/voice/clone/validate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_url": "https://example.com/source-voice.wav",
    "voice_name": "Suara wanita Mandarin saya",
    "description": "Suara wanita Mandarin yang jernih dan alami",
    "style": "Mandopop",
    "singer_skill_level": "intermediate",
    "language": "zh",
    "vocal_start_s": 1.2,
    "vocal_end_s": 18.5,
    "source_duration_seconds": 20
  }'

Contoh respons

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Suara wanita Mandarin saya",
      "language": "zh",
      "validate_status": "submitted",
      "is_available": false,
      "status": "validate_submitted",
      "stage": "validate_submitted",
      "created_at": 1780480000,
      "updated_at": 1780480000
    }
  }
}

2. Kueri tugas suara

Endpoint: GET /api/voice/clone/tasks/{voice_task_id}

Contoh permintaan

curl https://www.suno-api.io/api/voice/clone/tasks/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Contoh respons

{
  "success": true,
  "message": "",
  "data": {
    "voice": {
      "voice_task_id": 123,
      "voice_name": "Suara wanita Mandarin saya",
      "validate_info": "Bacakan teks verifikasi yang dikembalikan di sini",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. Buat ulang teks verifikasi

Endpoint: POST /api/voice/clone/tasks/{voice_task_id}/regenerate

Panggil bila teks verifikasi tidak cocok untuk dibacakan atau validasi perlu diulang.

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/regenerate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

4. Kirim audio verifikasi dan buat suara

Endpoint: POST /api/voice/clone/tasks/{voice_task_id}/generate

Parameter body

Contoh permintaan

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/generate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "verify_url": "https://example.com/verify-voice.wav",
    "voice_name": "Suara wanita Mandarin saya"
  }'

5. Periksa apakah suara bisa dipakai

Endpoint: POST /api/voice/clone/tasks/{voice_task_id}/check

curl -X POST https://www.suno-api.io/api/voice/clone/tasks/123/check \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Saat tugas sudah bisa dipakai, is_available pada respons bernilai true dan voice_id dikembalikan.

6. Hapus suara

Endpoint: DELETE /api/voice/clone/voices/{voice_task_id}

Biaya: gratis.

curl -X DELETE https://www.suno-api.io/api/voice/clone/voices/123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Contoh respons

{
  "success": true,
  "message": "",
  "data": {
    "voice_task_id": 123,
    "deleted": true
  }
}

Apa yang terjadi setelah dihapus

• Tidak bisa lagi dipakai membuat lagu baru: memanggil POST /api/music/generate-with-voice dengan voice_task_id ini (atau voice_id-nya) akan ditolak dengan pesan selected voice is not ready, tanpa biaya.
• Lagu yang sudah dibuat dengannya sama sekali tidak terpengaruh: pemutaran, unduhan, lanjutan, penggantian, dan pemisahan stem tetap berjalan seperti biasa.
• Tugas suara ini hilang dari kueri: GET /api/voice/clone/tasks/{voice_task_id} mengembalikan record not found.
• Audio sumber tetap disimpan sesuai kebijakan penyimpanan permanen platform (sejak 2026-09-23 penghapusan tidak lagi membersihkan sampel vokal yang Anda unggah), tetapi itu tidak berarti bisa dipulihkan: tugas lama sudah berakhir, dan untuk melanjutkan dengan suara yang sama Anda harus melewati alur kloning lagi, yang menghasilkan voice_task_id baru.
• Hapus dua kali: menghapus tugas yang sama sekali lagi mengembalikan record not found (sudah dalam status terhapus dan tidak bisa ditemukan).

7. Buat lagu dengan suara hasil kloning

Endpoint: POST /api/music/generate-with-voice

Biaya: 1,2 ¥ per panggilan.

Parameter body

suno-v6, suno-v6-wild, dan suno-v6-mini didukung; model kosong diperlakukan sebagai suno-v6. Model lama V5/V5.5 sudah dihentikan, tetapi tugas historis mungkin masih menampilkan nama model lama.

Struktur permintaan bersama juga membaca field kompatibilitas Create UI seperti task, soundType, soundLoop, soundBpm, soundKey, voiceTaskId, dan voiceId, namun itu bukan parameter pelanggan yang valid untuk endpoint ini: tugas suara harus dikirim sebagai voice_task_id, verifikasi suara opsional sebagai voice_id, dan pembuatan musik dengan suara tidak pernah membaca field sound.

Cara mengisi parameter pembuatan

• Saat customMode=false, prompt berisi deskripsi lagu; saat customMode=true, prompt berisi lirik lengkap, dan style serta title juga harus diisi. Jangan mengirim lirik ke field deskripsi mode inspirasi dan jangan memperlakukan deskripsi lagu sebagai lirik mode lanjutan.
• weirdnessConstraint dan styleWeight adalah rasio desimal dari 0.0 sampai 1.0; 50 atau 50% tidak bisa dikirim. 0.5 adalah nilai seimbang; tidak mengirim berarti "tidak ditentukan", dan 0 adalah nilai eksplisit yang valid.
• vocalGender hanya menerima m, male, f, atau female. instrumental di sini hanya field kompatibilitas: pembuatan dengan suara hasil kloning selalu diperlakukan sebagai lagu bervokal.
• waitAudio tidak mengubah perilaku di sini; endpoint selalu mengembalikan tugas placeholder secara asinkron. audio_url kosong pada hasil awal itu normal: kueri dengan client_request_id dan baca alamat audio hanya setelah hasilnya selesai.

Parameter header

Perilaku Idempotency-Key:

• Permintaan pertama menulis catatan idempotensi permanen sebelum penagihan;
• Jika kunci yang sama dengan permintaan yang sama sudah selesai, respons penerimaan pertama diputar ulang, tanpa tagihan kedua dan tanpa tugas kedua;
• Kunci yang sama dengan body berbeda akan ditolak;
• Kunci yang sama yang masih diproses mengembalikan galat "sedang diproses" yang stabil dan hanya menampilkan client_request_id yang aman setelah dihasilkan;
• Jika permintaan pertama dengan suatu kunci gagal, status gagal tetap berlaku; mencoba lagi memerlukan kunci baru.

Syarat cover dengan sourceClipId

Cover dari sumber di API pelanggan ditangani sepenuhnya di sisi server: akses ke lagu sumber diselesaikan server dan pelanggan tidak mengirim data akun apa pun. Bisa atau tidaknya ditentukan respons sebenarnya dari endpoint.

Sumber harus milik pengguna API saat ini, berupa lagu ruang kerja yang sudah selesai dan bukan pending:, serta memiliki audio yang bisa dipakai. Didukung pembuatan biasa, sumber dari unggahan biasa, dan lagu akhir unggahan yang diperkuat; catatan antara unggahan yang diperkuat ditolak sebelum penagihan. Server hanya menerima ID lagu sumber yang dikirim pelanggan dan tidak pernah menerima ID akun; sumber yang tidak tersedia atau belum selesai mengembalikan galat sebelum penagihan.

Contoh permintaan

curl -X POST https://www.suno-api.io/api/music/generate-with-voice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_task_id": 123,
    "customMode": true,
    "prompt": "Tulis lagu pop Mandarin tentang tepi laut pada malam musim panas",
    "style": "Mandopop, warm piano, emotional",
    "title": "Angin laut malam musim panas",
    "negativeTags": "noise, low quality",
    "instrumental": false,
    "model": "suno-v6"
  }'

Contoh respons

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "items": [
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Angin laut malam musim panas",
        "prompt": "Tulis lagu pop Mandarin tentang tepi laut pada malam musim panas"
      },
      {
        "placeholder_id": "pending:cu_1780480000_abcd1234:1",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 1,
        "status": "submitted",
        "type": "voice_generate",
        "title": "Angin laut malam musim panas",
        "prompt": "Tulis lagu pop Mandarin tentang tepi laut pada malam musim panas"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

Tentang tugas placeholder dan song_id akhir

generate-with-voice adalah endpoint pembuatan asinkron. Respons sukses hanya berarti tugas pembuatan sudah dikirim, bukan bahwa lagunya sudah selesai.

Arti field penting pada respons:

Perhatian: placeholder_id yang dimulai dengan pending: tidak bisa dipakai sebagai song_id akhir dan tidak bisa langsung dikirim ke /api/music/query atau endpoint unduhan. Memanggil /api/music/query hanya dengan nilai pending:* bisa mengembalikan array kosong [], karena lagu sebenarnya belum selesai atau tugas placeholder belum diganti dengan ID lagu akhir.

Contoh yang salah:

{
  "song_ids": "pending:cu_1780480000_abcd1234:0"
}

Alur yang benar:

1. Panggil POST /api/music/generate-with-voice untuk mengirim tugas pembuatan musik dengan suara.
2. Simpan client_request_id, items[].placeholder_id, dan items[].client_request_index dari respons.
3. Polling GET /api/music/generate-with-voice/results?client_request_id=cu_xxx.
4. Saat items[].song_id sudah bernilai dan tidak diawali pending:, panggil /api/music/query, /api/music/download-file, atau /api/music/download-all.

Versi saat ini menambahkan endpoint kueri publik:

GET /api/music/generate-with-voice/results?client_request_id=cu_xxx

Endpoint ini mengembalikan hasil tugas dengan client_request_id yang sama di bawah pengguna saat ini, sehingga pelanggan dapat mencari song_id akhir sendiri. Dalam daftar yang dikembalikan:

• song_id adalah ID lagu sebenarnya;
• placeholder_id hanya muncul selama tugas masih berstatus placeholder;
• nilai yang diawali pending: tidak bisa dipakai dengan /api/music/query atau endpoint unduhan.

Jika Anda hanya menyimpan client_request_id atau ID placeholder pending:*, panggil endpoint hasil ini lebih dulu; bila song_id sebenarnya tetap tidak ditemukan, kirim client_request_id ke dukungan teknis untuk ditelusuri.

Kueri hasil pembuatan musik dengan suara

Endpoint: GET /api/music/generate-with-voice/results

Biaya: gratis.

Parameter query

Contoh permintaan

curl -X GET "https://www.suno-api.io/api/music/generate-with-voice/results?client_request_id=cu_1780480000_abcd1234" \
  -H "Authorization: Bearer YOUR_API_KEY"

Contoh respons saat sedang dibuat

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "processing",
    "items": [
      {
        "song_id": "",
        "placeholder_id": "pending:cu_1780480000_abcd1234:0",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "processing",
        "type": "voice_generate",
        "title": "Angin laut malam musim panas"
      }
    ]
  }
}

Contoh respons setelah selesai

{
  "success": true,
  "message": "",
  "data": {
    "client_request_id": "cu_1780480000_abcd1234",
    "status": "completed",
    "items": [
      {
        "song_id": "song_abc123",
        "client_request_id": "cu_1780480000_abcd1234",
        "client_request_index": 0,
        "status": "completed",
        "type": "voice_generate",
        "title": "Angin laut malam musim panas",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

Arti status tingkat teratas

8. Unduh satu berkas

Endpoint: POST /api/music/download-file

Parameter body

Contoh permintaan

curl -X POST https://www.suno-api.io/api/music/download-file \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123",
    "kind": "audio"
  }' \
  --output song.mp3

Responsnya adalah aliran berkas; Content-Type dan nama berkas mengikuti yang dikembalikan backend.

9. Unduh sumber daya lagu sebagai paket

Endpoint: POST /api/music/download-all

Parameter body

Contoh permintaan

curl -X POST https://www.suno-api.io/api/music/download-all \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "song_id": "song_abc123"
  }' \
  --output song.zip

Paket biasanya berisi audio, sampul, dan metadata.json; jika suatu jenis sumber daya belum dibuat, berkas itu tidak dimasukkan ke arsip.

Kesalahan umum

Kesalahan grup ini selalu mengembalikan HTTP 200: nilai keberhasilan dari field success di body (false berarti gagal, alasannya di message) dan jangan hanya melihat kode status HTTP. Semantik lengkap penghapusan suara (apakah masih bisa dipakai, apakah bisa dipulihkan) ada di bagian 6.