API penjanaan pertuturan

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

Penerangan endpoint

Speech menukar teks ucapan atau perihalan satu baris menjadi audio "bertutur/ucapan", dengan muzik latar sebagai pilihan. Sesuai untuk ucapan, toast, narasi, skrip suara latar, kandungan audio dan senario serupa.

Perhatian: endpoint ini menghasilkan audio pertuturan, bukan lagu yang dinyanyikan (tiada melodi dan tiada vokal nyanyian). Jika perlu nyanyian, gunakan API penjanaan mod mudah atau API penjanaan mod tersuai.

Endpoint: POST /api/music/speech

Pengebilan: Berbayar, kini lalai 0.6 ¥ setiap panggilan. Setiap panggilan biasanya memulangkan 2 audio; jumlah yang benar-benar dicaj mengikut tetapan harga 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 beberapa saat (1-10 saat); tetapi seperti endpoint penjanaan segerak lain, dalam kes melampau ia boleh mengambil masa lebih lama. 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.

Pematuhan kandungan: platform menyemak teks dari segi hak cipta dan dasar kandungan. Jika dinilai melibatkan bahan berhak cipta (contohnya memetik lirik orang lain atau teks asal karya terkenal), panggilan ini gagal dan keseluruhan bayaran dipulangkan secara automatik. Tukar kepada ayat anda sendiri, atau jadikan petikan itu parafrasa, kemudian cuba lagi.

Parameter permintaan

Headers

Parameter body

Endpoint ini tidak menyokong duration: menghantarnya memulangkan HTTP 400, bukan diabaikan secara senyap. Tempoh ucapan ditentukan oleh panjang kandungan script.

Contoh permintaan

Permintaan minimum (teks sahaja)

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 semua! Ucapan saya hari ini tentang memanfaatkan masa dengan baik dan terus melangkah ke hadapan."
  }'

Permintaan penuh (dengan nada, jantina dan muzik 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 petang, rakan-rakan. Saya akan melaporkan kemajuan minggu ini.',
        'tone': 'tenang dan jelas, laporan mesyuarat',
        '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 (ucapan, wajib)

• Tampal kandungan yang ingin anda sampaikan; anda juga boleh menulis satu perihalan dan biarkan model menyediakan ucapan itu (contohnya "kata-kata semangat separuh masa untuk pasukan yang ketinggalan dua puluh mata, daripada bisikan perlahan hingga pekikan sekuat hati").
• Baris baharu, perenggan dan arahan pentas seperti [jeda] boleh ditulis terus, dan model akan mengikutinya seboleh mungkin.
• Hadnya 3000 aksara (dikira sebagai aksara Unicode; satu aksara Cina dikira 1); melebihi had memulangkan 400 tanpa caj.

tone (nada dan suasana, pilihan)

Ia menerangkan bagaimana bercakap, bukan apa yang dikatakan. Sebaiknya sertakan empat jenis maklumat: nada, tempo/irama, emosi dan suasana.

Bertenaga dan kuat, tempo daripada perlahan ke pantas, jeda yang jelas; dewan sekolah, di hadapan semua guru dan pelajar
Hangat dan lembut, tempo perlahan; majlis perkahwinan
Tenang dan terkawal, sekata dan jelas; laporan kepada lembaga pengarah

Hadnya 1000 aksara. Jika tidak dihantar, model menilainya daripada kandungan script.

gender / vocal_gender (jantina penutur, pilihan)

• Untuk suara lelaki hantar m atau male, untuk suara wanita f atau female; pelayan menormalkannya kepada m / f.
• Kedua-dua nama medan berfungsi, pilih satu sahaja: gender ialah bentuk yang disyorkan untuk endpoint ini; jika anda sudah menggunakan mod tersuai, anda boleh terus guna vocal_gender.
• Tidak menghantar bermaksud "bebas", model yang menentukan.

backing_music (muzik latar, pilihan)

• Lalai true (dengan muzik latar), sama seperti lalai dalam versi web Suno.
• false memberi ucapan dengan suara sahaja, berguna jika kemudian anda mahu menambah muzik atau suara latar sendiri.
• Mesti boolean JSON true / false; rentetan "true" dan "1" juga diterima, tetapi boolean lebih disyorkan.

model (model, pilihan)

Ketiga-tiga model untuk pelanggan tersedia pada harga yang sama (0.6 ¥ setiap panggilan). Ucapan dijana oleh keluarga Suno v6; jika tidak dihantar ia dianggap sebagai suno-v6. Kecuali anda ada keutamaan tertentu, biasanya medan ini tidak perlu dihantar.

Pengesahan parameter dan had teks

Kes berikut memulangkan HTTP 400, dan semuanya disekat sebelum pengebilan, jadi tiada kos timbul:

Had medan teks

Melebihi had juga memulangkan HTTP 400 dan tidak masuk ke penjanaan serta tiada caj pendahuluan. Pengiraan menggunakan aksara Unicode (satu aksara Cina dikira 1) dan ruang di awal serta akhir turut dikira:

Mesej ralat berbentuk script must not exceed 3000 characters; received 4120: perkataan pertama ialah nama medan yang melebihi had dan penghujungnya ialah bilangan sebenar, jadi apabila menerima 400 anda boleh terus memangkas dengan dua nombor itu.

Respons

Respons ialah tatasusunan lagu sama seperti endpoint penjanaan lain (biasanya 2 item); simpan song_id dan gunakan API pertanyaan lagu dan sejarah untuk melihat status akhir dan alamat audio:

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

Kegagalan penjanaan dan bayaran balik

Jika penjanaan gagal, kos panggilan itu dipulangkan penuh secara automatik; tidak perlu menghubungi sokongan. Puncanya kelihatan dalam respons atau dalam error_message bagi API pertanyaan lagu dan sejarah.

Punca paling biasa ialah kandungan dinilai melibatkan bahan berhak cipta, contohnya:

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

Dalam kes itu, tukar teks kepada ayat anda sendiri (atau jadikan petikan itu parafrasa) dan hantar semula.

Soalan lazim

S: Mengapa hasilnya "bertutur" dan bukan nyanyian? J: Ini endpoint ucapan, dan outputnya audio pertuturan. Untuk nyanyian gunakan endpoint penjanaan atau mod tersuai.

S: Mengapa setiap kali memulangkan 2 item? J: Seperti endpoint penjanaan lain di platform ini, satu penjanaan menghasilkan 2 calon; pertanyakan secara berasingan mengikut song_id dan pilih yang anda suka.

S: Bagaimana mengawal tempoh? J: Ia ditentukan oleh panjang script; endpoint ini tidak menerima parameter duration.

S: Bolehkah saya tentukan suara (contohnya suara klon saya)? J: Versi semasa belum menyokong. Ucapan menggunakan set suara pertuturan tetap, dan gender memilih lelaki atau wanita; jika perlu suara anda sendiri, gunakan keupayaan berkaitan API penciptaan profil suara (disyorkan).

S: Apa jadi jika tone tidak dihantar? J: Model menilai nada dan irama daripada kandungan script. Untuk menghasilkan semula sesuatu gaya dengan stabil, tulis nada, tempo dan suasana dalam tone.

Medan serasi

Untuk integrasi baharu gunakan snake_case secara konsisten. Medan lain (script, tone, song_title, backing_music) tiada alias camelCase.

Langkah seterusnya

Setelah mendapat song_id:

1. Gunakan API pertanyaan lagu dan sejarah untuk melihat status penjanaan dan alamat audio;
2. Setelah selesai, gunakan API muat turun dan pratonton media lagu untuk memuat turun atau mendengarnya;
3. Untuk muat turun pukal atau menyalin ke storan anda sendiri, lihat endpoint pusat muat turun.