Sıkça sorulan sorular
API anahtarını nerede bulabilirim?
API anahtarınızı /get-api-key/ sayfasında bulabilirsiniz. Giriş yaptıktan sonra panelde aktif anahtarınız görüntülenir. İsterseniz yeni bir anahtar oluşturabilirsiniz; bu durumda eski anahtar anında geçersiz olur. Her hesap için yalnızca bir aktif anahtar bulunur ve bu anahtarla API'ye erişim sağlanır.
Hangi HTTP metodunu kullanmalıyım?
Ses üretimi için POST metodunu kullanmalısınız. İstekleri https://api.55ff.info/v1/audio/speech adresine gönderin. JSON formatında model, input, voice ve response_format alanlarını belirtin. Ses listesi ve fiyat bilgisi için GET /v1/voices endpoint'ini kullanabilirsiniz. Bu yapı, OpenAI SDK'larıyla uyumludur.
JSON yanıtı nasıl parse edilir?
API, başarılı isteklerde ses dosyasını doğrudan ikili veri (binary) olarak döndürür. Yanıt JSON değil, doğrudan .mp3, .wav veya diğer seçtiğiniz formatın içeriğidir. Bu nedenle yanıtı JSON olarak parse etmeye gerek yoktur. Dosyayı doğrudan kaydedebilir veya bellekte işleyebilirsiniz. Hata durumunda ise JSON döner.
Zaman aşımı süresi nedir?
Belirtilen standart bir zaman aşımı süresi yoktur. Ancak uzun metinler için üretim gerçek zamanlı hızdadır. Kısa cümleler birkaç saniye sürer. Yük altında istekler kuyruğa alınabilir. Bu nedenle, isteklerinizin tamamlanması için yeterli bekleme süresi ayarlamanız önerilir. Başarısız istekler ücretsizdir ve ücret iadesi yapılır.
Ses dosyası boyutu ne kadar?
Dosya boyutu seçilen formata göre değişir. MP3 en küçük, FLAC ve WAV daha büyük dosyalar oluşturur. PCM formatı en yüksek kaliteyi sağlar ancak dosya boyutunu artırır. Ortalama üretim hızı saniyede yaklaşık 25 karakter metin içindir. Bu nedenle daha uzun metinler daha büyük ses dosyaları üretir.
Hangi portlar açık?
API, standart HTTPS protokolü üzerinden 443 portunu kullanarak çalışır. Özel bir port ataması gerekmez. Sadece HTTPS bağlantısı gereklidir. HTTP kullanımı için ek bir yapılandırma gerekmez. İstemcileriniz doğrudan HTTPS endpoint'ine bağlanarak veri alışverişini gerçekleştirebilir. Güvenlik için SSL/TLS şifrelemesi otomatik olarak sağlanır.
SSL sertifikası var mı?
Evet, tüm API bağlantıları SSL sertifikası ile korunur. Verileriniz şifrelenerek iletilir. Bu sayede API anahtarınız ve metinleriniz güvenli bir şekilde aktarılır. Sertifikalar otomatik olarak yönetilir ve güncel kalır. İstemcileriniz herhangi bir özel sertifika yüklemesi yapmadan güvenli bağlantı kurabilir. Bu standart web güvenliği uygulamasıdır.
API versiyon güncellemeleri nasıl?
Mevcut API sürümü v1'dir. Endpoint yapısı sabittir. Yeni özellikler eklendiğinde veya değişiklik yapıldığında bu belgeler güncellenecektir. Geriye dönük uyumluluk korunmaya çalışılır. Ancak büyük değişiklikler için bildirim yapılmayabilir. Mevcut istemcilerinizin çalışmaya devam etmesi beklenir. Herhangi bir kesinti durumunda destek e-postası ile bilgilendirme yapılır.
Rate limit aşıldığında ne olur?
Dakikada 60 istek limiti vardır. Bu limit aşıldığında istekleriniz reddedilir. Yeni bir anahtar oluşturursanız limit sıfırlanır. İlk yükleme öncesi bu limit dakikada 10'dur. Aşım durumunda HTTP 429 hatası döner. Bekleyip tekrar deneyin veya anahtarınızı yenileyin. Limitler hesabınızın kullanım durumuna göre değişebilir. Bu kurallar belirlidir.
Gecikme süresi ne kadar?
Gecikme süresi metin uzunluğuna ve sunucu yüküne bağlıdır. Kısa metinler birkaç saniyede üretilir. Uzun metinler için üretim hızı yaklaşık gerçek zamanlıdır. Yük altında istekler kuyruğa alınabilir. Bu durum gecikmeye neden olabilir. Ortalama olarak saniyede 25 karakter işlenir. Bu nedenle büyük projeler için kuyruk yönetimi önemlidir. Bekleme süresi değişkenlik gösterir.
Test ortamı var mı?
Ayrı bir test ortamı (sandbox) mevcut değildir. Tüm istekler üretim ortamında işlenir. Ancak $0.50 ücretsiz deneme kredisi ile test yapabilirsiniz. Bu kredi 7 gün geçerlidir. Google ile giriş yapanlar bu krediyi alır. Testler sırasında gerçek sesler üretilir ve karakterleriniz kullanılır. Geri ödeme başarılı istekler için yapılmaz.
Webhook desteği var mı?
Webhook desteği şu anda mevcut değildir. Ses üretimi tamamlandığında doğrudan yanıt olarak dosya döner. Uzun metinler için parçalar istemci tarafında birleştirilmelidir. Arka planda webhook gönderilmez. İşlem tamamlanana kadar istemci bağlantısını açık tutmanız gerekir. Şimdilik senkron istekler kullanın. Destek e-posta ile yapılır.
Batch istekleri destekleniyor mu?
Toplu istek (batch) endpoint'i mevcut değildir. Her metin için ayrı bir API çağrısı yapmalısınız. Uzun metinleri parçalara bölüp ayrı ayrı gönderebilirsiniz. Ardından ses dosyalarını birleştirebilirsiniz. Bu yöntem, paralel isteklerle daha hızlı sonuç verebilir. Ancak her istek ayrı ücretlendirilir. Bu, API'nin mevcut tasarımının bir parçasıdır.
Ses kalitesi parametreleri nelerdir?
Kaliteyi model seçerek belirlersiniz. tts-1 ve tts-1-hd modelleri aynı motoru kullanır. Ses hızını 0.25 ile 4.0 arasında ayarlayabilirsiniz. Format seçimi (mp3, wav, opus, flac) kaliteyi etkiler. Dil parametresi ile dil seçimi yapabilirsiniz. Ses tonu veya vurgu gibi ince ayarlar yoktur. Bu parametreler, metnin anlaşılırlığını ve akıcılığını etkiler.
İlk istek
curl
curl https://api.55ff.info/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.55ff.info/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.55ff.info/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 Anahtarı Alma
MasalSes API'sine erişim sağlamak için https://55ff.info/get-api-key/ adresindeki kayıt sayfasını kullanın. Hesap oluşturduktan sonra, hesabınıza özel tek bir aktif API anahtarını yönetme yetkinliğine sahip olursunuz. Bu sayfa, anahtarınızı görüntülemenizi, mevcut bakiyenizi kontrol etmenizi ve kullanım istatistiklerinizi takip etmenizi sağlar.
Kayıt sayfasından erişim
Giriş yaptıktan sonra, API anahtarınız hemen görünecektir. Bu anahtarı güvenli bir yerde saklayın. Her istek için Authorization: Bearer tts-... formatını kullanın.
Google veya e-posta ile giriş
Kayıt olurken Google hesabınızı kullanırsanız, hesabınıza 0,50 $ değerinde ücretsiz deneme kredisi (yaklaşık 50.000 karakter) otomatik olarak eklenir. Bu kredi 7 gün boyunca geçerlidir. E-posta ve şifre ile kayıt olan hesaplar ise başlangıç kredisi almaz.
Tek aktif anahtarı yönetme
Hesabınızda aynı anda yalnızca bir aktif anahtar bulunur. Eski anahtarınızı güvenlik gerekçesiyle iptal ederseniz, yeni bir anahtar oluşturulur ve eski anahtar hemen kullanımdan kalkar. Bu işlem anlıktır, bekleme süresi yoktur.
İlk API İsteği
MasalSes API ile metinden sese dönüşüm sürecini başlatmak için tek bir POST isteği yeterlidir. Girdi olarak metni, hedef sesi ve isteğinizi belirterek ses dosyasını anında alabilirsiniz. Bu yapı, masal ve hikaye metinlerini profesyonel ses dosyalarına dönüştürür.
Aşağıdaki cURL komutu, 'tts-1' modelini kullanarak 'aria' sesinin İngilizce bir cümleyi nasıl okuyacağını test etmenizi sağlar. Yanıt, seçilen formatta (örneğin mp3) binary veri olarak döner.
cURL komutu ile test
Aşağıdaki komutu terminalinize yapıştırarak API'nin doğru çalıştığını doğrulayabilirsiniz. tts-1 modeli standart kalitede, tts-1-hd ise daha yüksek detay sunar. Her iki model de aynı fiyatlandırma ile çalışır.
curl -X POST https://api.55ff.info/v1/audio/speech-H 'Authorization: Bearer tts-...'<br>-H 'Content-Type: application/json'<br>- `-d '{"model": "tts-1", "input": "The quick brown fox jumps over the lazy dog.", "voice": "aria", "response_format": "mp3"}'`
JSON yapısını anlama
İstek gövdesi JSON formatında olmalıdır. model alanı 'tts-1' veya 'tts-1-hd' olabilir. input alanı 4096 karakteri geçmemelidir. voice alanı için 'aria', 'nova', 'luna', 'sage', 'felix', 'milo', 'atlas' veya 'orion' kullanılabilir. speed 0.25 ile 4.0 arasında değişebilir.
model: tts-1 veya tts-1-hdinput: Metin (max 4096 karakter)voice: 8 preset ses seçeneğinden biriresponse_format: mp3, wav, opus, flac, pcm
Yanıt formatını inceleme
Başarılı bir istek, HTTP 200 kodu ve bir ses dosyası döndürür. Dosya, seçilen formatta (örneğin mp3) binary veri olarak gelir. Hatalı isteklerde (geçersiz model veya ses), HTTP hata kodu ve hata mesajı döner.
- Başarılı: 200 OK + Ses dosyası
- Hatalı: 4xx/5xx + Hata mesajı
- Otomatik karakter sayımı
- Hız ayarı uygulaması
OpenAI SDK Uyumluluğu
MasalSes API, OpenAI Speech endpoint ile aynı JSON yapısını kullandığı için resmi OpenAI SDK'larını base_url değişikliği ile kullanabilirsiniz. Bu uyumluluk, geliştirme sürecinizi hızlandırır ve mevcut kütüphane alışkanlıklarınızı korumanızı sağlar.
base_url değişikliği
SDK yapılandırmasında base_url değerini https://api.55ff.info/v1 olarak ayarlayın. Bu adım, isteklerin doğru sunucuya ulaşmasını sağlar ve diğer tüm parametrelerin aynı kalmasını garanti eder.
Mevcut kütüphanelerin kullanımı
Resmi OpenAI SDK'ları, model adı olarak "tts-1" veya "tts-1-hd" ile çalışır. Python veya Node.js gibi ortamlarda standard Speech API çağrılarını doğrudan kullanabilirsiniz.
Doğrulama ayarları
API anahtarınızı standart Bearer token formatında header'a ekleyin. Her istekte Authorization: Bearer <ANAHTAR> başlığını kullanarak yetkilendirme işlemini tamamlayın.
Desteklenen Formatlar
MasalSes API, metinleri çeşitli dijital ses formatlarına dönüştürmenize olanak tanır. İhtiyacınıza uygun formatı seçerek ses dosyalarını doğrudan yanıt olarak alabilirsiniz.
Format seçimi, üretilecek ses dosyasının boyutunu ve kullanılacak bant genişliğini doğrudan etkiler. Her format farklı kullanım senaryoları için optimize edilmiştir.
MP3 ses dosyası
MP3 formatı, ses kalitesi ve dosya boyutu arasındaki dengeli yaklaşımı sağlar. Genel kullanım için uygun bir formattır.
Bu format, web uygulamalarında ve mobil cihazlarda sorunsuz çalışmasını istediğiniz senaryolar için idealdir. Dosya boyutunun küçük olması, indirme sürelerini kısaltır.
- Genel kullanım için uygun seçenek
- Düşük dosya boyutu
- Geniş uyumluluk desteği
WAV yüksek kalite
WAV formatı, kayıpsız ses verisi sunar ve düzenleme süreçlerinde tercih edilir. Profesyonel yayınlar veya ses düzenleme araçları ile çalışırken bu formatı seçebilirsiniz.
Orijinal ses kalitesini korurken daha büyük dosya boyutları oluşturur. Bu durum, depolama alanı veya veri transferi kısıtlamalarınız varsa dikkate alınmalıdır.
- Kayıpsız ses kalitesi
- Ses düzenleme için ideal
- Daha yüksek dosya boyutu
OPUS ve FLAC seçenekleri
OPUS formatı, yüksek sıkıştırma oranı ve iyi ses kalitesi sunar. Özellikle düşük bant genişliği ortamlarında veya mobil uygulamalarda tercih edilebilir.
FLAC formatı, kayıpsız sıkıştırma ile ses kalitesini korurken dosya boyutunu MP3'ten daha verimli yönetir. Her iki format da teknik gereksinimlerinize göre seçilmelidir.
- OPUS: Verimli sıkıştırma
- FLAC: Kayıpsız sıkıştırma
- Özel kullanım durumları
Hız Limitleri
API'nizin saniyelik veri akışı değil, dakikalık istek sayısına dayalı bir hız limitine sahip olduğunu bilmek, üretim planlamanız için kritiktir. Bu limit, sunucuların yüksek kaliteli ses sentezi yapabilmek için yeterli işlem gücünü korumasını sağlar.
Dakikada 60 istek
Her API anahtarı için standart limit dakika başına 60 istektir. Bu, üretim süreçlerinizi buna göre yapılandırmanız gerektiği anlamına gelir.
İlk yükleme öncesi limit
Hesabınız henüz kredi ile yüklenmemişse, dakika başına 10 isteklik bir kısıtlama uygulanır. Bu düşük limit, sistemimizin kaynaklarını korumasını ve yeni kullanıcıların deneyimini kesintiye uğratmamasını sağlar. İlk USDT yüklemenizi yaptıktan sonra limit otomatik olarak 60'a yükselir.
Kuyruk yönetimi
İstekler sırayla işlenir. Özellikle uzun metinler için ses üretimi gerçek zamanlı yakından bir hızdadır; bu nedenle yoğun dönemlerde istekleriniz bir kuyruğa alınabilir. Kısa cümleler için bile birkaç saniye sürebilen işlemler, kuyruk nedeniyle daha uzun sürebilir. Sabırlı bir istek dizisi, en verimli sonucu verir.

Hata Yönetimi
Hata yönetimi, API'nin beklenmedik durumlarda nasıl davrandığını anlamanızı sağlar. Başarısız istekler için ücret alınmaz; tüm tutarlar iade edilir.
Bu bölümde, yayıncılar için kritik olan karakter sınırı ve yapı doğrulama hatalarının nasıl işlendiğini bulacaksınız.
HTTP hata kodları
Sunucu, isteklerinizdeki sorunları standart HTTP hata kodlarıyla belirtir. Örneğin, geçersiz bir anahtar kullanımı 401, sunucu hatası ise 500 döner.
Ödeme sistemi, sentezleme başarısız olduğunda harcanan karakterleri hesabınıza geri ekler. Bu sayede, teknik aksaklıklar bütçenizi etkilemez.
- 400: Yanlış istek formatı veya eksik alanlar.
- 401: Geçersiz veya süresi dolmuş API anahtarı.
- 429: Dakikada 60 istek limitine ulaşıldı.
- 500: Sunucu tarafında beklenmeyen bir hata.
Karakter sınırı hataları
Her istek maksimum 4096 karakteri geçemez. Bu sınır, metinlerin tek seferde işlenebilmesi için tasarlanmıştır.
Bu limitin aşılması durumunda API, isteği reddeder ve karakter başına ücretlendirme yapılmaz. Uzun hikayeler için bölme stratejilerini kullanın.
Geçersiz ses seçimi
Ses listesi (GET /v1/voices) endpoint'inden doğrulanmış 8 ses preset'ini kontrol edin. Desteklenmeyen bir ses adı gönderirseniz istek başarısız olur.
Geçersiz bir ses modeli veya format belirtmek, isteğin hemen reddedilmesine neden olur. Bu durumda da ücret iadesi sağlanır.
- Aria, Nova, Luna, Sage (Kadın)
- Felix, Milo, Atlas, Orion (Erkek)
Uzun Metin İşleme
MasalSes API, tek bir istekle işleyebileceğiniz metin uzunluğunu 4096 karakterle sınırlar. Bu sınır, tek bir API çağrısında üretilebilecek ses dosyasının boyutunu ve işleme süresini belirler. Daha uzun masal kitapları veya hikaye bölümleri için metni bu sınırı aşmayacak şekilde bölmeniz gerekir.
4096 karakter sınırı
Her API isteği maksimum 4096 karakter içerebilir. Boşluklar ve noktalama işaretleri de bu karakter sayısına dahil edilir. Bu nedenle, uzun hikayeleri göndermeden önce metinlerinizi karakter sayısına göre kontrol etmeniz gerekir.
Parçalara bölme stratejisi
Metni parçalara bölerken cümle bütünlüğünü korumaya özen gösterin. Her parça 4096 karakteri geçmemelidir. Bu sayede her parça için ayrı bir API isteği gönderip ses dosyaları üretebilirsiniz.
Ses dosyalarını birleştirme
Her parça için ayrı ayrı üretilen ses dosyalarını, kendi uygulama mantığınızla birleştirmeniz gerekir. MasalSes API, parçalar arasında otomatik bir birleştirme işlemi yapmaz. Parçaları ardışık olarak oynatmak için istemci tarafında veya sunucu tarafında birleştirme işlemi gerçekleştirmelisiniz.
Güvenlik
MasalSes API'si, metinleri ses dosyalarına dönüştürürken veri akışını güvenli bir şekilde yönetir. Geliştiriciler, istekleri doğrulamak ve erişimi kontrol etmek için standart güvenlik protokollerini kullanır. Bu sayede ses üretim süreçlerinizdeki kimlik doğrulama işlemleri şeffaf ve güvenilirdir.
API anahtarlarınızın güvenliği, üretim hatlarınızın sürekliliği için kritiktir. Yanlış kişi veya sistemlerin kullanımını önlemek için basit ama etkili doğrulama mekanizmaları devrededir.
Bearer token doğrulaması
Tüm API istekleri, başlık alanında Authorization: Bearer tts-... formatında bir jeton (token) içerir. Bu jeton, hesabınıza özel tekil kimliğinizi temsil eder ve sunucuya kim olduğunuzu kanıtlar. Jeton, istek URL'sinde veya gövdesinde açıkça görünmez, bu da onu kaptırmayı zorlaştırır.
- Jetona başlık alanına yerleştirin.
- Sadece HTTPS üzerinden iletilir.
API anahtarı gizliliği
Anahtarınızı kopyaladığınızda onu güvenli bir ortamda tutun. Genellikle istemci tarafı kodlarda (tarayıcı içinde) doğrudan kullanılmamalıdır; anahtarı ifşa eden bir hata, isteklerinizin başkası tarafından yapılmasına neden olabilir. Anahtar, hesabınızdaki bakiye ve kullanım limitleri ile doğrudan ilişkilidir.
Tekrar kullanıma kapalı anahtarlar
Güvenlik endişesi duyduğunuzda veya anahtarınızın sızdığını düşündüğünüzde, yeni bir anahtar oluşturabilirsiniz. Eski anahtar anında geçersiz hale gelir; bu durumda eski anahtarla yapılan tüm istekler artık kabul edilmez. Bu özellik, yanlışlıkla paylaşılan anahtarların riskini minimize eder.
8 sesi dinleyin
Aşağıdaki her örnek, aynı cümle bu API tarafından üretilmiştir. Bu durum, hata ayıklama sürecini basitleştirir ve geliştirme hızını artırır.
23 dil
Her ses bu dillerden birini konuşabilir.
