Konuşma (Speech) üretimi API'si

2026-09-18 tarihinde güncellendi · Suno-API ekibi

Uç nokta açıklaması

Speech, bir konuşma metnini veya tek satırlık bir açıklamayı "konuşma/sunum" sesine dönüştürür; arka plan müziği isteğe bağlıdır. Sunumlar, kadeh kaldırma konuşmaları, anlatım, seslendirme metinleri, sesli içerik ve benzeri senaryolar için uygundur.

Dikkat: Bu uç nokta konuşma sesi üretir, söylenen bir şarkı değil (melodi yok, söyleyen vokal yok). Şarkı gerekiyorsa basit mod üretim API'sini veya özel mod üretim API'sini kullanın.

Uç nokta: POST /api/music/speech

Faturalama: Ücretli, şu anda varsayılan olarak çağrı başına 0,6 ¥. Her çağrı genellikle 2 ses dosyası döndürür; gerçekte tahsil edilen tutar güncel arka ofis fiyat yapılandırmasına göre belirlenir.

Max Mode / Variety: bu uç nokta isteğe bağlı max_mode ve variety (0-4) parametrelerini destekler. max_mode açıkken bu çağrı 2 kat fiyattan faturalanır (0,6 → 1,2 ¥ / çağrı); variety için ek ücret alınmaz. Anlamları ve nasıl gönderilecekleri Yeni API genel bakışı sayfasındaki "Gelişmiş parametreler" bölümündedir.

Bekleme süreleri ve zaman aşımları (önemli): bu uç nokta senkrondur — sipariş ancak yanıt geldiğinde kabul edilir ve üretime verilir. Ölçümlere göre isteklerin çoğu saniyeler içinde yanıtlanır (1-10 sn); ancak diğer senkron üretim uç noktalarında olduğu gibi uç durumlarda daha uzun sürebilir. İstemci zaman aşımını 300 saniye veya üzerine ayarlayın; yanıt gelmemesi hiçbir şey üretilmediği anlamına gelmez ve zaman aşımından hemen sonra yeniden denemeyin (siparişi çoğaltır ve tekrar ücret alır). Bağlantı koptuysa daha sonra GET /api/music/songs ile kontrol edin. Yeni API genel bakışı sayfasındaki "Bekleme süreleri ve zaman aşımı ayarları" bölümüne bakın.

İçerik uygunluğu: platform metni telif hakkı ve içerik politikası açısından denetler. Telif korumalı materyal olarak değerlendirilirse (örneğin başkasının şarkı sözlerini veya bilinen bir eserin birebir metnini alıntılamak), bu çağrı başarısız olur ve tutarın tamamı otomatik olarak iade edilir. Kendi ifadenize geçin ya da alıntıyı başka sözcüklerle aktarmaya çevirip yeniden deneyin.

İstek parametreleri

Headers

Gövde parametreleri

Bu uç nokta duration parametresini desteklemez: gönderilirse HTTP 400 döner, sessizce yok sayılmaz. Konuşma süresi script içeriğinin uzunluğuna göre belirlenir.

İstek örnekleri

En küçük istek (yalnızca metin)

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": "Herkese günaydın! Bugünkü konuşmam zamanımızı iyi kullanmak ve ilerlemek üzerine."
  }'

Tam istek (ton ve cinsiyet belirtilmiş, arka plan müziği kapalı)

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"
  }'

Python örneği

import requests

response = requests.post(
    'https://www.suno-api.io/api/music/speech',
    headers={'Authorization': 'Bearer YOUR_API_KEY'},
    json={
        'script': 'Merhaba arkadaşlar. Bu haftanın ilerlemesini aktaracağım.',
        'tone': 'sakin ve net, toplantı sunumu',
        'gender': 'male',
        'backing_music': True,
    },
    timeout=300,
)
response.raise_for_status()
items = response.json()          # genelde 2 kayıt
for item in items:
    print(item['song_id'], item['status'])

Parametre açıklamaları

script (konuşma metni, zorunlu)

• Söylemek istediğiniz içeriği doğrudan yapıştırın; tek bir açıklama yazıp metni modelin yazmasını da sağlayabilirsiniz (örneğin "yirmi sayı geride olan bir takım için soyunma odası motivasyonu, alçak bir mırıltıdan avaz avaz haykırışa").
• Satır sonları, paragraflar ve [duraklama] gibi sahne yönlendirmeleri doğrudan yazılabilir; model bunlara mümkün olduğunca uyar.
• Sınır 3000 karakterdir (Unicode karakter olarak sayılır, bir Çince karakter 1 sayılır); aşılırsa 400 döner ve ücret alınmaz.

tone (ton ve ortam, isteğe bağlı)

Ne söyleneceğini değil, nasıl söyleneceğini tanımlar. Dört tür bilgi eklemek iyi olur: ton, hız/ritim, duygu ve ortam.

Enerjik ve güçlü, tempo yavaştan hızlıya, belirgin duraklamalar; okul salonu, tüm öğrenci ve öğretmenlerin karşısında
Sıcak ve yumuşak, sakin tempo; düğün resepsiyonu
Sakin ve ölçülü, dengeli ve net; yönetim kurulu sunumu

Sınır 1000 karakterdir. Gönderilmezse model script içeriğinden kendisi belirler.

gender / vocal_gender (konuşmacının cinsiyeti, isteğe bağlı)

• Erkek ses için m veya male, kadın ses için f veya female gönderin; sunucu bunları m / f olarak normalleştirir.
• İki alan adı da çalışır, yalnızca birini kullanın: bu uç noktada önerilen biçim gender'dır; hâlihazırda özel modu kullanıyorsanız vocal_gender ile devam edebilirsiniz.
• Göndermemek "sınırsız" anlamına gelir, kararı model verir.

backing_music (arka plan müziği, isteğe bağlı)

• Varsayılan true (arka plan müziği var), Suno web sürümündeki varsayılanla aynıdır.
• false yalnızca ses içeren bir konuşma verir; sonradan kendi müziğinizi veya dublajınızı eklemek isterseniz kullanışlıdır.
• JSON boolean true / false olmalıdır; "true" ve "1" metinleri de kabul edilir, ancak boolean önerilir.

model (model, isteğe bağlı)

Üç müşteri modeli de aynı fiyatla kullanılabilir (çağrı başına 0,6 ¥). Konuşma Suno v6 ailesi tarafından üretilir; gönderilmezse suno-v6 olarak işlenir. Belirgin bir tercihiniz yoksa bu alanı göndermeniz genelde gerekmez.

Parametre doğrulama ve metin sınırları

Aşağıdaki durumlar HTTP 400 döndürür ve hepsi ücretlendirmeden önce engellenir, dolayısıyla masraf oluşmaz:

Metin alanı sınırları

Sınırı aşmak da HTTP 400 döndürür ve üretime geçmez, ön tahsilat yapılmaz. Sayım Unicode karaktere göredir (bir Çince karakter 1 sayılır) ve baştaki/sondaki boşluklar da dâhildir:

Hata script must not exceed 3000 characters; received 4120 biçimindedir: ilk sözcük sınırı aşan alan adı, sonu ise gerçek karakter sayısıdır, yani 400 aldığınızda bu iki sayıyla doğrudan kısaltabilirsiniz.

Yanıt

Yanıt, diğer üretim uç noktalarıyla tamamen aynı şarkı dizisidir (genelde 2 kayıt). song_id değerini kaydedip şarkı sorgulama ve geçmiş API'si ile nihai durumu ve ses adresini sorgulayın:

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

Üretim hatası ve iadeler

Üretim başarısız olursa o çağrının ücreti otomatik olarak tamamen iade edilir; destek ekibine başvurmanız gerekmez. Nedeni yanıtta veya şarkı sorgulama ve geçmiş API'si error_message alanında görülebilir.

En sık görülen neden içeriğin telif korumalı materyal olarak değerlendirilmesidir, örneğin:

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

Bu durumda metni kendi ifadenizle değiştirip (veya alıntıyı başka sözcüklerle aktarmaya çevirip) yeniden gönderin.

Sık sorulan sorular

S: Neden sonuç şarkı değil de "konuşma"? C: Bu uç nokta konuşma içindir ve çıktısı konuşma sesidir. Şarkı için üretim veya özel mod uç noktalarını kullanın.

S: Neden her seferinde 2 kayıt dönüyor? C: Platformun diğer üretim uç noktalarında olduğu gibi bir üretim 2 aday üretir; bunları song_id ile ayrı ayrı sorgulayıp memnun kaldığınızı seçin.

S: Süreyi nasıl kontrol ederim? C: script uzunluğu belirler; bu uç nokta duration parametresini kabul etmez.

S: Bir ses (örneğin klonladığım ses) belirtebilir miyim? C: Mevcut sürüm desteklemiyor. Konuşma sabit bir konuşma sesi kümesi kullanır ve gender erkek/kadın seçer; kendi sesiniz gerekiyorsa ses profili oluşturma API'sinin (önerilir) ilgili yeteneğini kullanın.

S: tone göndermezsem ne olur? C: Model tonu ve ritmi script içeriğine göre belirler. Bir stili tutarlı biçimde tekrarlamak için ton, hız ve ortamı tone alanına yazın.

Uyumlu alanlar

Yeni entegrasyonlarda snake_case kullanın. Diğer alanların (script, tone, song_title, backing_music) camelCase takma adı yoktur.

Sonraki adımlar

song_id değerini aldıktan sonra:

1. Üretim durumunu ve ses adresini görmek için şarkı sorgulama ve geçmiş API'sini kullanın;
2. Tamamlandığında şarkı medyası indirme ve önizleme API'si ile indirin veya dinleyin;
3. Toplu indirme veya kendi depolamanıza aktarma için indirme merkezi uç noktalarına bakın.