Gambaran keseluruhan dokumentasi Suno API

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

Daftar dengan alamat e-mel dan anda sudah boleh mencipta kunci API. Satu penjanaan berharga 0.6 ¥, menghasilkan 2 lagu, dan merangkumi muat turun MP3/WAV, lagu cover, Extend, pemisahan stem serta klon suara. URL asas: https://www.suno-api.io.

Halaman ini menyenaraikan model yang tersedia sekarang, semua endpoint penjanaan dan penyuntingan, cara pengebilan, dan susunan bacaan yang disyorkan. Jika anda baru pertama kali berintegrasi, bacalah dari atas ke bawah; bahagian penyelesaian masalah 401/403/429 juga ada di sini.

Jawapan ringkas

Bagaimana saya mendapat kunci API? Daftar dengan alamat e-mel, buka konsol, pergi ke pengurusan token dan cipta satu token. Tiada nombor telefon dan tiada kad bank diperlukan.

Berapa kos satu panggilan? Satu penjanaan berharga 0.6 ¥ dan menghasilkan 2 lagu. Pertanyaan status, WAV, lirik bertimestamp dan cadangan prompt adalah percuma.

Model mana yang disokong? suno-v6 (lalai), suno-v6-wild dan suno-v6-mini. Model penjanaan standard v5.5 dan lebih lama telah ditarik; kerja sedia ada tidak terjejas.

Apakah URL asasnya? https://www.suno-api.io, dengan pengepala Authorization: Bearer YOUR_API_KEY.

Model yang tersedia sekarang

Model untuk pelanggan bagi penjanaan lagu standard ialah suno-v6, suno-v6-wild dan suno-v6-mini. Jika model ditinggalkan, sistem menggunakan suno-v6.

Model standard suno-v2, suno-v3, suno-v3-5, suno-v4, suno-v4-5, suno-v4-5-all, suno-v4-5-plus, suno-v5 dan suno-v5-5 telah ditarik. Tugasan lama mungkin masih memaparkan nama-nama itu; itu data sejarah, bukan tanda model tersebut boleh dipakai untuk permintaan baharu. Pemisahan stem ialah pengecualian — lihat API pemisahan stem (pisah vokal/muzik).

Pengesahan

Setiap endpoint awam berkunci API menggunakan set pengepala yang sama:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

URL asas:

https://www.suno-api.io

Konvensyen parameter umum

• number dalam body mesti nombor JSON, bukan rentetan peratus. Keamatan 50% ditulis 0.5, tidak pernah 50 atau 50%.
• boolean mesti true atau false. Jangan gunakan 0 atau 1 sebagai ganti.
• Medan bertanda "tidak" boleh ditinggalkan sepenuhnya. Jika anda tidak pasti apa fungsi sesuatu parameter, biarkan kosong supaya perkhidmatan menggunakan gelagat lalainya; jangan hantar rentetan kosong, null atau 0 sebagai ganti "tidak dihantar", kerana 0 ialah nilai sah bagi sesetengah medan nombor.
• Nama medan sensitif pada ejaan. Setiap halaman endpoint menyenaraikan nama yang disyorkan dan alias yang serasi; hantar tepat seperti dalam jadual parameter. Di tempat dokumentasi menyatakan snake_case dan camelCase kedua-duanya diterima, jangan hantar kedua-duanya sekali gus.
• Setiap medan tempoh yang berakhir dengan _s atau Seconds diukur dalam saat dan menerima perpuluhan. Timestamp Unix dijelaskan secara berasingan, termasuk sama ada dalam saat atau milisaat.
• ID yang bermula dengan pending: ialah pemegang tempat platform, bukan song_id sebenar. Gunakannya hanya di tempat endpoint menyatakan sokongan pemegang tempat secara jelas; selain itu tunggu song_id sebenar.

Had medan teks

Melebihi had teks mengembalikan HTTP 400 terus: tiada apa-apa dijana, tiada caj pendahuluan dan tiada rekod tugasan dicipta. Pengiraan mengikut aksara Unicode (satu aksara Han dikira 1) dan ruang di hadapan/hujung turut dikira.

Medan message menyebut medan mana yang melanggar dan panjang yang diukur, jadi dua nombor itu sudah cukup untuk memendekkannya:

{
  "error": {
    "message": "style_tags must not exceed 1000 characters; received 2772",
    "type": "invalid_request_error"
  }
}

Terpakai kepada: /api/music/create, /api/music/create/custom, /api/music/extend, /api/music/upload-cover, /api/music/generate-from-source, /api/music/add-instrumental, /api/music/add-vocal, /api/music/add-stem, /api/music/mashup, /api/music/sample, /api/music/inspo, /api/music/crop, /api/music/remove-section, /api/music/fade, /api/music/reverse, /api/music/speed, /api/music/replace-section, /api/music/generate-with-voice.

Satu pengecualian: medan description bagi POST /api/music/sounds dihadkan kepada 100 aksara, kerana laluan kesan bunyi menggunakan had platform yang lebih pendek.

Penjanaan tak segerak dan alamat audio

Endpoint penjanaan muzik secara lalai berfungsi secara tak segerak. Apabila respons pertama membawa status bernilai pending, submitted atau processing, audio_url, video_url atau cover_url yang kosong adalah normal dan bukan tanda tugasan gagal. Simpan song_id sebenar (atau client_request_id yang dikembalikan endpoint) kemudian panggil endpoint pertanyaan yang sepadan; baca dan muat turun alamat audio hanya apabila status selesai.

⚠️ Alamat audio luput selepas 7 hari — pindahkan fail anda tepat pada masanya

audio_url, wav_url, video_url dan alamat yang dikembalikan endpoint muat turun disajikan daripada storan objek platform dan luput selepas 7 hari secara lalai (fail dikitar semula; alamat lama mengembalikan 404 / gagal dimuat turun).

• Dalam tempoh 7 hari itu, pindahkan fail ke storan anda sendiri (storan objek anda, CDN atau cakera pelayan). Jangan anggap alamat kami sebagai pautan berumur panjang.
• Alamat yang telah luput tidak memerlukan penjanaan semula lagu dan tiada kos tambahan: panggil semula API pertanyaan lagu (atau API muat turun media) untuk mendapatkan alamat baharu yang masih sah bagi lagu tersebut.

Masa menunggu dan tetapan timeout

Endpoint penjanaan bersifat segerak: pesanan hanya diterima dan diserahkan kepada platform untuk dijana apabila responsnya tiba. Sebelum itu, perkhidmatan perlu menjadualkan akaun dan melepasi pemeriksaan keselamatan yang diwajibkan, dan tiada respons pertengahan — tiada endpoint lain boleh melihat pesanan itu. Jadi satu-satunya bukti yang boleh dipercayai bahawa "sesuatu sudah dijana" ialah respons itu sendiri, bukan apa-apa yang anda perhatikan semasa menunggu.

Masa menunggu yang diukur (keluarga /api/music/create dalam production, 2026-09-18 hingga 2026-09-20)

• Kira-kira 10% permintaan mengambil masa lebih 30 saat dan kira-kira 1% mengambil 1–2 minit. Permintaan yang lambat biasanya bermakna permintaan itu perlu melepasi pemeriksaan keselamatan dahulu.
• Medan permintaan, bentuk respons, kod ralat dan pengebilan tidak berubah, jadi integrasi sedia ada hanya perlu menaikkan timeout klien — tiada perubahan kod lain.

Keperluan integrasi

1. Tetapkan timeout klien 300 saat atau lebih. Klien yang lalai 30, 60 atau 120 saat akan memutuskan sambungan semasa menunggu.
2. Tiada respons tidak bermakna tiada apa-apa dijana. Semasa timeout atau sambungan terputus, pesanan mungkin sudah diterima dan sedang dijana.
3. Jangan cuba semula sejurus selepas timeout: penghantaran berganda mencipta pesanan kedua dan mencaj lagi.
4. Jika sambungan terputus, senaraikan lagu anda dengan GET /api/music/songs (terbaharu dahulu) sebentar kemudian — pesanan yang telah diterima akan muncul seperti biasa. Hantar semula hanya selepas anda mengesahkan pesanan itu benar-benar tiada.
5. Semasa melaporkan masalah, sertakan pengepala respons X-Oneapi-Request-Id supaya permintaan itu boleh dikesan terus.

Tidak mahu memegang sambungan lama? Gunakan mod terima-resit. POST /api/music/create dan POST /api/music/create/custom menyokong resit terima secara pilihan: tambah "accept_mode": "async" ke dalam body (atau pengepala X-Accept-Mode: async) dan endpoint terus mengembalikan 202 bersama nombor resit sementara penjanaan berterusan di latar belakang; panggil GET /api/music/requests/{request_id} untuk memantau kemajuannya. Klien yang timeoutnya hanya beberapa puluh saat tidak lagi tersalah membaca "tiada respons" sebagai "tiada apa-apa dijana", dan tidak boleh dicaj dua kali akibat percubaan semula. Lihat "Mod terima-resit" dalam API penjanaan mod mudah.

Sebagai rujukan: python requests menggunakan timeout=300, urllib menggunakan urlopen(..., timeout=300), Node menggunakan req.setTimeout(300000), curl menggunakan --max-time 300.

Senarai endpoint yang disyorkan

/api/voice/clone/* dan /api/music/generate-with-voice ialah rantaian klon suara generasi awal dan tidak disyorkan untuk integrasi baharu; gunakan 【Disyorkan】 API profil suara sebaliknya.

Parameter lanjutan: Max Mode dan Variety

Endpoint penjanaan menyokong dua parameter pilihan ini (meninggalkannya mengekalkan gelagat dan harga sebelumnya):

Kedua-dua parameter ini disokong oleh: POST /api/music/create, POST /api/music/create/custom, POST /api/music/extend, POST /api/music/upload-cover, POST /api/music/generate-from-source, POST /api/music/add-instrumental, POST /api/music/add-vocal, POST /api/music/add-stem, POST /api/music/mashup, POST /api/music/sample, POST /api/music/inspo, POST /api/music/replace-section, POST /api/music/voice-profile/cover, POST /api/music/speech.

• Harga 2× dalam praktik: endpoint yang berharga 0.6 ¥ setiap panggilan menjadi 1.2 ¥ dengan max_mode; jana dengan suara pilihan berharga 1.2 ¥ setiap panggilan dan 2.4 ¥ dengan Max Mode; cover dengan suara bagi 【Disyorkan】 API profil suara juga 1.2 ¥ setiap panggilan (2.4 ¥ dengan max_mode).
• variety hanya terpakai kepada keluarga suno-v6 (suno-v6, suno-v6-wild, suno-v6-mini); menghantarnya bersama model lain mengembalikan 400.
• Kesan bunyi, pemisahan stem, concat, WAV dan tindakan penyuntingan Studio (crop, padam bahagian, fade, terbalikkan, ubah kelajuan dan sebagainya) tidak menerima kedua-dua parameter ini — menghantarnya secara jelas mengembalikan 400, supaya tiada parameter diabaikan secara senyap.
• variety ialah integer mentah 0-4; style_weight dan weirdness_constraint ialah perpuluhan dari 0 hingga 1, jadi skalanya berbeza.

Medan respons lagu yang biasa

Endpoint penjanaan, cover, extend, pemisahan dan pertanyaan biasanya mengembalikan tatasusunan lagu dengan medan berikut:

Empat langkah berintegrasi (contoh minimum yang berfungsi)

Lengkapkan keempat-empat langkah ini dan anda sudah ada lagu pertama; senarai medan penuh setiap langkah ada pada halaman yang sepadan dalam senarai endpoint yang disyorkan.

# 1) Hantar permintaan penjanaan: 0.6 ¥, menghasilkan 2 lagu
curl -X POST https://www.suno-api.io/api/music/create \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "bright Mandarin pop, piano intro, warm female vocal", "model": "suno-v6"}'

# 2) Polling tugasan sehingga status completed (selang 3-5 saat sudah sesuai)
curl -X POST https://www.suno-api.io/api/music/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id yang dikembalikan pada langkah 1"}'

# 3) Dapatkan alamat media: endpoint baca semuanya percuma; tersedia song / wav / video / cover / midi
curl -X POST https://www.suno-api.io/api/music/download-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"song_id": "song_id yang sama", "kind": "song"}'

Apabila berlaku masalah: 401 / 402 / 403 / 429 dibincangkan dalam rujukan ralat; timeout dan caj berganda dalam bahagian "Masa menunggu dan tetapan timeout" di atas; butiran setiap endpoint dalam senarai endpoint yang disyorkan di bawah.

Saranan

• Integrasi baharu sebaiknya menggunakan suno-v6 sepanjang aliran.
• Bagi endpoint yang menyebut harga lalai, jumlah yang benar-benar dibilkan mengikut konfigurasi harga back-office semasa dan model yang diminta.
• Endpoint penjanaan biasanya mengembalikan tugasan dahulu; baca audio akhirnya melalui /api/music/query.
• wait_completion=true menyekat sehingga selesai dan sesuai untuk ujian bervolume rendah; dalam production, polling lebih disyorkan.
• Endpoint penjanaan boleh mengambil masa yang sangat lama untuk membalas — tetapkan timeout klien 300 saat atau lebih, dan ingat bahawa "tiada respons" tidak sama dengan "tiada apa-apa dijana"; lihat "Masa menunggu dan tetapan timeout" di atas.
• Keupayaan muat naik, cover, replace dan WAV bergantung pada akaun platform dan kebenaran klip sumber; apabila gagal, baca dahulu message atau error_message yang dikembalikan.

Tentang dokumentasi ini

Halaman ini disusun semula mengikut keupayaan yang benar-benar dipaparkan Create UI, dan integrasi baharu sebaiknya membacanya dahulu. Dokumentasi API lama masih tersedia dalam bahagian "Dokumentasi API lama (serasi)" untuk pemanggil yang mahu terus menggunakannya.