API muat naik lalu cover sekali gus

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

Penerangan endpoint

Muat naik lalu cover sekali gus menghantar fail audio atau URL audio dan menjana versi cover baharu daripada audio sumber itu.

Endpoint: POST /api/music/upload-cover

Pengebilan: Berbayar, kini lalai 0.6 ¥ setiap panggilan. Endpoint ini ialah "muat naik lalu cover", bukan memuat naik kulit album imej. Jumlah yang benar-benar dicaj mengikut tetapan harga semasa dalam back-office.

Max Mode / Variety: endpoint ini menyokong parameter pilihan max_mode dan variety (0-4). Dengan max_mode dihidupkan, panggilan ini dibilkan pada 2× harga (0.6 → 1.2 ¥ setiap panggilan); variety tidak menambah kos. Maksud dan cara menghantarnya ada dalam bahagian "Parameter lanjutan" pada Gambaran keseluruhan API baharu.

Masa menunggu dan timeout (penting): ini endpoint segerak — pesanan hanya diterima dan dihantar ke penjanaan apabila respons tiba. Berdasarkan ukuran, kebanyakan permintaan membalas dalam 1-3 saat, kira-kira 10% melebihi 30 saat dan paling lama sekitar 230 saat. Tetapkan timeout klien kepada 300 saat atau lebih; tiada respons tidak bermakna tiada apa-apa dijana, dan jangan cuba semula sejurus selepas timeout (ia menggandakan pesanan dan mencaj dua kali). Jika sambungan terputus, periksa kemudian dengan GET /api/music/songs. Lihat "Masa menunggu dan tetapan timeout" dalam Gambaran keseluruhan API baharu.

Apabila audio besar, lebih baik pisahkan "muat naik" dan "cover" kepada dua langkah (disyorkan)

Endpoint ini memerlukan keseluruhan audio dimasukkan ke dalam badan permintaan: semakin besar audio, semakin besar badan, dan satu gangguan rangkaian atau timeout memotong pemindahan di pertengahan, selepas itu pelayan memulangkan unexpected end of JSON input (HTTP 400, tiada caj).

Apabila audio melebihi kira-kira 8 MB, rangkaian tidak stabil, atau bahan sumber yang sama akan diguna semula, tukar kepada bentuk dua langkah:

1. POST /api/music/upload-source memuat naik audio sumber dahulu — percuma, boleh cuba semula bila-bila masa — dan memberikan clip_id;
2. POST /api/music/generate-from-source memulakan cover dengan clip_id itu — badan permintaan langkah bercaj hanya kira-kira 250 bait.

Lihat API muat naik audio sumber, API cover daripada klip sumber, dan "Fail besar dan permintaan terpotong" di hujung halaman ini.

Parameter permintaan

Headers

Parameter body

cover_start_s dan cover_end_s dalam unit saat dan boleh perpuluhan; masa mula mesti lebih kecil daripada masa tamat dan tidak boleh melebihi tempoh audio sumber. Jika kedua-dua medan ditinggalkan, keseluruhan audio digunakan. audio_weight dipetakan kepada metadata.control_sliders.audio_weight Suno dan mengawal sejauh mana hasil bersandar pada audio rujukan; nilainya 0.0-1.0 dan hanya boleh disertakan apabila permintaan membawa audio rujukan yang sah dalam file_url atau file_base64. 0 ialah nilai yang sah; meninggalkan medan bermaksud "tidak dinyatakan" dan mengekalkan tingkah laku lalai Suno. instrumental dan waitAudio mesti boolean JSON, bukan rentetan.

Endpoint muat naik membalas secara tak segerak secara lalai. Selagi clips[].status dalam respons ialah pending, audio_url yang kosong adalah normal dan bukan bermakna muat naik atau cover gagal; simpan song_id sebenar yang dipulangkan dan panggil endpoint carian lagu sehingga selesai sebelum membaca alamat audio.

Contoh permintaan

curl -X POST https://www.suno-api.io/api/music/upload-cover \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "suno-v6",
    "file_url": "https://example.com/source.mp3",
    "file_name": "source.mp3",
    "prompt": "Lirik baharu atau arah adaptasi",
    "style": "Mandopop, acoustic guitar",
    "title": "Versi cover",
    "negativeTags": "noise, low quality",
    "audio_weight": 0.5,
    "instrumental": false,
    "waitAudio": false,
    "cover_start_s": 0,
    "cover_end_s": 60
  }'

Respons

{
  "code": 200,
  "message": "success",
  "data": {
    "upload": {
      "clip_id": "uploaded_clip_id",
      "status": "complete"
    },
    "clips": [
      {
        "song_id": "new_clip_id",
        "song_title": "Versi cover",
        "status": "pending"
      }
    ]
  }
}

Fail besar dan permintaan terpotong

Disyorkan: pisahkan muat naik dan cover kepada dua langkah

Endpoint sekali gus (yang ini) menggabungkan muat naik dan penjanaan dalam satu langkah: badan besar berada dalam satu-satunya langkah itu, jadi apabila ia terputus anda tidak tahu sama ada ada yang dijana mahupun sama ada dicaj.

Kesimpulan: audio melebihi kira-kira 8 MB, rangkaian tidak stabil, atau bahan yang sama digunakan beberapa kali → guna bentuk dua langkah; audio sangat kecil pada rangkaian stabil → endpoint ini lebih mudah.

Apa maksud 400 unexpected end of JSON input

Maksudnya JSON yang diterima pelayan tidak lengkap (bukan parameter salah, bukan masalah kebenaran atau baki). Punca biasa, disusun mengikut kebarangkalian:

1. Badan besar terpotong di pertengahan pemindahan: lapisan masuk merekodkan kedua-dua "berapa bait yang diisytiharkan klien" dan "berapa bait yang benar-benar tiba". Kes berukuran: klien mengisytiharkan 14.17 MB tetapi hanya 11.8–12.4 MB tiba, dan ketiga-tiga permintaan berhenti pada sekitar 1.6–1.7 saat; bilangan bait yang hilang berbeza setiap kali, menandakan pemindahan terputus dan bukan had tetap (pelayan tidak mengehadkan saiz badan permintaan).
2. Content-Length tidak sepadan dengan bait yang benar-benar dihantar: dalam Node.js, menggunakan .length rentetan (bilangan aksara UTF-16) sebagai panjang akan tersalah kira apabila kandungannya mengandungi bahasa Cina atau teks berbilang bait yang lain.
3. Menulis badan sebagai rentetan dan bukan Buffer, jadi bait yang ditulis tidak sepadan dengan yang diisytiharkan.

Kejadian ketiga-tiganya berlaku sebelum pengebilan, jadi tiada kos timbul.

Senarai semak kendiri di sisi klien

• Content-Length diperoleh daripada Buffer.byteLength(json, 'utf8') (atau Buffer.from(json).length) — jangan guna json.length;
• Badan permintaan ditulis sebagai Buffer, bukan rentetan;
• Timeout soket / permintaan ≥ 300 saat;
• Apabila audio melebihi kira-kira 8 MB: guna file_url (badan hanya beberapa ratus bait), atau muat naik multipart daripada upload-source, atau terus ke bentuk dua langkah;
• Pada permintaan multipart, jangan tetapkan Content-Type sendiri (biarkan klien menambah boundary);
• Cetak "bait yang benar-benar dihantar" dan bandingkan dengan Content-Length;
• Dalam bentuk dua langkah, pastikan langkah 1 memulangkan clip_id dengan status selesai sebelum menghantar langkah 2.

Kesalahan lazim

Endpoint berkaitan: API muat naik audio sumber (langkah 1), API cover daripada klip sumber (langkah 2).