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.mp3Python (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 | |
|---|---|
aria | kadın |
nova | kadın |
luna | kadın |
sage | kadın |
felix | erkek |
milo | erkek |
atlas | erkek |
orion | erkek |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
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
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
İ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
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
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ı
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ı
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.

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
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
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.
23 dil
Her ses bu dillerden birini konuşabilir.
Kaynaklar ve ileri okuma
- Wikipedia
- TRON developer hub: TRC-20
- MDN: Web Speech API
- ISO 639 language codes
- openai-python on GitHub
- LibriTTS-R paper (arXiv 2305.18802)
- Creative Commons Attribution 4.0
- LibriVox public-domain audiobooks
- FFmpeg documentation
- LibriTTS-R corpus (OpenSLR 141)
- openai-node on GitHub
- W3C WAI: making audio and video accessible
