API pembuatan mode kustom

Diperbarui 2026-09-18 · tim Suno-API

Deskripsi endpoint

Mode kustom cocok ketika lirik, gaya, dan judul sudah siap dan Anda ingin mengendalikan suara yang bernyanyi, kekuatan pengaruh gaya, serta tingkat keacakan pembuatan.

Endpoint: POST /api/music/create/custom

Biaya: Berbayar, saat ini default 0,6 ¥ per panggilan. Setiap panggilan biasanya mengembalikan 2 lagu; jumlah yang benar-benar ditagih mengikuti konfigurasi harga di back-office saat ini.

Max Mode / Variety: endpoint ini mendukung parameter opsional max_mode dan variety (0-4). Dengan max_mode aktif, panggilan ini ditagih 2× harga (0,6 → 1,2 ¥ per panggilan); variety tidak menambah biaya. Arti dan cara mengirimnya ada di bagian "Parameter lanjutan" pada Ringkasan API baru.

Waktu tunggu dan timeout (penting): ini endpoint sinkron — pesanan baru diterima dan diteruskan ke pembuatan saat respons tiba. Dari pengukuran, sebagian besar permintaan merespons dalam 1-3 detik, sekitar 10% melewati 30 detik, dan terlama sekitar 230 detik. Setel timeout klien 300 detik atau lebih; tidak ada respons bukan berarti tidak ada yang dibuat, dan jangan mencoba ulang langsung setelah timeout (itu menduplikasi pesanan dan menagih dua kali). Jika koneksi terputus, periksa lagi nanti dengan GET /api/music/songs. Lihat "Waktu tunggu dan pengaturan timeout" di Ringkasan API baru.

Parameter permintaan

Headers

Parameter body

Catatan parameter lanjutan

Gender vokal vocal_gender

• Kirim m atau male untuk suara pria, f atau female untuk suara wanita.
• Layanan menormalkan male dan female menjadi m dan f.
• Dengan instrumental=true, parameter gender vokal tidak dikirim ke layanan pembuatan.

Pengaruh gaya style_weight

Mengendalikan seberapa kuat hasil mengikuti style_tags. Semakin tinggi nilainya, semakin hasil cenderung mengikuti tag gaya yang Anda kirim.

Keacakan weirdness_constraint

Mengendalikan seberapa bervariasi dan eksperimental hasilnya. Nilai tinggi biasanya memberi lebih banyak variasi; nilai rendah memberi hasil yang lebih aman.

Kedua parameter angka berkisar 0.0 sampai 1.0, dan 0 adalah nilai eksplisit yang sah. Hanya menghilangkan kolom sepenuhnya yang berarti "tidak ditentukan".

Saat mengisinya, ingat bahwa ini pecahan desimal, bukan bilangan bulat persen. Acuan yang disarankan: 0.0–0.3 konservatif, 0.4–0.6 seimbang, 0.7–1.0 lebih eksperimental; tanpa preferensi jelas gunakan 0.5 atau cukup hilangkan. Contoh: weirdness_constraint: 0.5, jangan 50 atau 50%.

Dengan instrumental=true, hasilnya instrumental sehingga lirik dan gender vokal tidak bekerja seperti pada lagu bernyanyi; jika butuh vokal, kirim false atau hilangkan kolom itu. Kolom boolean harus memakai true/false JSON, bukan string.

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 melintas jendela',
        '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()

Mode tanda terima penerimaan (opsional)

Endpoint ini juga mendukung mode tanda terima penerimaan dari API pembuatan mode sederhana: dengan "accept_mode": "async" di body (atau header X-Accept-Mode: async), endpoint langsung mengembalikan 202 dan nomor tanda terima, pembuatan berjalan di latar belakang, dan Anda memantau kemajuannya dengan GET /api/music/requests/{request_id}.

Cocok untuk klien yang tidak boleh menahan koneksi lama, atau yang tidak ingin timeout dibaca sebagai "tidak ada yang dibuat". Tanpa parameter itu, perilakunya persis seperti sebelumnya.

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 polling ada di bagian "Mode tanda terima penerimaan" pada API pembuatan mode sederhana.

Validasi parameter

Kasus berikut mengembalikan HTTP 400, dan message kesalahan menyebut kolom yang tidak valid:

• style_weight atau weirdness_constraint bukan angka.
• Nilai angka di bawah 0.0 atau di atas 1.0.
• vocal_gender bukan salah satu dari m, f, male, female.

Batas kolom teks

Kolom berikut juga mengembalikan HTTP 400 saat terlalu panjang, tidak masuk ke pembuatan dan tidak dipotong biaya di muka. Perhitungan per karakter Unicode (satu aksara Han dihitung 1) dan spasi di awal/akhir ikut dihitung:

Pesan kesalahan berbentuk style_tags must not exceed 1000 characters; received 2772: kata pertama adalah nama kolom yang melanggar dan di akhir adalah jumlah terukur, jadi saat menerima 400 cukup memangkas dengan dua angka itu tanpa mencoba kolom satu per satu. Aturan umumnya ada di "Batas kolom teks" pada Ringkasan API baru.

Respons

Endpoint biasanya mengembalikan array berisi 2 lagu. Permintaan asinkron biasanya mulai pada status pending; simpan song_id lalu ambil status akhir dan alamat audio melalui API kueri lagu. Kolom lagunya sama dengan API pembuatan mode sederhana.

Kolom yang kompatibel

Integrasi baru sebaiknya memakai snake_case secara konsisten. Jika satu permintaan membawa snake_case dan camelCase sekaligus, nilai snake_case yang berlaku.