API penjanaan mod tersuai

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

Penerangan endpoint

Mod tersuai sesuai apabila lirik, gaya dan tajuk sudah siap dan anda mahu mengawal suara yang menyanyi, kekuatan pengaruh gaya serta tahap kerawakan penjanaan.

Endpoint: POST /api/music/create/custom

Pengebilan: Berbayar, kini lalai 0.6 ¥ setiap panggilan. Setiap panggilan biasanya mengembalikan 2 lagu; 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.

Parameter permintaan

Headers

Parameter body

Nota parameter lanjutan

Jantina suara vocal_gender

• Hantar m atau male untuk suara lelaki, f atau female untuk suara perempuan.
• Perkhidmatan menormalkan male dan female kepada m dan f.
• Dengan instrumental=true, parameter jantina suara tidak dihantar kepada perkhidmatan penjanaan.

Pengaruh gaya style_weight

Mengawal sejauh mana hasil mengikut style_tags. Semakin tinggi nilainya, semakin hasil cenderung mengikut tag gaya yang anda berikan.

Kerawakan weirdness_constraint

Mengawal sebanyak mana hasil berubah dan bersifat eksperimen. Nilai tinggi biasanya memberi lebih banyak variasi; nilai rendah memberi hasil yang lebih selamat.

Kedua-dua parameter nombor berada dalam julat 0.0 hingga 1.0, dan 0 ialah nilai eksplisit yang sah. Hanya meninggalkan medan sepenuhnya yang bermaksud "tidak dinyatakan".

Semasa mengisinya, ambil perhatian bahawa ini pecahan perpuluhan, bukan integer peratus. Rujukan yang disyorkan: 0.0–0.3 konservatif, 0.4–0.6 seimbang, 0.7–1.0 lebih eksperimen; jika tiada keutamaan jelas gunakan 0.5 atau biarkan kosong. Contoh: weirdness_constraint: 0.5, jangan tulis 50 atau 50%.

Dengan instrumental=true, hasilnya instrumental jadi lirik dan jantina suara tidak berkesan seperti lagu bernyanyi; jika perlu vokal, hantar false atau tinggalkan medan itu. Medan boolean mesti menggunakan true/false JSON, bukan rentetan.

Contoh permintaan Python

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/create/custom',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'model': 'suno-v6',
        'lyrics': '[Verse]\nMalam turun di atas laut\nangin senja melintasi tingkap',
        'style_tags': 'Mandopop, acoustic guitar, warm vocal',
        'song_title': 'Angin senja di tepi laut',
        'vocal_gender': 'male',
        'style_weight': 0.68,
        'weirdness_constraint': 0.32,
    },
    timeout=300,
)
response.raise_for_status()
songs = response.json()

Mod resit penerimaan (pilihan)

Endpoint ini juga menyokong mod resit penerimaan daripada API penjanaan mod mudah: dengan "accept_mode": "async" dalam body (atau pengepala X-Accept-Mode: async), endpoint terus mengembalikan 202 dan nombor resit, penjanaan berterusan di latar belakang, dan anda memantau kemajuan dengan GET /api/music/requests/{request_id}.

Sesuai untuk klien yang tidak boleh memegang sambungan lama, atau yang tidak mahu timeout ditafsirkan sebagai "tiada apa-apa dijana". Tanpa parameter itu, kelakuannya sama seperti sebelum ini.

curl -X POST https://www.suno-api.io/api/music/create/custom \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "style_tags": "Mandopop, acoustic guitar, warm vocal",
    "song_title": "Angin senja di tepi laut",
    "vocal_gender": "male",
    "accept_mode": "async"
  }'

Bentuk respons dan cara tinjauan berkala ada dalam bahagian "Mod resit penerimaan" pada API penjanaan mod mudah.

Pengesahan parameter

Kes berikut mengembalikan HTTP 400, dan message ralat menyebut medan yang tidak sah:

• style_weight atau weirdness_constraint bukan nombor.
• Nilai nombor di bawah 0.0 atau melebihi 1.0.
• vocal_gender bukan salah satu daripada m, f, male, female.

Had medan teks

Medan berikut juga mengembalikan HTTP 400 apabila terlalu panjang, tidak masuk penjanaan dan tidak dicaj di hadapan. Pengiraan dalam aksara Unicode (satu aksara Han dikira 1) dan ruang di hujung hadapan turut dikira:

Mesej ralat berbentuk style_tags must not exceed 1000 characters; received 2772: perkataan pertama ialah nama medan yang melebihi dan di hujung ialah bilangan yang diukur, jadi apabila menerima 400 anda boleh memendekkan berdasarkan dua nombor itu tanpa mencuba medan satu demi satu. Peraturan umum ada dalam "Had medan teks" pada Gambaran keseluruhan API baharu.

Respons

Endpoint biasanya mengembalikan tatasusunan dengan 2 lagu. Permintaan tak segerak biasanya bermula pada status pending; simpan song_id dan dapatkan status akhir serta alamat audio melalui API pertanyaan lagu. Medan lagunya sama seperti dalam API penjanaan mod mudah.

Medan serasi

Integrasi baharu sebaiknya menggunakan snake_case secara konsisten. Jika satu permintaan membawa snake_case dan camelCase sekali gus, nilai snake_case yang diutamakan.