API pembuatan ucapan

Diperbarui 2026-09-18 · tim Suno-API

Deskripsi endpoint

Speech mengubah naskah pidato atau deskripsi satu baris menjadi audio "berbicara/pidato", dengan musik latar opsional. Cocok untuk pidato, sambutan, narasi, naskah sulih suara, konten audio, dan skenario serupa.

Perhatian: endpoint ini menghasilkan audio ucapan, bukan lagu yang dinyanyikan (tanpa melodi dan tanpa vokal bernyanyi). Kalau butuh nyanyian, gunakan API pembuatan mode sederhana atau API pembuatan mode kustom.

Endpoint: POST /api/music/speech

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

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 hitungan detik (1-10 detik); namun seperti endpoint pembuatan sinkron lainnya, dalam kasus ekstrem bisa lebih lama. 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.

Kepatuhan konten: platform memeriksa naskah dari sisi hak cipta dan kebijakan konten. Bila dinilai melibatkan materi berhak cipta (misalnya mengutip lirik orang lain atau teks asli karya terkenal), panggilan ini gagal dan seluruh biaya dikembalikan otomatis. Beralihlah ke kalimat Anda sendiri, atau ubah kutipan menjadi parafrase, lalu coba lagi.

Parameter permintaan

Headers

Parameter body

Endpoint ini tidak mendukung duration: mengirimnya mengembalikan HTTP 400, bukan diabaikan diam-diam. Durasi pidato ditentukan oleh panjang isi script.

Contoh permintaan

Permintaan minimal (hanya naskahnya)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Selamat pagi bapak dan ibu guru serta teman-teman! Hari ini pidato saya membahas cara memanfaatkan waktu dan terus melangkah maju."
  }'

Permintaan lengkap (dengan nada, gender, dan musik latar dimatikan)

curl -X POST https://www.suno-api.io/api/music/speech \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  --max-time 300 \
  -d '{
    "script": "Good evening everyone, thank you all for coming to celebrate this special day with us.",
    "tone": "warm and slow, wedding reception",
    "song_title": "Wedding Toast",
    "gender": "f",
    "backing_music": false,
    "model": "suno-v6"
  }'

Contoh Python

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/speech',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'script': 'Selamat sore, rekan-rekan. Saya akan melaporkan kemajuan minggu ini.',
        'tone': 'tenang dan jelas, laporan rapat',
        'gender': 'male',
        'backing_music': True,
    },
    timeout=300,
)
response.raise_for_status()
items = response.json()          # biasanya 2 item
for item in items:
    print(item['song_id'], item['status'])

Penjelasan parameter

script (naskah pidato, wajib)

• Tempel isi yang ingin Anda sampaikan; Anda juga bisa menulis satu deskripsi dan membiarkan model menyusun naskahnya (misalnya "orasi penyemangat di jeda babak untuk tim yang tertinggal dua puluh poin, dari bisikan lirih sampai raungan lantang").
• Baris baru, paragraf, dan arahan panggung seperti [jeda] bisa ditulis langsung, dan model akan mengikutinya sejauh mungkin.
• Batasnya 3000 karakter (dihitung sebagai karakter Unicode; satu aksara Tionghoa dihitung 1); melewatinya mengembalikan 400 tanpa biaya.

tone (nada dan suasana, opsional)

Ini menjelaskan bagaimana berbicara, bukan apa yang dikatakan. Sebaiknya sertakan empat jenis informasi: nada, tempo/irama, emosi, dan suasana.

Bersemangat dan kuat, tempo dari lambat ke cepat, jeda jelas; aula sekolah, di depan seluruh guru dan siswa
Hangat dan lembut, tempo perlahan; resepsi pernikahan
Tenang dan terkendali, tempo tetap dan jelas; laporan ke dewan direksi

Batasnya 1000 karakter. Bila tidak dikirim, model menilainya dari isi script.

gender / vocal_gender (gender pembicara, opsional)

• Untuk suara pria kirim m atau male, untuk suara wanita f atau female; server menormalkannya menjadi m / f.
• Kedua nama field berfungsi, pilih salah satu: gender adalah bentuk yang disarankan untuk endpoint ini; jika Anda sudah memakai mode kustom, Anda bisa tetap memakai vocal_gender.
• Tidak mengirim berarti "bebas", model yang menentukan.

backing_music (musik latar, opsional)

• Default true (dengan musik latar), sama seperti default di versi web Suno.
• false menghasilkan pidato hanya suara, praktis bila nanti Anda ingin menambahkan musik atau sulih suara sendiri.
• Harus berupa boolean JSON true / false; string "true" dan "1" juga diterima, tetapi boolean lebih disarankan.

model (model, opsional)

Ketiga model untuk pelanggan tersedia dengan harga yang sama (0,6 ¥ per panggilan). Pidato dihasilkan oleh keluarga Suno v6; bila tidak dikirim diperlakukan sebagai suno-v6. Kecuali Anda punya preferensi khusus, biasanya field ini tidak perlu dikirim.

Validasi parameter dan batas teks

Kasus berikut mengembalikan HTTP 400, dan semuanya diblokir sebelum penagihan, jadi tidak ada biaya yang timbul:

Batas panjang kolom teks

Melebihi batas juga mengembalikan HTTP 400 dan tidak masuk ke pembuatan serta tidak ada pra-penagihan. Penghitungan memakai karakter Unicode (satu aksara Tionghoa dihitung 1) dan spasi di awal/akhir juga dihitung:

Pesan kesalahannya berbentuk script must not exceed 3000 characters; received 4120: kata pertama adalah nama kolom yang melewati batas dan bagian akhir adalah jumlah sebenarnya, jadi saat mendapat 400 Anda bisa langsung memangkas dengan dua angka itu.

Respons

Responsnya adalah array lagu sama persis dengan endpoint pembuatan lainnya (biasanya 2 item); simpan song_id lalu gunakan API kueri lagu dan riwayat untuk melihat status akhir dan alamat audio:

[
  {
    "song_id": "b7529174-b495-465b-8c5e-cd21bea2df8c",
    "song_title": "Memanfaatkan waktu",
    "status": "pending",
    "audio_url": "",
    "cover_url": "",
    "video_url": "",
    "model_version": "suno-v6",
    "generation_type": "generate",
    "created_at": "2026-10-08T01:00:00Z"
  }
]

Kegagalan pembuatan dan pengembalian dana

Bila pembuatan gagal, biaya panggilan itu dikembalikan penuh secara otomatis; tidak perlu menghubungi dukungan. Penyebabnya terlihat di respons atau di error_message pada API kueri lagu dan riwayat.

Penyebab paling umum adalah konten dinilai melibatkan materi berhak cipta, misalnya:

Your lyrics contain copyrighted material. Please change it and try again.

Dalam kasus itu, ganti naskahnya dengan kalimat Anda sendiri (atau ubah kutipan menjadi parafrase) lalu kirim ulang.

Pertanyaan umum

T: Kenapa hasilnya "berbicara" bukan bernyanyi? J: Ini endpoint pidato, dan keluarannya audio ucapan. Untuk bernyanyi gunakan endpoint pembuatan atau mode kustom.

T: Kenapa setiap kali mengembalikan 2 item? J: Seperti endpoint pembuatan lain di platform ini, satu pembuatan menghasilkan 2 kandidat; kueri terpisah berdasarkan song_id dan pilih yang Anda suka.

T: Bagaimana mengontrol durasi? J: Ditentukan oleh panjang script; endpoint ini tidak menerima parameter duration.

T: Bisakah saya menentukan suara (misalnya suara hasil klon saya)? J: Versi saat ini belum mendukung. Pidato memakai kumpulan suara ucapan tetap, dan gender memilih pria atau wanita; jika butuh suara Anda sendiri, gunakan kemampuan terkait pada API pembuatan profil suara (disarankan).

T: Apa yang terjadi bila tone tidak dikirim? J: Model menilai nada dan irama dari isi script. Untuk mereproduksi gaya tertentu dengan stabil, tulis nada, tempo, dan suasana di tone.

Kolom yang kompatibel

Untuk integrasi baru gunakan snake_case secara konsisten. Kolom lain (script, tone, song_title, backing_music) tidak punya alias camelCase.

Langkah berikutnya

Setelah mendapat song_id:

1. Gunakan API kueri lagu dan riwayat untuk melihat status pembuatan dan alamat audio;
2. Setelah selesai, gunakan API unduhan dan pratinjau media lagu untuk mengunduh atau mendengarkannya;
3. Untuk unduhan massal atau menyalin ke penyimpanan Anda sendiri, lihat endpoint pusat unduhan.