【Disyorkan】 API profil suara

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

✅ Jalur ini kami syorkan untuk integrasi baharu. Menurut penilaian sebenar ramai pengguna, lagu yang dijana melalui jalur ini mengekalkan suara asal dengan baik: vokal dalam hasil akhir lebih menyerupai orang dalam sampel yang anda muat naik, jadi inilah jalur yang kami syorkan kepada pelanggan pada masa ini.

Perbandingan: API pengklonan suara dan penjanaan dengan suara yang ditetapkan sebelum ini masih berfungsi, tetapi menu menandakannya sebagai "tidak disyorkan" dan ia tidak lagi disyorkan untuk integrasi baharu.

• Tarikh dokumen: 2026-09-26
• Skop: membina suara anda sendiri → menggunakannya untuk meng-kover lagu tertentu / menyanyikan lagu baharu → memantau kemajuan → memuat turun hasil
• Semua endpoint, medan dan respons telah disahkan dengan panggilan sebenar (yang bertanda "diukur" disahkan secara terperinci)

Nota: dokumen ini hanya menerangkan endpoint yang anda panggil. Pemprosesan bahan, penjadualan tugasan dan pengesahan kandungan dilakukan secara automatik oleh pelayan; klien tidak melaksanakannya.

0. Bermula dalam lima minit

Empat langkah cukup untuk menukar satu sampel vokal menjadi dua lagu siap.

① Bina suara    POST /api/music/voice-profile/create      → dapat voice_id (status=ready)
② Kover         POST /api/music/voice-profile/cover       → terus dapat 2 song_id
③ Pantau        POST /api/music/query                     → tinjau sehingga status=completed
④ Muat turun    GET  /api/music/download?song_id=…&kind=mp3

Contoh minimum (curl):

API_KEY="sk-kunci-anda"
BASE="https://www.suno-api.io"

# ① Bina suara (muat naik sampel vokal; 10 saat atau lebih, bawah 10 MB disyorkan)
curl -sS -X POST "$BASE/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" \
  -F "title=Suara saya" \
  -F "source_kind=upload"
# → {"success":true,"message":"","data":{"voice_id":"vp_2026…","status":"ready", …}}

# ② Kover satu lagu dengan suara ini (song_clip_id = clip id lagu yang hendak dikover)
curl -sS -X POST "$BASE/api/music/voice-profile/cover" \
  -H "Authorization: Bearer $API_KEY" \
  -H "X-Create-Ui-Client-Request-Id: cover-$(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
        "model": "suno-v6",
        "voice_id": "vp_2026…",
        "song_clip_id": "5b773e9a-…",
        "lyrics": "[Verse 1]\nlirik…",
        "style_requirements": "folk perlahan, gitar akustik",
        "audio_weight": 0.85,
        "max_mode": false
      }'
# → {"code":200,"message":"success","data":{"resolved_scene":"cover","clips":[{…},{…}]}}

# ③ Tinjau (hantar beberapa id sekali gus, dipisah koma)
curl -sS -X POST "$BASE/api/music/query" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"suno-v6","song_ids":"id1,id2"}'

# ④ Muat turun mp3 selepas siap (fail hanya ada apabila status=completed)
curl -sS -L "$BASE/api/music/download?song_id=id1&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song1.mp3

1. Konvensyen umum

1.1 Domain dan persekitaran

Semua laluan di bawah adalah relatif kepada Base URL; contohnya alamat penuh POST /api/music/voice-profile/create ialah https://www.suno-api.io/api/music/voice-profile/create.

1.2 Pengesahan

Semua endpoint menggunakan pengepala permintaan yang sama, nilainya ialah API Key yang anda cipta dalam konsol:

Authorization: Bearer sk-xxxxxxxx

• Awalan Bearer tidak wajib; awalan sk- juga (Authorization: sk-xxx berfungsi juga).
• Kunci hilang atau tidak sah → HTTP 401, badan balasan seperti {"success":false,"message":"…"} (teks mengikut bahasa permintaan).
• Setiap kunci hanya boleh melihat dan mengendalikan lagu serta suara milik akaunnya sendiri.

1.3 Format badan permintaan

• Membina suara: disyorkan multipart/form-data (memuat naik fail); application/json (URL atau base64) juga disokong.
• Endpoint lain: application/json.

1.4 Dua pembalut respons (pelanggan hanya perlu mengenali dua ini)

Endpoint "pengurusan suara" (create / create-from-clip / list / detail / delete) menggunakan pembalut perniagaan:

{ "success": true, "message": "", "data": { } }

{ "success": false, "message": "voice_id is required" }

"Kover dengan suara" melalui saluran penjanaan dan menggunakan pembalut penjanaan: berjaya ialah code/message/data, gagal ialah objek error:

{ "code": 200, "message": "success", "data": { } }

{ "error": { "message": "voice not found: vp_xxx", "type": "bad_response_status_code", "param": "", "code": "bad_response_status_code" } }

Cara menilai: lihat kod status HTTP dahulu, kemudian success === false, akhir sekali code !== 200 atau kewujudan error. Kegagalan perniagaan tidak menjamin HTTP selain 200 (endpoint pengurusan suara masih HTTP 200 ketika ralat), jadi jangan hanya melihat kod status.

1.5 Idempotensi

Membina suara (termasuk "bina daripada audio sedia ada") benar-benar idempotent: di bawah kunci yang sama, menghantar semula client_request_id yang sama hanya membina satu suara dan percubaan kedua terus memulangkan hasil pertama (success=true, voice_id yang sama). Pola penggunaannya: klien menjana id sendiri (contohnya UUID) dan menggunakan semula nilai yang sama apabila mencuba semula selepas tamat masa.

Penghantaran kover tidak menyahduplikasi pada peringkat permintaan (ini penjanaan berbayar), jadi perhatikan dua perkara:

1. Pengecam penghantaran berada dalam pengepala X-Create-Ui-Client-Request-Id: <id penghantaran anda>. Ia ditulis ke rekod tugasan di pihak pelayan untuk memudahkan siasatan kemudian; ia tidak menghalang caj berganda.
2. Tamat masa ≠ gagal: permintaan mungkin sudah diterima dan sedang dijana. Sebelum mencuba semula, semak dengan GET /api/music/songs?p=1&page_size=20 (parameter penomboran ialah p / page_size; ejaan serasi ps juga berfungsi) sama ada lagu baharu dengan generation_type=voice_profile_cover sudah muncul, dan hantar semula permintaan yang sama hanya jika belum ada.

Badan create dan create-from-clip juga menerima medan client_request_id (lihat §3 dan §4).

1.6 Gambaran keseluruhan pengebilan

Harga boleh dibaca bila-bila masa dari endpoint awam, jadi jangan tetapkan nilai tetap (lihat §9):

curl -sS https://www.suno-api.io/api/pricing/catalog | jq '.data.catalog.meta'
# {
#   "generation_price": "0.6",
#   "voice_generation_price": "1.2",      ← harga asas kover dengan suara
#   "max_mode_factor": "2",
#   "enhanced_upload_price": "10",        ← harga klon diperkukuh
#   "voice_auto_verify_price": "5",
#   "voice_long_term_clone_price": "5"
# }

Kover menggunakan pola potong dahulu + pulangkan jika gagal:

• Permintaan yang ditolak (parameter salah, 4xx/5xx platform, baki sendiri tidak cukup) tidak dicaj — apabila dihantar dengan suara yang tidak wujud, baki tidak berubah langsung dalam pengukuran kami (delta = 0);
• Tugasan yang diterima tetapi akhirnya gagal (termasuk gangguan perkhidmatan platform) melalui laluan pemulangan di pihak pelayan dan memulangkan jumlah yang dipotong dahulu.

1.7 Kamus status

status suara:

status lagu (nilai yang dipulangkan endpoint pertanyaan):

2. Gambaran keseluruhan endpoint

3. Membina suara

POST /api/music/voice-profile/create

Daftarkan satu keratan audio vokal sebagai "suara" dan dapatkan voice_id. Bagi platform, suara hanyalah "satu audio + clip-nya dalam katalog", jadi selepas berjaya dibina audio sumber itu disimpan secara kekal (untuk kover seterusnya).

3.1 Tiga bentuk input (pilih satu)

Bentuk A: muat naik fail multipart (disyorkan)

Content-Type: multipart/form-data

file=<binari audio>          # wajib
title=<nama suara>           # pilihan; jika kosong guna nama fail tanpa sambungan
file_name=<nama fail asal>
source_file_name=<nama fail asal>
source_kind=upload|record    # pilihan, penanda sumber (muat naik / rakaman); lalai upload
enhanced=false|true          # pilihan, true = klon diperkukuh (lihat §3.5)
client_request_id=<kunci idempotensi>   # pilihan
voice_id=<ID sendiri>        # pilihan, jarang digunakan

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3;type=audio/mpeg" \
  -F "file_name=my-voice.mp3" \
  -F "source_file_name=my-voice.mp3" \
  -F "title=Suara saya" \
  -F "source_kind=upload"

Bentuk B: JSON + URL audio awam

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "file_url": "https://your-cdn.example.com/voice/my-voice.mp3",
        "file_name": "my-voice.mp3",
        "title": "Suara saya"
      }'

• URL mesti pautan terus HTTPS yang boleh diakses awam; pelayan memuat turunnya sekali dan memindahkannya ke storan objek kami.
• Alamat boleh diletakkan dalam medan audio_url, kesannya sama (jika kedua-duanya dihantar, file_url diutamakan).
• Jika alamat sudah berada dalam storan objek platform ini (*.myqcloud.com/create-ui/voice-source/...), ia tidak dimuat turun semula: didaftarkan terus.

Bentuk C: JSON + base64

{
  "file_base64": "data:audio/mpeg;base64,//uQxAAA…",
  "file_name": "my-voice.mp3",
  "title": "Suara saya"
}

• Menyokong awalan data:audio/xxx;base64, dan base64 tulen.
• Saiz terhad (base64 membesar 1.33×), untuk fail besar gunakan bentuk A.

3.2 Keperluan audio

3.3 Respons

{
  "success": true,
  "message": "",
  "data": {
    "voice_id": "vp_20260926080618509168500DXXrxe",
    "clip_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "song_id": "91cc5935-389f-4193-b56b-cc796c15562d",
    "account_id": "acc_1790085275308",
    "title": "Suara saya",
    "source_file_name": "my-voice.mp3",
    "audio_url": "https://suno-api-p-1437223057.cos.ap-guangzhou.myqcloud.com/create-ui/voice-source/2026/09/26/xxx.mp3",
    "image_url": "https://cdn2.suno.ai/image_91cc5935-389f-4193-b56b-cc796c15562d.jpeg",
    "duration_s": 29.18,
    "enhanced": false,
    "source_kind": "upload",
    "status": "ready",
    "client_request_id": "",
    "created_at": 1790409978,
    "updated_at": 1790409998
  }
}

Penjelasan medan (create / list / detail berkongsi set medan yang sama):

created_at / updated_at ialah cap masa peringkat saat (10 digit), bukan milisaat.

3.4 Ralat biasa

3.5 Klon diperkukuh (enhanced=true)

Untuk kes "sampel suara sendiri mengandungi lirik berhak cipta / perlu muat naik diperkukuh". Harga mengikut harga muat naik diperkukuh (lalai 10 ¥ setiap panggilan, gagal dipulangkan secara automatik):

• Respons terus status=processing + task_id (belum ada clip_id) dan berjalan secara tak segerak;
• Semasa diproses, pantau dengan GET /api/music/voice-profile/{voice_id} yang memulangkan progress_percent / progress_stage / progress_message;
• Selepas siap status menjadi ready dan clip_id, audio_url, image_url dilengkapkan;
• Jika gagal status=failed dan error_message berbunyi kira-kira "muat naik diperkukuh gagal; caj telah dipulangkan secara automatik, cuba lagi kemudian";
• Klon diperkukuh jauh lebih lama daripada pembinaan biasa (minit), jadi jangan menunggunya dengan logik tamat masa segerak.

curl -sS -X POST "https://www.suno-api.io/api/music/voice-profile/create" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./my-voice.mp3" -F "title=Suara saya" -F "enhanced=true"

4. Membina suara daripada audio sedia ada

Jika tidak mahu muat naik semula: salin terus audio yang sudah anda muat naik atau sudah anda jana menjadi suara. Percuma dan idempotent.

POST /api/music/voice-profile/create-from-clip
Content-Type: application/json

{
  "source_song_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
  "title": "Xu Qing Qiang",
  "client_request_id": "vp-clip-1789…"
}

• source_song_id: clip id audio yang sudah siap dalam akaun anda (sama dengan song_id lagu).
• Menghantar clip yang sama berulang kali tidak mencipta rekod baharu: suara sedia ada terus dipulangkan dengan reused: true (diukur).

Respons ialah semua medan dalam §3.3 serta dua medan baca sahaja:

{
  "success": true,
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "title": "Xu Qing Qiang",
    "status": "ready",
    "enhanced": true,
    "reused": true,
    "source_type": "enhanced_upload"
  }
}

Ralat (message seperti dipulangkan; elok dipaparkan atau disetempatkan):

5. Senarai / butiran / padam suara

5.1 Senarai

GET /api/music/voice-profile/list
GET /api/music/voice-profile/list?include_deleted=true

{
  "success": true,
  "message": "",
  "data": {
    "items": [ { "voice_id": "vp_…", "title": "Suara saya", "status": "ready", "audio_url": "…", "image_url": "…" } ],
    "total": 1
  }
}

Medannya betul-betul seperti §3.3. Suara yang dipadam tidak dipulangkan secara lalai.

5.2 Butiran

GET /api/music/voice-profile/{voice_id}

Memulangkan satu objek suara (data ialah objek itu sendiri, bukan tatasusunan). Semasa klon diperkukuh berjalan, ada tambahan:

5.3 Padam

POST /api/music/voice-profile/delete
Content-Type: application/json

{ "voice_id": "vp_2026…" }

{ "success": true, "message": "", "data": { "voice_id": "vp_2026…", "status": "deleted" } }

• Selepas dipadam, suara hilang daripada senarai dan tidak boleh digunakan untuk kover baharu: menghantar dengan voice_id itu memulangkan 400 (lihat §6.4).
• Lagu yang sudah dijana dengannya tidak terjejas sama sekali; main balik, muat turun, sambungan, penggantian dan pemisahan berfungsi seperti biasa.
• Memadam suara yang tidak wujud, atau yang bukan milik akaun ini, memulangkan {"success":false,"message":"voice not found"}.

6. Kover dengan suara (endpoint teras)

POST /api/music/voice-profile/cover
Content-Type: application/json

Satu penghantaran menjana 2 lagu (sama seperti penjanaan biasa).

6.1 Dua senario

resolved_scene dalam respons menggemakan cover atau sing, supaya anda boleh mengesahkan laluan yang digunakan.

6.2 Medan permintaan

Elok juga sertakan pengepala X-Create-Ui-Client-Request-Id: <id penghantaran yang sama>: hanya itu ditulis ke rekod tugasan pihak pelayan dan menjadi kunci utama siasatan kemudian (lihat §1.5).

Perhatikan unit: audio_weight / style_weight / weirdness_constraint ialah perpuluhan 0–1, variety ialah integer 0–4, duration dalam saat. Tersalah guna akan ditolak atau hasilnya pelik.

Lirik pilihan pada senario B (model menguruskannya sendiri), tetapi hantar lyrics apabila kandungan tertentu perlu dinyanyikan.

6.3 Respons

{
  "code": 200,
  "message": "success",
  "data": {
    "voice_id": "vp_20260926081712557959800Z5gvlt",
    "voice_clip_id": "97ee62fe-56cd-473f-a2f5-c66ac0766a2e",
    "song_clip_id": "5b773e9a-a035-4134-a4a4-29c9961d3ccb",
    "resolved_scene": "cover",
    "model": "suno-v6",
    "audio_weight": 0.85,
    "clips": [
      {
        "song_id": "0f2a…",
        "status": "processing",
        "song_title": "",
        "model_version": "suno-v6",
        "audio_url": "",
        "play_url": "https://media.suno-api.io/play/0f2a…?expires=…&signature=…",
        "lyrics": "",
        "description": "[Tugasan] Ini satu kover. … (bahagian struktur tetap pelayan + keperluan kover / gaya yang anda isi)"
      },
      {
        "song_id": "7c91…",
        "status": "processing",
        "model_version": "suno-v6",
        "audio_url": ""
      }
    ],
    "source_updates": []
  }
}

Poin penting:

1. Kenal pasti hasil siap melalui clips[].song_id (endpoint ini tidak memulangkan medan id).
2. Anda terus mendapat 2 nilai song_id, sementara status masih processing (hanya bermakna telah diterima) dan audio_url kosong; mesti tinjau sehingga completed sebelum memuat turun. play_url ialah strim pratonton platform, mungkin muncul sejak peringkat penghantaran dan akan luput.
3. description ialah prompt yang akhirnya dihantar pelayan (bahagian struktur tetap + cover_requirements / style_requirements yang anda isi); sangat berguna semasa menyiasat hasil.
4. source_updates ialah hasil pemprosesan bahan di pihak pelayan dan boleh diabaikan klien.
5. title yang anda hantar ditulis ke rekod tugasan pihak pelayan dan muncul sebagai song_title pada pertanyaan seterusnya; clips[].song_title yang kosong dalam respons penghantaran adalah normal.

6.4 Ralat

{ "error": { "message": "suara ini tidak wujud atau telah dipadam (voice_id=vp_xxx)…", "type": "new_api_error", "param": "", "code": "invalid_request" } }

Baki tidak mencukupi terus memulangkan ralat pengebilan pada peringkat penghantaran dan tidak meninggalkan tugasan separuh siap.

6.5 Model yang tersedia (nama untuk pelanggan)

Gunakan nama model untuk pelanggan (yang di atas). chirp-* ialah nama dalaman platform dan tidak boleh digunakan terus.

7. Memantau kemajuan

7.1 Pertanyaan pukal (disyorkan)

POST /api/music/query
Content-Type: application/json

{ "model": "suno-v6", "song_ids": "id1,id2" }

• song_ids ialah rentetan dipisah koma (bukan tatasusunan).
• Responsnya tatasusunan kosong pembalut (terus [...], tiada pembalut success / data):

[
  {
    "song_id": "0f2a…",
    "song_title": "Dua Harimau",
    "status": "completed",
    "audio_url": "https://suno-api-hk-1437223057.cos.ap-hongkong.myqcloud.com/assets/0f2a…-mp3.mp3",
    "cover_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "duration": 115.15,
    "model_version": "suno-v6",
    "generation_type": "voice_profile_cover",
    "play_url": "https://media.suno-api.io/play/…?expires=…&signature=…",
    "lyrics": "[Verse 1]…",
    "prompt": "[Verse 1]…",
    "description": "[Tugasan] Ini satu kover. … (prompt akhir pelayan)",
    "style_tags": "…",
    "created_at": "2026-09-25T18:19:09.918Z",
    "video_url": ""
  }
]

Saranan tinjauan: setiap 5–10 saat, jumlah tamat masa 10–15 minit (akaun "sejuk" paling lambat diukur sekitar 4 minit setengah; sangat sedikit lebih lama). Jangan nilai siap daripada audio_url kosong, gunakan status.

Nota keserasian: endpoint ini mengenal pasti lagu melalui song_id; pada beberapa respons awal muncul medan id, jadi row.song_id || row.id ialah cara baca yang selamat.

7.2 Butiran satu lagu

GET /api/music/songs/{song_id}

{
  "success": true,
  "data": {
    "song_id": "0f2a…",
    "title": "Dua Harimau",
    "status": "completed",
    "generation_type": "voice_profile_cover",
    "model": "suno-v6",
    "duration": 115.15,
    "audio_url": "https://…/assets/0f2a…-mp3.mp3",
    "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
    "wav_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=wav",
    "video_url": "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=video",
    "created_at": 1790411012,
    "completed_at": 1790411500,
    "parameters": {
      "prompt": "[Verse 1]…",
      "style_tags": "…",
      "title": "Dua Harimau",
      "model": "suno-v6",
      "generation_type": "voice_profile_cover",
      "source_song_id": "5b773e9a-…"
    },
    "parameter_retention": {
      "core_parameters_available": true,
      "extended_parameters_available": false,
      "sources": ["suno_tasks"],
      "unavailable_fields": ["negative_tags", "vocal_gender", "style_weight", "weirdness_constraint"]
    }
  }
}

• Di sini created_at / completed_at ialah saat Unix (berbeza daripada rentetan ISO pada pertanyaan pukal, klien perlu membezakannya).
• wav_url / video_url ialah pintu muat turun platform ini (relatif kepada domain semasa) dan GET mengambil failnya; menjadi rentetan kosong apabila platform belum menghasilkan bahan itu.
• parameter_retention memberitahu parameter penghantaran yang masih boleh dijejaki: core_parameters_available=true bermaksud parameter teras (lirik / gaya / sumber) boleh ditanya, manakala dengan extended_parameters_available=false parameter lanjutan di atas tidak disimpan (kover dengan suara kini dalam kategori ini).

7.3 Karya saya

GET /api/music/songs?p=1&page_size=20
GET /api/music/songs?status=completed&q=kata kunci

Parameter penomboran: p (nombor halaman, mula dari 1) / page_size (bilangan setiap halaman; ejaan serasi ps). Pilihan status dan q (kata kunci tajuk). Lalai susunan masa cipta menurun.

{
  "success": true,
  "data": {
    "page": 1,
    "page_size": 20,
    "total": 42,
    "items": [
      {
        "song_id": "0f2a…",
        "title": "Dua Harimau",
        "status": "completed",
        "generation_type": "voice_profile_cover",
        "model": "suno-v6",
        "duration": 115.15,
        "audio_url": "https://…/assets/0f2a…-mp3.mp3",
        "image_url": "https://cdn2.suno.ai/image_0f2a….jpeg",
        "created_at": 1790411012,
        "completed_at": 1790411500
      }
    ]
  }
}

Dengan generation_type=voice_profile_cover anda boleh membezakan "lagu daripada kover dengan suara" daripada hasil penjanaan lain.

8. Memuat turun hasil siap

8.1 Ambil mp3 terus (disyorkan, percuma)

Ketiga-tiganya boleh; pilih satu:

1. Guna audio_url daripada hasil pertanyaan (pautan terus ke storan objek, paling mudah).
2. GET /api/music/download?song_id=<id>&kind=mp3 → terus memulangkan strim bait audio (nama fail sudah ada dalam Content-Disposition).
3. POST /api/music/download-url (untuk alamat sementara bertandatangan).

curl -sS -L "https://www.suno-api.io/api/music/download?song_id=0f2a…&kind=mp3" \
  -H "Authorization: Bearer $API_KEY" -o song.mp3

Nilai kind: mp3 (sama seperti song) / playback (main strim) / wav / video / lyrics / timestamped_lyrics. timestamped_lyrics (.lrc) kini hanya untuk sebahagian lagu; jika gagal, bina failnya sendiri dengan API lirik bermarka masa. Responsnya ialah strim bait fail, Content-Type dan Content-Disposition (nama fail) sudah ditetapkan; wav_url / video_url yang dipulangkan GET /api/music/songs/{song_id} ialah pintu yang sama dengan kind=wav|video.

8.2 Tukar ke wav / lirik / metadata (berbayar)

POST /api/music/free2
Content-Type: application/json

{ "song_ids": ["0f2a…"], "files": ["mp3", "wav", "lyrics"] }

{
  "success": true,
  "data": {
    "songs": [
      { "song_id": "0f2a…", "files": [ { "type": "mp3", "url": "https://…" }, { "type": "wav", "url": "https://…" } ] }
    ],
    "requested_songs": 1,
    "succeeded_songs": 1,
    "price": 0.2
  }
}

• files menerima: mp3 / wav / lyrics / metadata, maksimum 10 lagu sekali.
• Dicaj mengikut bilangan lagu yang berjaya (0.2 ¥ setiap satu); lagu yang gagal sepenuhnya tidak dicaj, dan format yang gagal hanya muncul dalam songs[].errors.
• Untuk mengambil semula fail yang pernah dimuat turun, gunakan dahulu yang percuma POST /api/music/free2/cached (dengan song_ids + files yang sama) untuk alamat arkib; songs[].missing_files dalam responsnya menyenaraikan format yang tiada dalam cache dan perlu disediakan semula.

9. Pertanyaan harga

GET /api/pricing/catalog

Endpoint awam tanpa pengesahan. Semua harga seunit yang perlu dipaparkan kepada pelanggan ada dalam data.catalog.meta (rentetan):

Harga dilaraskan dalam back-office, jadi baca secara masa nyata dan jangan tetapkan dalam klien. Caj sebenar kover = voice_generation_price × (jika max_mode benar, darab lagi max_mode_factor).

10. Had dan peringatan

1. Saiz muat naik: ≤ 10 MB (pelayan menerima lebih banyak, tetapi get masuk memotong badan yang terlalu besar pada 10 MiB dan kelihatan seperti "ditolak Suno"; sekat di pihak anda dahulu).
2. Tempoh sampel: sekurang-kurangnya 6 saat, 10–60 saat disyorkan; terlalu pendek akan ditolak platform.
3. Kandungan sampel: vokal bersih; elakkan apa-apa yang sangat menyerupai rakaman sedia ada (padanan katalog akan menolaknya).
4. Had teks: lyrics ≤ 3000 aksara; style_requirements / negative_tags / title elok dalam 1000 / 1000 / 100 aksara (keperluan gaya dan kover digabungkan ke prompt, pastikan jumlahnya bawah 3000 aksara).
5. Lirik tidak ditulis semula: apa yang dihantar itulah yang dinyanyikan (aksara demi aksara), tanpa pemotongan setempat.
6. Setiap lagu menghasilkan 2 trek; jangan andaikan satu hasil.
7. Audio sumber disimpan secara kekal: memadam suara tidak membersihkan audio sumbernya; ini memastikan kover seterusnya masih boleh dan pematuhan boleh dijejaki.
8. Suara mesti ready: suara berstatus processing tidak boleh digunakan untuk kover.
9. Tamat masa permintaan: pada akaun "sejuk" penghantaran pertama diukur sehingga sekitar 4 minit setengah, jadi tetapkan tamat masa klien ≥ 6 minit. Kover tidak menyahduplikasi pada peringkat permintaan, jadi selepas tamat masa semak sama ada lagu baharu sudah muncul (§1.5) sebelum memutuskan hantar semula.
10. Pemilikan suara: suara milik penciptanya; kover hanya menerima suara yang sedia dan belum dipadam. Suara yang tidak wujud, telah dipadam, atau milik akaun lain memulangkan 400: suara ini tidak wujud atau telah dipadam (voice_id=…).

11. Soalan lazim (FAQ)

S1. Adakah membina suara berbayar? Pembinaan biasa dan "bina daripada audio sedia ada" adalah percuma; hanya kover (1.2 ¥ / MAX 2.4 ¥) dan klon diperkukuh (lalai 10 ¥) yang berbayar.

S2. Bolehkah menggunakan lagu siap beriringan muzik sebagai sampel suara? Tidak disyorkan. Apa-apa yang mengandungi muzik, atau sangat menyerupai rakaman sedia ada dalam katalog, akan ditolak platform (This audio matches an existing recording in our catalog.). Guna rakaman vokal tulen yang kering.

S3. Mengapa audio_url kosong selepas menghantar kover? Penghantaran hanya bermakna telah diterima dan status masih processing. Alamat yang boleh dimain/dimuat turun muncul selepas anda meninjau /api/music/query sehingga status=completed.

S4. Perlu hantar lirik pada senario B (tanpa song_clip_id)? Pilihan. Hantar lyrics untuk menyanyikan kandungan tertentu; tanpanya model menguruskannya sendiri tetapi kawalan berkurang.

S5. Bolehkah audio yang dimuat naik pelanggan terus menjadi suara? Boleh: melalui bentuk file_url pada create, atau memuat naiknya sebagai lagu dahulu lalu memanggil create-from-clip.

S6. Adakah wang dipulangkan jika gagal? Permintaan yang ditolak terus (parameter salah / ralat platform) tidak dicaj, menurut pengukuran; tugasan yang diterima tetapi akhirnya gagal memulangkan jumlah yang dipotong dahulu. Pada kegagalan akhir, tugasan melaporkan status=failed serta error_message.

S7. Selepas memadam suara, bolehkah lagu yang pernah dijana dengannya masih didengar? Boleh. Pemadaman hanya memengaruhi sama ada suara itu boleh digunakan untuk kover baharu.

S8. Berapa panjang lagu yang boleh dikover sekali? duration menerima 1–480 saat; jika tidak dihantar platform menentukan daripada lagu asal / bahan. Perhatikan: trek siap platform sekurang-kurangnya sekitar 30 saat; dengan nilai lebih kecil, pengukuran tetap memberi 29.96 / 29.76 saat.

Lampiran A: contoh lengkap (Node.js, dengan tinjauan dan muat turun)

const BASE = "https://www.suno-api.io";
const KEY = process.env.SUNO_API_KEY;
const H = { Authorization: `Bearer ${KEY}` };

// ① Bina suara (multipart)
async function createVoice(filePath, title) {
  const fd = new FormData();
  fd.set("file", new Blob([await (await import("node:fs/promises")).readFile(filePath)], { type: "audio/mpeg" }), "my-voice.mp3");
  fd.set("file_name", "my-voice.mp3");
  fd.set("source_file_name", "my-voice.mp3");
  fd.set("title", title);
  fd.set("client_request_id", `vp-create-${Date.now()}`);
  const res = await fetch(`${BASE}/api/music/voice-profile/create`, { method: "POST", headers: H, body: fd });
  const body = await res.json();
  if (!body.success) throw new Error(body.message);
  return body.data; // { voice_id, status, audio_url, ... }
}

// ② Kover
async function cover(voiceId, songClipId, lyrics) {
  const submissionId = `vp-cover-${Date.now()}`;
  const res = await fetch(`${BASE}/api/music/voice-profile/cover`, {
    method: "POST",
    headers: { ...H, "Content-Type": "application/json", "X-Create-Ui-Client-Request-Id": submissionId },
    body: JSON.stringify({
      model: "suno-v6",
      voice_id: voiceId,
      song_clip_id: songClipId || "",
      lyrics: lyrics || "",
      style_requirements: "folk perlahan, gitar akustik",
      audio_weight: 0.85,
      max_mode: false,
      client_request_id: submissionId,
    }),
  });
  const body = await res.json();
  if (body.error) throw new Error(body.error.message);
  return body.data; // { resolved_scene, clips: [{ song_id, status }] }
}

// ③ Tinjau sehingga siap (setiap 5 saat, maksimum 15 minit)
async function waitUntilCompleted(songIds) {
  const deadline = Date.now() + 15 * 60 * 1000;
  while (Date.now() < deadline) {
    const res = await fetch(`${BASE}/api/music/query`, {
      method: "POST",
      headers: { ...H, "Content-Type": "application/json" },
      body: JSON.stringify({ model: "suno-v6", song_ids: songIds.join(",") }),
    });
    const songs = await res.json(); // tatasusunan telanjang
    if (songs.every((s) => s.status === "completed" || s.status === "failed")) return songs;
    await new Promise((r) => setTimeout(r, 5000));
  }
  throw new Error("timeout waiting for cover");
}

// ④ Muat turun
async function download(songId, outPath) {
  const res = await fetch(`${BASE}/api/music/download?song_id=${encodeURIComponent(songId)}&kind=mp3`, { headers: H });
  if (!res.ok) throw new Error(`download failed: ${res.status}`);
  (await import("node:fs/promises")).writeFile(outPath, Buffer.from(await res.arrayBuffer()));
}

const voice = await createVoice("./my-voice.mp3", "Suara saya");
const result = await cover(voice.voice_id, "5b773e9a-a035-4134-a4a4-29c9961d3ccb", "[Verse 1]\nlirik…");
const ids = result.clips.map((c) => c.song_id);
const songs = await waitUntilCompleted(ids);
for (const [i, s] of songs.entries()) {
  if (s.status === "completed") await download(s.song_id, `./out-${i}.mp3`);
}

Lampiran B: log perubahan