TTS API Dokümantasyonu ve Entegrasyon Rehberi

Yazan SesliRehber editör ekibi · Güncellendi 2026-11-18

Bu dokümantasyon, Tıp ekipleri ve hasta rehberleri hazırlayan büyük gruplar için tasarlanmış SesliRehber TTS API'sinin teknik entegrasyonunu detaylandırır. POST /v1/audio/speech endpoint'i üzerinden JSON formatında veri göndererek, karmaşık tıbbi terminolojiyi yüksek doğrulukla sese dönüştürürsünüz. OpenAI SDK yapısıyla uyumlu altyapı, mevcut kod tabanınıza minimal değişikliklerle entegrasyon imkanı sunar.

Sayfada; kimlik doğrulama, istek parametreleri, yanıt formatları ve hata kodları eksiksiz şekilde açıklanmıştır. Python, cURL veya doğrudan HTTP istekleriyle ses dosyası üretme süreçlerini adım adım izleyebilirsiniz. Belirtilen örnekler, tıbbi içeriklerin hızlıca ve tutarlı bir şekilde audio materyale dönüştürülmesi için gereken teknik altyapıyı sağlar.

TTS API Dokümantasyonu ve Entegrasyon Rehberi

Sıkça sorulan sorular

API endpoint'i nedir?

Metin seslendirmesi için POST https://api.playpaksuper.com/v1/audio/speech endpoint'ini kullanın. Sesler ve modeller hakkında bilgi almak için GET /v1/voices ve GET /v1/models endpoint'leri mevcuttur. Bu yapı, OpenAI Speech endpoint'i ile aynıdır.

Hangi HTTP metodunu kullanmalıyım?

Ses dosyası oluşturmak için POST metodunu kullanın. Ses listesi, dil desteği, formatlar ve fiyat bilgisi için GET metodunu kullanın. Bu yapı, OpenAI Speech endpoint'i ile aynıdır.

Kimlik doğrulama nasıl yapılır?

İstek başlıklarına Authorization: Bearer tts-... formatında API anahtarınızı ekleyin. Hesabınızda tek bir aktif anahtar bulunur. Yeni anahtar oluşturduğunuzda eski anahtar anında geçersiz hale gelir.

Hangi parametreler mevcut?

İstek gövdesinde model (tts-1 veya tts-1-hd), input (metin), voice (8 ses seçeneği), response_format (mp3, wav, opus, flac, pcm), speed (0.25–4.0) ve isteğe bağlı language parametreleri bulunur.

Hangi formatlar destekleniyor?

Çıktı formatları olarak mp3, wav, opus, flac ve pcm desteklenir. Bu formatları response_format parametresi ile belirtebilirsiniz. Varsayılan format genellikle mp3'tür ancak açıkça belirtmeniz önerilir.

Dil seçimi nasıl yapılır?

23 dil desteklenir. language parametresi ISO kodu ile belirtilir. Belirtilmezse sistem dili tahmin eder; Latin alfabesi varsayılan olarak İngilizce olarak kabul edilir. Türkçe, Almanca, Fransızca vb. diller için açıkça belirtin.

Hız ayarı nasıl yapılır?

Konuşma hızını speed parametresi ile 0.25 ile 4.0 arasında ayarlayabilirsiniz. Varsayılan hız 1.0'dır. Tıbbi terminoloji için daha yavaş hızlar, anlaşılırlığı artırmak amacıyla önerilir.

Hangi hata kodları döner?

Belirli hata kodları listelenmemiştir. Ancak başarısız istekler için ücret iade edilir. İstekler sırayla işlendiğinden, yoğunluk sırasında bekleme süresi oluşabilir.

OpenAI SDK ile uyumlu mu?

Evet, istek şekli OpenAI Speech endpoint'i ile aynıdır. SDK'ları kullanırken base_url değerini https://api.playpaksuper.com/v1 olarak değiştirerek ve kendi API anahtarınızı ekleyerek doğrudan entegre edebilirsiniz.

cURL ile nasıl istek atılır?

POST metodu ile https://api.playpaksuper.com/v1/audio/speech endpoint'ine JSON gövdesi gönderin. Authorization başlığında API anahtarınızı belirtin. model, input, voice ve response_format alanlarını doldurun.

Karakter sınırı nedir?

Her istek için maksimum 4096 karakter sınırı vardır. Boşluklar ve noktalama işaretleri de karakter sayısına dahildir. Bu sınır, tek bir API çağrısı için geçerlidir. Uzun metinler için bölme gereklidir.

Uzun metinler nasıl işlenir?

Metinleri 4096 karakterlik parçalara bölün. Her parça için ayrı API istekleri gönderin. Elde edilen ses dosyalarını istemci tarafında veya sunucu tarafında birleştirerek tek bir tam metin çıktısı oluşturun.

Dil tahmini nasıl çalışır?

Dil belirtilmezse sistem metnin script'ine göre tahmin yapar. Latin alfabesi içeren metinler varsayılan olarak İngilizce olarak kabul edilir. Türkçe, Almanca veya diğer diller için language parametresini açıkça belirtin.

Rate limit nedir?

Her API anahtarı için dakika başına 60 istek limiti vardır. İlk yüklemeniz yapılmadan önce bu limit dakika başına 10 istektir. Bu limit, dakikada 60 (ilk yükleme öncesi dakikada 10) istek içindir.

İlk istek

curl

curl https://api.playpaksuper.com/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.playpaksuper.com/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.playpaksuper.com/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariakadın
novakadın
lunakadın
sagekadın
felixerkek
miloerkek
atlaserkek
orionerkek
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

API Endpoint'i

İçin ses dalga görseli: API Endpoint'i

TTS API, metinleri yüksek kaliteli ses dosyalarına dönüştürmek için https://api.playpaksuper.com/v1/audio/speech endpoint'ini kullanır. Bu uç nokta, OpenAI speech endpoint'iyle aynı JSON yapısını benimser, böylece mevcut OpenAI SDK'larını doğrudan entegre edebilirsiniz.

İstekler, tıbbi terminoloji içeren metinleri işleyerek ses dosyası üretir. Her istek, belirlenen model ve ses ayarlarına göre tek bir audio dosyası döndürür.

POST /v1/audio/speech

POST /v1/audio/speech

Bu endpoint, metni sese dönüştürmek için tek işlevsel kapıdır. HTTP POST metodu ile veri gönderilir ve API, işlenen audio dosyasını yanıt olarak döndürür.

JSON request body

JSON request body

İstek gövdesi, model, metin (input), ses (voice) ve diğer parametreleri içeren bir JSON objesi olmalıdır. Bu yapı, OpenAI SDK'larının beklediği formata uygundur.

Maksimum 4096 karakterlik metinler desteklenir. Uzun tıbbi raporlar için metin parçalara bölünmeli ve sesler ardışık olarak birleştirilmelidir.

  • model: "tts-1" veya "tts-1-hd"
  • input: İşlenecek metin (max 4096 karakter)
  • voice: Ses seçimi (örn. aria, nova)

base_url yapılandırması

OpenAI SDK'larını kullanırken, base_url parametresini https://api.playpaksuper.com/v1 olarak ayarlayın. Bu, isteklerin doğru sunucuya yönlendirilmesini sağlar.

Bu yapılandırma, mevcut OpenAI entegrasyonlarını minimal kod değişikliği ile çalıştırmanıza olanak tanır.

Kimlik Doğrulama

İçin ses dalga görseli: Kimlik Doğrulama

API'ye yapılan tüm isteklerde, başlık alanında Authorization: Bearer tts-<anahtar> formatında bir jeton sağlanmalıdır. Bu anahtar, hesabınızın yetkilendirilmesini sağlar ve her istek için geçerlidir. Yanlış veya süresi dolmuş bir anahtar, isteklerin reddedilmesine neden olur.

Bearer token kullanımı

Kimlik doğrulama, HTTP başlıklarının Authorization alanına Bearer ön ekiyle birlikte API anahtarının eklenmesiyle yapılır. Bu standart yaklaşım, OpenAI SDK'ları ve diğer HTTP istek kütüphaneleriyle sorunsuz uyumluluk sağlar. Anahtarınız güvenli bir şekilde iletilmelidir.

API anahtarı oluşturma

Anahtarınızı /get-api-key/ sayfasında Google veya e-posta + şifre ile kayıt olarak elde edersiniz. Hesabınız oluşturulduğunda sistem otomatik olarak tek bir aktif anahtar verir. Bu anahtarı güvenli bir ortamda saklayın ve isteklerinizde kullanın.

Anahtar yenileme

Güvenlik amacıyla istediğiniz zaman yeni bir anahtar oluşturabilirsiniz. Yeni anahtar verildiğinde, eski anahtar anında geçersiz hale gelir. Bu süreç, mevcut isteklerin kesintisiz devam etmesini sağlar çünkü yeni anahtar hemen kullanıma hazırdır.

İstek Parametreleri

İçin ses dalga görseli: İstek Parametreleri

API isteğinizin yapısını belirleyen bu parametreler, sentezlenen sesin kalitesini ve dilini kontrol eder. Model ve ses seçimi, çıktı dosyasının teknik özelliklerini doğrudan etkiler.

Tıbbi terminoloji içeren uzun metinler için karakter limiti ve ses tonu seçimi, hastalar için anlaşılır ve tutarlı eğitim materyallerinin hazırlanmasında kritik rol oynar.

model seçimi

İki seçenek mevcuttur: "tts-1" ve "tts-1-hd". Her iki model de aynı motoru kullanır ve fiyatları aynıdır. Kalite farkı sadece işleme hızında hissedilebilir; her iki model de aynı motoru kullanır ve fiyatları aynıdır.

input metni

Metin, input alanına JSON formatında gönderilir. Her istekte maksimum 4096 karakter sınırına dikkat edilmelidir. Boşluklar ve noktalama işaretleri bu karakter sayısına dahildir.

  • Uzun metinler için parçalara bölünmeli ve ses dosyaları birleştirilmelidir.

voice seçeneği

8 farklı ses preseti arasından seçim yapabilirsiniz. Tıbbi terminoloji ve hasta rehberleri için "sage" (sakin, eğitici) veya "atlas" (tarafsız, haber tarzı) önerilir.

  • Kadın: aria, nova, luna, sage
  • Erkek: felix, milo, atlas, orion

Yanıt Formatları

İçin ses dalga görseli: Yanıt Formatları

API, response_format parametresiyle ses dosyasının çıkış biçimini belirlemenize olanak tanır. Varsayılan format mp3'tür. Desteklenen formatlar arasında mp3, wav, opus, flac ve pcm yer alır. Bu esneklik, tıbbi terminoloji içeren hasta rehberlerinizin farklı yayın platformlarına ve ses oynatıcılara uyumlu olmasını sağlar.

mp3 formatı

Varsayılan ve en yaygın kullanılan biçimdir. Yüksek sıkıştırma oranı sayesinde dosya boyutları küçülür ve ağ üzerinden hızlı iletim sağlanır. Tıbbi eğitim materyalleri veya mobil uygulamalar için idealdir.

  • Varsayılan format: mp3
  • Yüksek sıkıştırma oranı
  • Hızlı ağ iletimi

wav formatı

Lossless (kayıpsız) PCM tabanlı bir formattır. Ses kalitesinde herhangi bir sıkıştırma kaybı yaşanmaz. Profesyonel ses düzenleme veya yüksek kaliteli arşivleme gerektiren tıbbi sesli içerikler için uygundur.

  • Lossless (kayıpsız) yapı
  • Yüksek ses kalitesi
  • Düzenleme dostu

opusal ve flac formatları

Opus, düşük bant genişliğinde bile yüksek kalite sunar. FLAC ise lossless sıkıştırma ile disk alanından tasarruf sağlar. Her iki format da modern web ve mobil standartlarıyla tam uyumludur.

  • Opus: Verimli sıkıştırma
  • FLAC: Kayıpsız sıkıştırma
  • Modern uyumluluk

Hız ve Dil Ayarları

İçin ses dalga görseli: Hız ve Dil Ayarları

TTS API, metin okuma hızını 0.25 ile 4.0 aralığında hassas bir şekilde ayarlamanıza olanak tanır. Bu parametre, özellikle uzun tıbbi terminoloji içeren hastalık rehberleri veya karmaşık prosedür anlatımlarında, dinleyicinin bilgiyi takip etme kapasitesine göre optimize edilebilir.

Dil ayarı, API'nin ses sentezi motorunun doğru fonetik kuralları uygulamasını sağlar. Belirtilmezse sistem varsayılan olarak İngilizce kabul eder veya metnin script'ine göre tahmin yürütür.

speed parametresi

Hız parametresi 0.25 ile 4.0 arasında değişir. Standart değer 1.0'dır. Tıbbi terminoloji sunumlarında, terimlerin net duyulması için 0.75-0.9 aralığı önerilir. Hız artışı, karakter başına düşen üretim süresini değiştirmez ancak dinleme deneyimini hızlandırır.

language ISO kodu

Desteklenen 23 dil için ISO 639-1 kodlarını kullanın. Örneğin, Türkçe için 'tr', İngilizce için 'en'. Kod belirtildiğinde, tıbbi metinlerdeki Latin veya Kiril alfabesi karışımı kelimeler doğru telaffuz edilir. Desteklenmeyen dillerde (Örn: Vietnamca, Endonezce) ses desteklenmez.

  • Türkçe: tr
  • İngilizce: en
  • Almanca: de
  • Fransızca: fr

Dil tahmin mekanizması

language alanı boş bırakılırsa sistem, metnin script'ine bakarak dili tahmin etmeye çalışır. Latin alfabesiyle yazılmış metinler varsayılan olarak İngilizce olarak işlenir. Türkçe tıbbi metinlerde hata riskini azaltmak için mutlaka language parametresini gönderin.

Hız ve Dil Ayarları

Hata Kodları

İçin ses dalga görseli: Hata Kodları

API çağrılarında karşılaşılan hata durumlarını ve çözüm yollarını burada bulabilirsiniz. Yanıt kodları, isteğinizin neden reddedildiğini veya işlenemediğini gösterir.

Bu hataları doğru yönetmek, TTS hizmetinizin kesintisiz çalışmasını ve karakter maliyetlerinin doğru yansıtılmasını sağlar.

400 Bad Request

İstek gövdesindeki veri formatı hatalıysa veya desteklenmeyen bir değer içeriyorsa bu hata döner. Karakter sayısı 4096'ı aşabilir veya geçersiz bir model adı girilmiş olabilir.

  • Gövdedeki 'input' alanının metin formatında ve geçerli olduğundan emin olun.
  • Karakter sınırı (4096) aşılmışsa metni bölün.
  • Geçersiz 'voice' veya 'model' değeri girilmiş olabilir.

401 Unauthorized

Geçersiz veya eksik API anahtarı sağlandığında bu hata alınır. 'Authorization: Bearer tts-...' başlığı doğru formatta olmalıdır.

  • Anahtarın kopyalandığından ve son karakterlerin silinmediğinden emin olun.
  • Anahtarın süresi geçmemiş veya iptal edilmemiş olduğunu kontrol edin.

429 Rate Limit

Dakikada 60 istek sınırına ulaşıldığında bu hata döner. İlk yükleme öncesi bu sınır dakikada 10'dur. Bekleyerek veya isteği yeniden göndererek sorunu çözebilirsiniz.

  • Dakikalık istek sayısını takip edin.
  • Yüksek hacimli metinler için parçalı gönderim stratejisi uygulayın.

OpenAI SDK Entegrasyonu

İçin ses dalga görseli: OpenAI SDK Entegrasyonu

Bu API, OpenAI Speech endpoint'iyle aynı JSON yapısını kullandığı için mevcut OpenAI SDK'larını doğrudan kullanabilirsiniz. İstemciyi yapılandırırken base_url parametresini https://api.playpaksuper.com/v1 olarak ayarlamanız yeterlidir. Bu sayede mevcut kod tabanınızda minimal değişikliklerle entegrasyon sağlayabilirsiniz.

SDK'nın dil bağımsız yapısı, tıbbi terminoloji içeren metinlerin hızlı bir şekilde sese dönüştürülmesini sağlar. Kod örneği, doğru başlık ayarı ve hata yönetimiyle birlikte hazır istek yapısını gösterir.

base_url değiştirme

SDK'nın varsayılan API URL'sini kendi sunucunuzla değiştirin. Bu adım, isteklerin doğru yöne iletilmesini sağlar.

  • OpenAI SDK'nın base_url özelliğini güncelleyin.
  • Doğrulama başlığını otomatik olarak ekler.

client yapılandırması

API anahtarınızı Authorization başlığına ekleyin. İstemci, bu anahtarı her istekte otomatik olarak taşır.

Kod örneği

Aşağıdaki Python kodu, OpenAI SDK kullanarak ses oluşturma işlemini gerçekleştirir.

  • import OpenAI
  • client = OpenAI(base_url='https://api.playpaksuper.com/v1', api_key='tts-...')

cURL Örnekleri

İçin ses dalga görseli: cURL Örnekleri

API ile çalışırken en hızlı doğrulama yöntemi doğrudan terminal istekleridir. Tıbbi terminoloji içeren metinlerin doğru seslendirilip seslendirilmediğini test etmek için hazır cURL komutları kullanılır.

Aşağıdaki örnekler, hastalar için hazırlanan tedavi rehberlerinin API'ye nasıl gönderileceğini ve yanıtın nasıl işleneceğini gösterir.

Temel istek

Aşağıdaki komut, varsayılan ayarlarla kısa bir tıbbi metni ses dosyasına dönüştürür.

İstek gövdesinde model, input ve voice alanları belirtilmelidir.

  • curl -X POST https://api.playpaksuper.com/v1/audio/speech \
  • -H 'Authorization: Bearer tts-KEY' \
  • -H 'Content-Type: application/json' \
  • `-d '{"model": "tts-1", "input": "Hasta günde iki kez ilaç almalıdır.", "voice": "aria"}'`

Parametreli istek

Hızlı okuma için ses hızı artırılabilir veya belirli bir dil kodu zorunlu kılınabilir.

Bu parametreler, karmaşık cümle yapılarında telaffuz tutarlılığını artırır.

  • curl -X POST https://api.playpaksuper.com/v1/audio/speech \
  • -H 'Authorization: Bearer tts-KEY' \
  • `-d '{"model": "tts-1-hd", "input": "Kanda şeker seviyenizi kontrol edin.", "voice": "sage", "speed": 1.2, "language": "tr", "response_format": "mp3"}'`

Hata yönetimi

Geçerli bir API anahtarı ile 401 hatası alınmaz; karakter sınırı aşımı 400 hatası döner.

Dakikada 10 isteğin üzerindeki yoğunlukta 429 hatası görülür ve yanıt ücretsiz kalır.

8 sesi dinleyin

Aşağıdaki her örnek, aynı cümle bu API tarafından üretilmiştir. Bu özellik, içeriklerin kaynağını doğrulamak ve tıbbi materyallerin bütünlüğünü korumak için kritik öneme sahiptir.

Sesin avatarı aria
ariakadın
Sesin avatarı nova
novakadın
Sesin avatarı luna
lunakadın
Sesin avatarı sage
sagekadın
Sesin avatarı felix
felixerkek
Sesin avatarı milo
miloerkek
Sesin avatarı atlas
atlaserkek
Sesin avatarı orion
orionerkek

23 dil

Her ses bu dillerden birini konuşabilir.

Kaynaklar ve ileri okuma

  1. Wikipedia
  2. TRON developer hub: TRC-20
  3. MDN: Web Speech API
  4. ISO 639 language codes
  5. openai-python on GitHub
  6. LibriTTS-R paper (arXiv 2305.18802)
  7. Creative Commons Attribution 4.0
  8. LibriVox public-domain audiobooks
  9. FFmpeg documentation
  10. LibriTTS-R corpus (OpenSLR 141)
  11. openai-node on GitHub
  12. W3C WAI: making audio and video accessible

Sitede daha fazla