API pengklonan suara dan penjanaan dengan suara yang ditetapkan (tidak disyorkan)

Dikemas kini 2026-09-18 · pasukan Suno-API

⛔ Laluan lama, tidak disyorkan untuk integrasi baharu. Halaman ini menerangkan laluan persona awal (voice_task_id / generate-with-voice). Ia masih berfungsi, tetapi tidak lagi disyorkan kepada pelanggan; menu di kiri menandakannya sebagai "tidak disyorkan".

Untuk integrasi baharu gunakan 【Disyorkan】 API profil suara: bina profil suara daripada satu sampel vokal (POST /api/music/voice-profile/create), kemudian gunakannya untuk membuat kover lagu tertentu atau menyanyikan lagu baharu. Profil suara ialah sumber kelas pertama: boleh disenaraikan, diambil dan dipadam, serta audio sumbernya disimpan secara kekal.

Jika produk anda memerlukan kitaran lengkap "bina suara → guna semula jangka panjang → kover", utamakan laluan baharu.

Penting: suara yang diklon boleh luput.

voice_id / voice_task_id yang dihasilkan oleh pengklonan suara bukan sumber yang boleh digunakan selama-lamanya: ia boleh berhenti berfungsi kerana tempoh sah, keadaan akaun atau perubahan keadaan suara. Pihak yang berintegrasi tidak boleh mengklon sekali kemudian menggunakan semula ID suara yang di-cache secara tempatan selama-lamanya.

Amalan yang disyorkan:

• Simpan voice_task_id, voice_id, is_available, updated_at dan masa penjanaan berjaya yang terakhir.
• Sebelum setiap penjanaan dengan suara yang diklon, 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 memulangkan bahawa suara tidak tersedia, tugasan tidak wujud atau selected voice is not ready, minta pengguna mengklon semula atau memilih suara lain yang tersedia.
• Jangan berjanji kepada pengguna akhir bahawa suara yang diklon ialah "aset kekal"; tunjukkan dalam antara muka produk bahawa "suara boleh luput dan perlu disahkan semula atau diklon semula".

Penerangan endpoint

Kumpulan endpoint ini membina suara yang boleh diguna semula dan menjana lagu dengannya. Pemanggil hanya memerlukan API Key yang dikeluarkan platform; pelayan mengendalikan penghantaran tugasan, penyegerakan status, pengebilan dan muat turun.

Pengesahan: Authorization: Bearer YOUR_API_KEY

Pengebilan:

• Pengesahan suara, pengklonan suara, pertanyaan status, pemadaman dan muat turun: percuma.
• Pintu masuk klon satu langkah dalam ruang kerja: 5 ¥ tetap setiap panggilan; ia menyelesaikan pengesahan suara sumber dan audio pengesahan kedua secara automatik, dan memulangkan dana jika gagal.
• Meneruskan secara automatik ke audio pengesahan selepas klon biasa: 5 ¥ tetap setiap panggilan; jika gagal dipulangkan mengikut aliran sedia ada.
• Menjana lagu dengan suara yang diklon: berbayar, 1.2 ¥ tetap setiap panggilan; setiap panggilan biasanya memulangkan 2 tugasan pemegang tempat.
• Apabila Max Mode dihidupkan (max_mode: true pada POST /api/music/generate-with-voice), kadar 1.2 ¥ setiap panggilan dibilkan pada 2×, iaitu 2.4 ¥ setiap panggilan; penjanaan suara juga menyokong variety (0-4, tanpa caj tambahan); peraturan nilainya ada dalam bahagian "Parameter lanjutan" pada gambaran keseluruhan API baharu.

Aliran panggilan

1. Panggil POST /api/voice/clone/validate untuk memuat naik suara sumber dan mendapat voice_task_id.
2. Tunggu atau tinjau GET /api/voice/clone/tasks/{voice_task_id} sehingga mendapat validate_info.
3. Pengguna membaca teks itu dengan kuat dan merakam audio pengesahan.
4. Panggil POST /api/voice/clone/tasks/{voice_task_id}/generate untuk menghantar audio pengesahan.
5. Panggil POST /api/voice/clone/tasks/{voice_task_id}/check atau terus pertanyaan tugasan sehingga is_available=true.
6. Panggil POST /api/music/generate-with-voice untuk menjana lagu dengan suara itu.
7. Endpoint penjanaan memulangkan tugasan pemegang tempat dahulu; apabila penjanaan selesai dan anda mendapat song_id sebenar, gunakan endpoint muat turun untuk mendapatkan satu fail atau satu pakej.
8. (Pilihan) Apabila suara tidak diperlukan lagi, panggil DELETE /api/voice/clone/voices/{voice_task_id} untuk memadamnya; semantiknya dalam bahagian 6.

Terdapat juga pengklonan satu langkah: pada halaman rakaman/muat naik suara sumber yang pertama dalam ruang kerja, anda boleh memilih selesai dalam satu langkah; sistem menyelesaikan pengesahan dan pembinaan suara sekali gus, jadi anda tidak perlu merakam audio pengesahan kedua; kosnya 5 ¥ setiap panggilan dan dipulangkan jika gagal.

Medan tugasan suara

1. Hantar suara sumber untuk pengesahan

Endpoint: POST /api/voice/clone/validate

Parameter body

vocal_end_s - vocal_start_s mesti memenuhi syarat minimum segmen vokal. Muat naik rakaman vokal yang bersih, tanpa iringan atau bunyi bising yang jelas.

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 semula jadi",
    "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. Pertanyaan tugasan 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": "Baca dengan kuat teks pengesahan yang dipulangkan di sini",
      "validate_status": "success",
      "is_available": false,
      "status": "validate_ready",
      "stage": "validate_callback"
    }
  }
}

3. Jana semula teks pengesahan

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

Panggil apabila teks pengesahan tidak sesuai untuk dibaca dengan kuat atau pengesahan 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. Hantar audio pengesahan dan bina 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 sama ada suara boleh digunakan

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 '{}'

Apabila tugasan boleh digunakan, is_available dalam respons ialah true dan voice_id dipulangkan.

6. Padam suara

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

Pengebilan: percuma.

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 berlaku selepas pemadaman

• Tidak boleh lagi digunakan untuk menjana lagu baharu: memanggil POST /api/music/generate-with-voice dengan voice_task_id ini (atau voice_id-nya) akan ditolak dengan mesej selected voice is not ready, tanpa caj.
• Lagu yang sudah dijana dengannya tidak terjejas sama sekali: main balik, muat turun, sambungan, penggantian dan pemisahan stem berfungsi seperti biasa.
• Tugasan suara ini hilang daripada pertanyaan: GET /api/voice/clone/tasks/{voice_task_id} memulangkan record not found.
• Audio sumber disimpan mengikut polisi penyimpanan kekal platform (sejak 2026-09-23 pemadaman tidak lagi membersihkan sampel vokal yang anda muat naik), tetapi itu tidak bermakna ia boleh dipulihkan: tugasan lama telah tamat dan untuk terus menggunakan suara yang sama anda perlu melalui aliran pengklonan semula, yang menghasilkan voice_task_id baharu.
• Padam dua kali: memadam tugasan yang sama sekali lagi memulangkan record not found (ia sudah dalam keadaan dipadam dan tidak boleh ditemui).

7. Jana lagu dengan suara yang diklon

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

Pengebilan: 1.2 ¥ setiap panggilan.

Parameter body

suno-v6, suno-v6-wild dan suno-v6-mini disokong; model kosong dianggap suno-v6. Model lama V5/V5.5 telah dihentikan, tetapi tugasan sejarah mungkin masih memaparkan nama model lama.

Struktur permintaan bersama juga mentafsir medan keserasian Create UI seperti task, soundType, soundLoop, soundBpm, soundKey, voiceTaskId dan voiceId, tetapi ia bukan parameter pelanggan yang sah untuk endpoint ini: tugasan suara mesti dihantar sebagai voice_task_id, pengesahan suara pilihan sebagai voice_id, dan penjanaan muzik dengan suara tidak pernah membaca medan sound.

Cara mengisi parameter penjanaan

• Apabila customMode=false, prompt mengandungi penerangan lagu; apabila customMode=true, prompt mengandungi lirik penuh, dan style serta title juga mesti diisi. Jangan hantar lirik ke medan penerangan mod ilham dan jangan anggap penerangan lagu sebagai lirik mod lanjutan.
• weirdnessConstraint dan styleWeight ialah nisbah perpuluhan dari 0.0 hingga 1.0; 50 atau 50% tidak boleh dihantar. 0.5 ialah nilai seimbang; tidak menghantarnya bermaksud "tidak dinyatakan", dan 0 ialah nilai eksplisit yang sah.
• vocalGender hanya menerima m, male, f atau female. instrumental di sini hanyalah medan keserasian: penjanaan dengan suara yang diklon sentiasa dianggap lagu bervokal.
• waitAudio tidak mengubah tingkah laku di sini; endpoint sentiasa memulangkan tugasan pemegang tempat secara tak segerak. audio_url kosong dalam hasil awal adalah normal: pertanyaan dengan client_request_id dan baca alamat audio hanya selepas hasilnya siap.

Parameter header

Tingkah laku Idempotency-Key:

• Permintaan pertama menulis rekod idempotensi kekal sebelum pengebilan;
• Jika kunci yang sama dengan permintaan yang sama sudah selesai, respons penerimaan pertama dipaparkan semula, tanpa caj kedua dan tanpa tugasan kedua;
• Kunci yang sama dengan body berbeza akan ditolak;
• Kunci yang sama yang masih diproses memulangkan ralat "sedang diproses" yang stabil dan hanya mendedahkan client_request_id yang selamat apabila ia telah dijana;
• Jika permintaan pertama dengan sesuatu kunci gagal, status gagal kekal; cubaan semula memerlukan kunci baharu.

Syarat kover dengan sourceClipId

Kover daripada sumber dalam API pelanggan dikendalikan sepenuhnya di pihak pelayan: akses kepada lagu sumber diselesaikan oleh pelayan dan pelanggan tidak menghantar sebarang maklumat akaun. Boleh atau tidak ditentukan oleh respons sebenar endpoint.

Sumber mesti milik pengguna API semasa, lagu ruang kerja yang telah siap dan bukan pending:, serta mempunyai audio yang boleh digunakan. Disokong penjanaan biasa, sumber muat naik biasa dan lagu akhir muat naik diperkukuh; rekod pertengahan muat naik diperkukuh ditolak sebelum pengebilan. Pelayan hanya menerima ID lagu sumber yang dihantar pelanggan dan tidak pernah menerima ID akaun; sumber yang tidak tersedia atau belum siap memulangkan ralat sebelum pengebilan.

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": "Bayu 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": "Bayu 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": "Bayu laut malam musim panas",
        "prompt": "Tulis lagu pop Mandarin tentang tepi laut pada malam musim panas"
      }
    ],
    "pre_consumed_quota": 600000,
    "billing_source": "wallet"
  }
}

Tentang tugasan pemegang tempat dan song_id akhir

generate-with-voice ialah endpoint penjanaan tak segerak. Respons berjaya hanya bermakna tugasan penjanaan telah dihantar, bukan bahawa lagu sudah siap.

Maksud medan utama dalam respons:

Perhatian: placeholder_id yang bermula dengan pending: tidak boleh digunakan sebagai song_id akhir dan tidak boleh dihantar terus ke /api/music/query atau endpoint muat turun. Memanggil /api/music/query hanya dengan nilai pending:* mungkin memulangkan tatasusunan kosong [], kerana lagu sebenar belum siap atau tugasan pemegang tempat belum digantikan dengan ID lagu akhir.

Contoh salah:

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

Aliran betul:

1. Panggil POST /api/music/generate-with-voice untuk menghantar tugasan penjanaan muzik dengan suara.
2. Simpan client_request_id, items[].placeholder_id dan items[].client_request_index daripada respons.
3. Tinjau GET /api/music/generate-with-voice/results?client_request_id=cu_xxx.
4. Apabila items[].song_id mempunyai nilai dan tidak bermula dengan pending:, panggil /api/music/query, /api/music/download-file atau /api/music/download-all.

Versi semasa menambah endpoint pertanyaan awam:

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

Ia memulangkan hasil tugasan bagi client_request_id yang sama di bawah pengguna semasa, supaya pelanggan boleh mencari song_id akhir sendiri. Dalam senarai yang dipulangkan:

• song_id ialah ID lagu sebenar;
• placeholder_id hanya muncul selagi tugasan masih dalam keadaan pemegang tempat;
• nilai yang bermula dengan pending: tidak boleh digunakan dengan /api/music/query atau endpoint muat turun.

Jika anda hanya menyimpan client_request_id atau ID pemegang tempat pending:*, panggil endpoint hasil ini dahulu; jika song_id sebenar masih tidak dijumpai, hantar client_request_id kepada sokongan teknikal untuk dikesan.

Pertanyaan hasil penjanaan muzik dengan suara

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

Pengebilan: percuma.

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 semasa dijana

{
  "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": "Bayu laut malam musim panas"
      }
    ]
  }
}

Contoh respons selepas 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": "Bayu laut malam musim panas",
        "audio_url": "https://...",
        "image_url": "https://...",
        "duration": 180.5
      }
    ]
  }
}

Maksud status peringkat atas

8. Muat turun satu fail

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 ialah strim fail; Content-Type dan nama fail mengikut apa yang dipulangkan backend.

9. Muat turun sumber lagu sebagai pakej

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

Pakej biasanya mengandungi audio, kulit album dan metadata.json; jika sesuatu jenis sumber belum dijana, ia tidak dimasukkan ke dalam arkib.

Ralat biasa

Ralat kumpulan ini sentiasa memulangkan HTTP 200: nilai kejayaan daripada medan success dalam body (false bermaksud gagal, puncanya dalam message) dan jangan hanya melihat kod status HTTP. Semantik penuh pemadaman suara (sama ada masih boleh digunakan, sama ada boleh dipulihkan) ada dalam bahagian 6.