Metin Okuma API Entegrasyonu: Geliştiriciler için Eksiksiz Rehber

Kısaca: DubVoice.ai metin okuma API'si REST tabanlı, sk_ anahtarıyla kimlik doğrulaması yapıyor ve webhook destekliyor. Metin ve voice_id ile /api/v1/tts'e POST atın, ardından audio_url ve srt_url için GET /api/v1/tts/{task_id} ile sorgulayın. Her hesapta başlangıç kredisi var.

Uygulamanıza metin okuma yeteneği eklemek mi istiyorsunuz? Bu rehber DubVoice.ai metin okuma API'sini entegre etmek için gerekenlerin tamamını kapsıyor — kimlik doğrulamadan üretim ortamı pratiklerine kadar.

Neden hazır bir API?

Metin okumayı sıfırdan kurmak devasa veri kümeleri, pahalı GPU altyapısı ve derin makine öğrenmesi uzmanlığı ister. Hazır bir API şunu verir:

• Üretime hazır sesler — kutudan çıkar çıkmaz 17.800+ doğal ses
• Çok dil desteği — tek arayüzle 50+ dil
• Ölçeklenebilirlik — altyapı derdi olmadan binlerce istek
• Sürekli iyileşme — ses kalitesi sizin hiçbir şey yapmanıza gerek kalmadan artar

Hızlı başlangıç

Kimlik doğrulama

Her istek bir API anahtarı gerektirir. Anahtarınızı DubVoice.ai panelinden alın: Ayarlar → API Anahtarları.

Temel istek

curl -X POST https://dubvoice.ai/api/v1/tts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello, welcome to our application!",
    "voice_id": "voice_rachel",
    "language": "en"
  }'

Yanıt

API bir ses dosyası (varsayılan MP3) ile birlikte karakter sayısı ve işlem süresi gibi meta verileri döndürür.

Entegrasyon desenleri

Desen 1: İstek üzerine üretim

Ses, kullanıcı istediği anda üretilir. Etkileşimli uygulamalar, sohbet botları ve erişilebilirlik özellikleri için uygundur.

Desen 2: Önceden üretim

Bilinen içerik için ses önceden üretilip önbelleğe alınır. E-öğrenme platformları, sesli yanıt sistemleri ve statik içerik için uygundur.

Desen 3: Akış

Gecikmenin önemli olduğu gerçek zamanlı uygulamalar için. Ses parçaları üretildikçe akıtılır.

İyi pratikler

• Agresif önbellekleme yapın — aynı metin tekrar isteniyorsa önbellekten verin
• Limitleri yönetin — 429 yanıtı için üstel geri çekilme uygulayın
• Girdiyi doğrulayın — göndermeden önce metin uzunluğunu ve içeriğini kontrol edin
• Kullanımı izleyin — beklenmedik maliyet için karakter tüketimini takip edin
• Webhook kullanın — uzun metinlerde geri çağırmalı asenkron üretimi tercih edin

Hata yönetimi

Hataları her zaman açıkça ele alın:

• 400 — geçersiz istek (metin uzunluğu, voice_id, dil kontrolü)
• 401 — geçersiz veya süresi dolmuş API anahtarı
• 429 — istek limiti aşıldı (geri çekilme gerekir)
• 500 — sunucu hatası (üstel geri çekilmeyle yeniden deneyin)

API kullanımının fiyatı

API istekleri, web arayüzüyle aynı orandan aynı bakiyeden kredi düşer. Bir kredi bir karakterdir. Paketler 250 bin kredi ($4,99) ile 40 milyon kredi ($110) arasında değişir.

Yaygın kullanım alanları

• Mobil uygulamalar — okuma, haber veya navigasyon uygulamalarına sesli anlatım
• Web uygulamaları — erişilebilirlik, sesli içerik, kullanıcı bildirimleri
• Cihazlar — akıllı ev anonsları, gömülü sesli yanıtlar
• Oyunlar — karakter replikleri, anlatıcı sesi, dinamik hikâye
• SaaS platformları — raporların, panellerin ve uyarıların sesli sürümleri

Senkron mu asenkron mu — kod yazmadan önce karar verin

Entegrasyonun geri kalanının şeklini bu karar belirliyor ve varsayılana savrularak yanlış vermek kolay.

Kısa metin, istek içinde beklenecek kadar hızlı dönüyor. Bir karşılama, bir bildirim, bir ürün adı — bir iki saniye, ve bloklamak alternatiften basit. Uzun metin dönmüyor. 15.000 karakterlik bir makale dakikalar sürebiliyor ve onu bekleyen bir sunucusuz fonksiyon, ses hazır olmadan çok önce platform tarafından öldürülüyor.

Hata senaryosunu açıkça söylemekte fayda var: fonksiyonunuz zaman aşımına uğruyor, kullanıcı hata görüyor, iş ise sunucuda başarıyla bitiyor. Krediyi yaktınız, sonucu kaybettiniz.

O yüzden birkaç bin karakterin üstünde gönderip yoklayın. Görev kimliğini hemen alın, tarayıcıya döndürün ve yoklamayı ince bir durum ucuna tarayıcı yapsın. Gönderen istek, render ne kadar sürerse sürsün bir saniyenin altında kalıyor.

İki kez ödemeden hata yönetimi

İki kural, ters gidenlerin çoğunu kapatıyor.

İstek limitini hata değil bekleme sayın. 429 yanıtı, ne kadar bekleyeceğinizi söyleyen bir Retry-After başlığı taşıyor. Hemen yeniden denemek yerine ona uyun — limite yeniden denemek limiti yalnızca uzatıyor. Eşzamanlı işçilerin aynı anda denememesi için biraz rastgelelikle üstel olarak geri çekilin.

Yeniden denemeleri idempotent yapın. İş yürütücünüz gönderdikten sonra ama görev kimliğini kaydetmeden çökerse, saf çözüm yeniden göndermektir — ve tek bir ses için iki kez ödemiş olursunuz. Görev kimliğini her şeyden önce veritabanına yazın ve göndermeden önce mevcut olup olmadığına bakın.

Ne saklamalı ve ne kadar süre

Görev kimliğini, metnin hash'ini, ses kimliğini ve çıkan ses URL'ini saklayın. Metin hash'i, aynı senaryo tekrar geldiğinde render'ı tamamen atlamanızı sağlıyor — ki pratikte sık oluyor: aynı ürün açıklaması defalarca isteniyor.

Sağlayıcının URL'ini kalıcı depolama saymayın. Dosyayı indirip kendi kontrolünüzdeki bir yere, kendi takviminizle koyun. Sizin vermediğiniz bir URL'in süresi dolabilir ve bunu ilk olarak çalışmayan oynatıcı hakkındaki destek talebinden duyarsınız.

Aynı anahtarla erişilebilen diğer her şeyin turu için [platformun yapabildiklerine](/blog/everything-you-can-do-with-dubvoice-ai) bakın.

Başlarken

• dubvoice.ai'de kaydolun ve API anahtarınızı alın
• Basit bir cURL isteğiyle test edin
• Tercih ettiğiniz dilde uygulamanıza entegre edin
• Farklı sesler ve dillerle deneyin
• Yayına alın ve kullanımı izleyin

Tam uç nokta referansı, ses kataloğu ve dil kodları için dubvoice.ai/api-docs adresindeki dokümantasyona bakın.