MasalSes API ile Metinden Sese Dönüşüm Hizmeti

Yazan MasalSes Editör Ekibi · Güncellendi 2026-11-19

Bu sayfa, MasalSes API’sini projelerinize entegre etmek için gerekli teknik detayları içerir. API anahtarınızı almadan ilk cURL isteğinize kadar, SDK uyumluluğundan hata yönetimine kadar tüm adımları adım adım anlatıyoruz. Hedef kitlemiz, masal ve hikaye metinlerini profesyonel ses dosyalarına dönüştüren yayıncılardır.

Burada, metinleri ses dosyalarına dönüştürürken dikkat etmeniz gereken teknik sınırlamaları ve en iyi uygulamaları bulacaksınız. 4096 karakterlik karakter sınırı, hız limitleri ve desteklenen ses formatları gibi konular, üretim süreçlerinizi otomatikleştirirken karşılaşılabilecek zorlukları önceden çözmenize yardımcı olacaktır.

MasalSes API ile Metinden Sese Dönüşüm Hizmeti

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.mp3

Python (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
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 Anahtarı Alma

İçin ses dalga görseli: 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

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ş

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

İçin ses dalga görseli: İ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-hd
  • input: Metin (max 4096 karakter)
  • voice: 8 preset ses seçeneğinden biri
  • response_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

İçin ses dalga görseli: 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

İçin ses dalga görseli: 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

İçin ses dalga görseli: 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.

Hız Limitleri

Hata Yönetimi

İçin ses dalga görseli: 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

İçin ses dalga görseli: 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

İçin ses dalga görseli: 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.

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. Tether (USDT)
  3. MDN: Web Speech API
  4. openai-node on GitHub
  5. Creative Commons Attribution 4.0
  6. ISO 639 language codes
  7. IETF RFC 7845: Ogg Opus
  8. LibriVox public-domain audiobooks
  9. curl documentation
  10. LibriTTS-R corpus (OpenSLR 141)
  11. W3C WAI: making audio and video accessible
  12. Python documentation

Sitede daha fazla