Metin Seslendirme API'si Kullanım Kılavuzu

Yazan MetinSes Ajans editör ekibi · Güncellendi 2026-11-19

Bu dokümantasyon, Metin Seslendirme API'mizi projelerinize entegre etmeniz için gerekli tüm teknik detayları içerir. Ajanslar ve eğitim departmanları için tasarlanan bu arayüz, kısa video kliplerden uzun e-öğrenme modüllerine kadar metinlerinizi yüksek kaliteli sese dönüştürmenizi sağlar. OpenAI SDK uyumlu yapısı sayesinde mevcut altyapınızda hızlıca çalışmaya başlayabilirsiniz.

Sayfada; API anahtarınızı alma, ilk isteği gönderme, ses ve dil parametrelerini yapılandırma gibi adımları adım adım bulacaksınız. Ayrıca çıktı formatları, hata yönetimi ve kullanım limitleri hakkında net bilgilerle entegrasyon sürecinizi hızlandıracaksınız. Teknik ekibinizin ihtiyaç duyacağı tüm örnekler ve kod parçacıkları burada yer almaktadır.

Metin Seslendirme API'si Kullanım Kılavuzu

Sıkça sorulan sorular

API anahtarını nasıl alırım?

Anahtarınızı /get-api-key/ sayfasında Google veya e-posta ile kayıt olarak alabilirsiniz. Hesabınız oluşturulduktan sonra panelde tek bir aktif anahtarınız görünür. İstediğiniz zaman yeni anahtar oluşturarak eskisini anında devre dışı bırakabilirsiniz. Anahtar, isteklerde Authorization başlığı altında Bearer token olarak kullanılmalıdır.

Hangi SDK'ları destekliyorsunuz?

Resmi SDK'mız bulunmamaktadır. Ancak API isteğiniz OpenAI speech endpoint ile aynı şekildedir. Bu nedenle OpenAI SDK'larını kullanabilirsiniz. Base URL'i https://api.8059.info/v1 olarak değiştirip kendi API anahtarınızı yapılandırmanız yeterlidir. Standart HTTP isteklerini de doğrudan POST yöntemiyle gönderebilirsiniz.

Hangi sesler mevcut?

Sekiz hazır ses preseti mevcuttur: Aria, Nova, Luna, Sage (kadın); Felix, Milo, Atlas, Orion (erkek). Sesler, CC BY 4.0 lisanslı LibriTTS-R verisinden ve Kamu Malı sesli kitaplardan türetilmiştir. Her ses, 23 desteklenen dilin tamamında konuşabilir. Sesler yapay zeka tarafından üretilir ve görünmez su işareti içerir.

Hangi diller destekleniyor?

23 dil desteklenmektedir: Arapça, Çince, Danca, Felemenkçe, İngilizce, Fince, Fransızca, Almanca, Yunanca, İbranice, Hintçe, İtalyanca, Japonca, Korece, Malayca, Norveççe, Lehçe, Portekizce, Rusça, İspanyolca, Svahili, İsveççe ve Türkçe. Latin alfabesi olmayan metinler için dil kodunu açıkça belirtmeniz önerilir. Vietnamca, Endonezce, Tayca, Ukraynaca, Romence, Çekçe, Bengalce ve diğerleri desteklenmemektedir.

Hangi formatları destekliyorsunuz?

Beş farklı ses formatı desteklenmektedir: mp3, wav, opus, flac ve pcm. İstek JSON gövdesinde response_format alanına istediğiniz formatı yazarak bu seçeneklerden birini belirleyebilirsiniz. Varsayılan bir format belirtilmemiştir, bu nedenle her istekte formatı açıkça belirtmeniz en sağlıklı yöntemdir. Desteklenen formatlar arasında AAC veya M4A bulunmamaktadır.

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

Hız ayarı, istek gövdesindeki speed parametresi ile yapılır. Değer 0.25 ile 4.0 arasında değişebilir. Varsayılan hız 1.0'dır. Daha düşük değerler sesi yavaşlatır, daha yüksek değerler ise hızlandırır. Bu ayar, sesin tonunu veya pitch'ini değiştirmez, sadece okuma hızını etkiler. Ayar, her bir API isteği için geçerlidir.

Uzun metinleri nasıl işlersiniz?

Her istek maksimum 4096 karakter destekler. Daha uzun metinler için metni bu sınırı aşmayacak şekilde parçalara bölmeniz gerekir. Her parça için ayrı bir API isteği gönderip, dönen ses dosyalarını kendi tarafınızda birleştirerek uzun içerikler oluşturabilirsiniz. Bu işlemi yaparken hız ve dil ayarlarının her istekte aynı kalmasına dikkat edin.

Hata kodları nelerdir?

API, standart HTTP hata kodlarını döndürür. Örneğin, 401 yetkilendirme hatası, 429 limit aşımları için kullanılır. Ses sentezi başarısız olursa ücret iade edilir ve hata döndürülür. Belirli bir hata kodu sözlüğü dokümantasyonda yer almaz; ancak genel HTTP standartları takip edilir. İstek başarısız olursa karakter hakkınız düşmez.

Kullanım limitleri nedir?

Anahtar başına dakikada 60 istek gönderme limiti vardır. İlk yükleme yapılmadan önce bu limit dakikada 10 istektir. Dakika başına 60 istek, anahtar başına geçerli bir sınırlamadır. Bu limit, kısa süreli yoğun kullanımlarda kuyruk oluşturabilir. Limit aşıldığında HTTP 429 hatası alırsınız. Sürekli gösteren yüksek hacimli işler için limitleri artırma seçeneği yoktur.

Verilerim güvende mi?

Girdi metniniz sadece ses üretimi için kullanılır ve eğitim verisi olarak kaydedilmez. Üretilen ses dosyası yanıt olarak iletilir ve sunucularımızda saklanmaz. Faturalandırma için istek zamanı, karakter sayısı ve durum bilgisi kaydedilir. Verileriniz üçüncü taraflarla paylaşılmaz. Gizlilik politikamız gereği, metinleriniz işlendikten sonra kalıcı olarak depolanmaz.

API endpoint adresi nedir?

Ana endpoint adresi POST https://api.8059.info/v1/audio/speech şeklindedir. Sesleri listelemek için GET https://api.8059.info/v1/voices endpoint'ini kullanabilirsiniz. Model listesine erişmek için ise GET https://api.8059.info/v1/models endpoint'i mevcuttur. Tüm istekler HTTPS üzerinden şifrelenir ve güvenli bir şekilde iletilir. Base URL olarak api.8059.info/v1 kullanın.

Auth başlığı nasıl olmalı?

Kimlik doğrulama için HTTP Authorization başlığı kullanılır. Değer, 'Bearer' kelimesinden ve boşluktan sonra API anahtarınızın gelmesi şeklindedir: Authorization: Bearer tts-... Anahtarınızı /get-api-key/ sayfasından kopyalayın. Başlık, istek başlıkları arasında yer almalıdır. Yanlış veya eksik anahtar kullanımı 401 Unauthorized hatasına neden olur.

Modeller nelerdir?

İki model mevcuttur: tts-1 ve tts-1-hd. Her iki model de aynı motoru kullanır ve aynı fiyattadır. Aralarındaki fark, altyapı performansında olabilir. İsteğinizde model alanına bu değerlerden birini yazmanız yeterlidir. Varsayılan model belirtilmemiştir, bu nedenle her istekte model adını açıkça belirtmeniz önerilir.

İstekler ne kadar sürer?

Uzun metinlerde ses üretimi yaklaşık gerçek zamanlı hızdadır (saniyede 25 karakter). Kısa cümleler birkaç saniye sürebilir. İstekler sırayla işlendiği için yoğunluk altında kuyrukta bekleme süresi oluşabilir. Ortalama işlem süresi, sunucu yüküne göre değişebilir. Streaming desteği olmadığı için yanıt, ses dosyası tamamen hazır olduğunda döner.

İlk istek

curl

curl https://api.8059.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.8059.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.8059.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ı Alın

İçin ses dalga görseli: API Anahtarı Alın

Metin Seslendirme API'sini kullanmaya başlamak için 8059.info sitesine gidin. Kayıt olurken Google hesabınızla hızlı erişim sağlayabilir veya e-posta ve şifre kombinasyonunu tercih edebilirsiniz. Bu işlem, ajansınız veya eğitim departmanınız için ayrı bir hesap oluşturur.

Kayıt tamamlandıktan sonra /get-api-key/ sayfasına yönlendirilirsiniz. Burada aktif API anahtarınızı görür ve kopyalarsınız. Her hesap için sadece bir aktif anahtar bulunur; yeni bir anahtar oluşturduğunuzda eski anahtar hemen geçersiz olur.

Kayıt Olma

Kayıt Olma

8059.info sitesine giriş yapın. Google ile oturum açmak, ücretsiz deneme kredisini ($0.50) otomatik olarak aktarır. E-posta ile kayıt olanlar kredi ile başlamaz.

Kayıt süreci basittir. Hesap oluşturulduğunda, API anahtarınız ve mevcut bakiyeniz otomatik olarak görüntülenir. Bu adım, entegrasyonunuz için gerekli kimlik doğrulamasının temelini oluşturur.

  • Google ile giriş: Deneme kredisi otomatik aktif olur.
  • E-posta ile giriş: Başlangıç kredisi verilmez.
  • Hesaplar site bazlıdır; her site bağımsızdır.

Anahtarı Kopyalama

Anahtarı Kopyalama

Dashboard'da API anahtarınız "tts-" ile başlar. Bu değeri panonuza kopyalayın. Anahtar, isteklerinizde kimlik doğrulaması için kullanılır.

Anahtar, hesap başına özeldir. İhtiyaç duyarsanız yeni bir anahtar oluşturabilirsiniz. Eski anahtar anında geçersiz hale gelir ve kullanılamaz olur.

  • Anahtar formatı: tts-xxxxxxx
  • Yeni anahtar, eskiyi anında iptal eder.

Güvenlik

API anahtarınızı gizli tutun. İsteklerinizde Authorization başlığı altında Bearer token olarak gönderilir. Anahtarın sızması, bakiyenizin tüketilmesine neden olabilir.

Her istek, anahtarınızla ilişkilendirilir. Kullandığınız anahtarın güvenliğini sağlamak, bakiyenizin korunması açısından kritiktir.

  • Anahtarı kodunuzda veya API çağrılarınızda açıkça kullanın.
  • Gizli anahtar, bakiyenizin güvenliğini sağlar.

İlk API İsteği

İçin ses dalga görseli: İlk API İsteği

Etkinlik sunumlarınız veya e-öğrenme materyalleriniz için metinleri sesli dosyalara dönüştürmek, API'nin temel işlevi olan POST isteği göndermekle başlar. Bu işlem, sunucularımıza metin verisini ve tercihlerinizi iletir.

İlk adım olarak, doğru uç noktasını ve JSON yapısını kullanarak istekinizi hazırlayın. Sistem, metni analiz eder, belirlediğiniz sesi seçer ve sesli dosyayı size iletir.

cURL Örneği

ağ trafiğini hızlıca test etmek için cURL komut satırı aracı idealdir. Aşağıdaki komut, tts-1 modeliyle nova sesini kullanarak basit bir metni seslendirmenizi sağlar.

  • curl -X POST https://api.8059.info/v1/audio/speech \
  • -H "Authorization: Bearer tts-..." \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Merhaba, bu bir test mesajı.", "voice": "nova", "response_format": "mp3"}'

JSON Body

İstek gövdesi, API'nin nasıl davranacağını belirleyen JSON formatında olmalıdır. input alanına seslendirmek istediğiniz metni, voice alanına ise tercih ettiğiniz karakteri yazın. response_format seçeneği dosya türünü (mp3, wav vb.) belirler.

HTTP Metodu

TTS API'si tüm istekler için POST metodunu kullanır. Bu, verilerin sunucuya gönderildiğini ve yeni bir kaynak (ses dosyası) oluşturulduğunu belirtir. GET istekleri genellikle yapılandırma veya ses listesi çekmek için kullanılır.

OpenAI SDK Uyumluluğu

İçin ses dalga görseli: OpenAI SDK Uyumluluğu

API'niz OpenAI Speech endpoint'iyle aynı JSON yapısını kullandığı için, mevcut OpenAI SDK'larını doğrudan entegre edebilirsiniz. Tek gereken, base URL'yi kendi API adresinize yönlendirmektir.

Bu uyumluluk, kütüphane öğrenme sürecini hızlandırır ve mevcut Python veya Node.js kod tabanınızda minimum değişiklik gerektirir.

Base URL Değişikliği

SDK yapılandırmasında base URL'yi https://api.8059.info/v1 olarak ayarlayın. Bu, isteklerin doğru sunucuya ulaşmasını sağlar.

  • Base URL: https://api.8059.info/v1

Kütüphane Yükleme

Standart OpenAI Python veya Node.js paketlerini yükleyin. Ek bağımlılık gerektirmez.

Kod Örneği

Aşağıdaki Python örneği, API anahtarınızı ve metninizi iletilmesini gösterir. Model olarak 'tts-1' veya 'tts-1-hd' kullanılabilir.

Ses ve Dil Parametreleri

İçin ses dalga görseli: Ses ve Dil Parametreleri

API'nizdeki ses ve dil parametreleri, üretilen seslendirmenin tonunu ve anlaşılırlığını doğrudan belirler. Her ses preset'i farklı bir anlatım tarzına sahiptir; örneğin eğitim modülleri için Sage (sakin ve öğretici) veya tanıtım videoları için Felix (enerjik) kullanılabilir.

Dil kodu, metnin doğru telaffuz edilmesi için kritik bir rol oynar. Eğer dil belirtilmezse sistem varsayılan olarak İngilizceyi kullanır; bu nedenle İngilizce olmayan Latin alfabeli metinlerde dil kodunu açıkça belirtmeniz önerilir.

Ses Seçimi

Seçilebilecek sekiz farklı ses preset'i bulunmaktadır. Her biri belirli bir ton ve anlatım tarzına sahiptir. Örneğin, kurumsal eğitimler için Sage veya Nova, belgesel tarzı içerikler için Orion tercih edilebilir.

  • Aria: Sıcak ve net anlatıcı
  • Nova: Parlak ve enerjik
  • Luna: Yumuşak hikaye anlatımı
  • Sage: Sakin ve öğretici
  • Felix: Enerjik promosyon
  • Milo: Samimi ve sohbet havasında
  • Atlas: Nötr ve haber tarzı
  • Orion: Derin ve belgesel tarzı

Dil Kodu

Desteklenen 23 dil arasında Türkçe, İngilizce, Almanca ve Arapça gibi yaygın diller yer alır. Sistem, dil kodu belirtilmediğinde metnin script'inden dili tahmin etmeye çalışır. Ancak Latin alfabeli ancak İngilizce olmayan metinlerde dil kodunu açıkça belirtmek en doğru sonucu verir.

Hız Ayarı

Speed parametresi 0.25 ile 4.0 arasında değişir. Varsayılan hız 1.0'dır. Eğitim materyallerinde anlaşılırlığı artırmak için hızı düşürebilir veya hızlı sunumlar için artırabilirsiniz. Düşük hızlar, özellikle teknik terminoloji içeren metinlerde dinleyici deneyimini iyileştirir.

Çıktı Formatları

İçin ses dalga görseli: Çıktı Formatları

API'den dönen ses dosyaları, kullanım senaryonuza uygun olarak dört farklı dijital formatta sunulur. Her format, ses kalitesi ve dosya boyutu arasında farklı bir denge sağlar.

Kısa video klipler veya web uygulamaları için sıkıştırma gerektiren formatlar, uzun e-öğrenme modülleri için ise yüksek doğruluklu kayıtlar tercih edilebilir.

MP3

Genel kullanım için en yaygın ve uyumlu formattır. Küçük dosya boyutu, neredeyse tüm oynatıcılarla uyumluluk ve yeterli ses kalitesi sunar.

Kısa video klipler, sosyal medya içerikleri veya hızlı prototiplemeler için idealdir.

  • Web ve mobil uyumluluk
  • Düşük bant genişliği gereksinimi
  • Hızlı yükleme süresi

WAV

Kodlamasız, yüksek kaliteli PCM ses verisi sunar. Dosya boyutu MP3'e göre çok daha büyüktür ancak ses kaybı içermez.

Profesyonel ses düzenleme, arşivleme veya post-prodüksiyon süreçlerinde ham veri olarak kullanılmalıdır.

Uzun e-öğrenme modüllerinde ses kalitesi öncelikliyse ve depolama maliyeti kritik değilse tercih edilmelidir.

  • Kayıpsız ses kalitesi
  • Profesyonel düzenleme uyumluluğu
  • Yüksek dosya boyutu

OPUS ve FLAC

OPUS, yüksek kalitede sıkıştırma sağlayan modern bir formattır.

FLAC ise kayıpsız sıkıştırma sunar.

Her iki format da modern web standartlarıyla tam uyumludur ve uzun metinler için verimli depolama imkanı tanır.

  • Modern web standartları
  • Verimli sıkıştırma
  • Esnek kullanım senaryoları
Çıktı Formatları

Hata Yönetimi

İçin ses dalga görseli: Hata Yönetimi

API çağrılarınız sırasında beklenmedik durumlarla karşılaşabilirsiniz. Bu bölümde, HTTP hata kodları, bağlantı süreleri ve kuyruk bekleme durumlarında istemcinizin nasıl davranması gerektiğini açıklıyoruz. Başarısız sentezlerde ücret iadesi otomatik gerçekleşir.

HTTP Hata Kodları

Sunucu, isteğinizin işlenemediğini belirten standart HTTP hata kodlarını döndürür. Örneğin, geçersiz API anahtarı 401, bulunmayan kaynak 404 veya sunucu hatası 500 olarak karşınıza çıkabilir. Hata mesajlarını kontrol ederek isteğinizin neden reddedildiğini anlayabilirsiniz.

Süre Aşımı

Uzun metinler kuyruğa alındığında işleme süresi uzayabilir. İstemciniz bağlantıyı koparabilir; bu durumda istek tamamlanlanmış olabilir de olmayabilir. Güvenli bir yaklaşım, aynı input için yeniden göndermektir çünkü tekrar ücretlendirme yapılmaz.

Limit Aşımı

Dakikada 60 istek limitinizi aştığınızda API, istekleri geçici olarak reddedebilir. Bu durumda istemcinizin kısa bir bekleme süresi uygulaması veya istekleri sıraya alması önerilir. Limit aşımı durumunda da başarısız istekler ücretsizdir.

Kullanım Limitleri

İçin ses dalga görseli: Kullanım Limitleri

API'niz her dakika 60 istek gönderebilir; yeni hesaplar ilk yükleme yapılana kadar bu limiti 10'a düşürür. Uzun metinler için client tarafında 4096 karakterlik parçalara bölme ve birleştirme sorumluluğu size aittir.

Dakikada İstek

Her API anahtarı için dakikada 60 istek limitiniz vardır. Hesabınız henüz aktif edilmediyse (ilk yükleme bekleniyorsa), bu limit dakikada 10 istek olarak düşer.

Metin Uzunluğu

Tek bir API çağrısında işlenebilecek maksimum metin uzunluğu 4096 karakterdir. Daha uzun içerikler (örneğin uzun e-öğrenme modülleri) için metni bu sınıra göre parçalara bölüp her parçayı ayrı istekle göndermeniz gerekir. Sonuçta elde edilen ses dosyalarını birleştirmek geliştirici sorumluluğundadır.

Kuyruk Bekleme

İstekler sırayla işlenir. Yüksek trafik anlarında, özellikle uzun metinler için kuyrukta bekleme süresi oluşabilir. Kısa cümleler genellikle birkaç saniyede, uzun metinler ise gerçek zamanlı hızda (saniyede yaklaşık 25 karakter) işlenir.

Veri Güvenliği

İçin ses dalga görseli: Veri Güvenliği

Gönderdiğiniz metinler yalnızca ses dosyasını üretmek için kullanılır ve eğitim verileri olarak eğitim amaçlı kullanılmaz. API anahtarınızı güvenli bir yerde tutun; her istekte Bearer token olarak gönderilmelidir. Anahtarınızın dışarıda kalması, bakiyenizin başkaları tarafından kullanılmasına neden olabilir.

Üretilen ses dosyaları yanıt üzerinden iletilir ve sunucularımızda kalıcı olarak saklanmaz. Ancak faturalandırma amacıyla istek zamanı, karakter sayısı ve durumu gibi metadata bilgileri saklanır. Bu veriler yalnızca hesap yönetimi için kullanılır.

API Anahtarı

API anahtarınız, isteklerinizin hangi hesaptan yapıldığını belirler. Anahtarı kopyaladıktan sonra güvenli bir ortamda saklayın. Anahtar birden fazla yerde kullanılıyorsa, birini iptal etmek eski anahtarın anında geçersiz olmasına neden olur.

  • Anahtarı kod içine gömün veya güvenli bir değişkende tutun.
  • Her hesap için yalnızca aktif bir anahtar bulunur.
  • Anahtar değişikliği eski anahtarı anında iptal eder.

İstek Metni

Gönderdiğiniz metinler ses üretimi için kullanılır ve eğitim amaçlı veritabanlarında tutulmaz. Uzun metinleri parçalara ayırarak gönderdiğinizde her parça bağımsız olarak işlenir.

  • Metinler eğitim amaçlı kullanılmaz.
  • Her istek maksimum 4096 karakter olabilir.

Sessiz Su İşareti

Oluşturulan her ses dosyası, dinleyicinin duyamayacağı bir su işareti içerir. Bu su işareti, sesin yapay zeka tarafından üretildiğini gösterir ve telif hakları açısından önemlidir.

8 sesi dinleyin

Aşağıdaki her örnek, aynı cümle bu API tarafından üretilmiştir. Aynı istek yapısı sayesinde kodunuzda büyük değişiklik yapmanıza gerek kalmaz.

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. MDN: Web Speech API
  3. W3C WAI: making audio and video accessible
  4. Node.js documentation
  5. OpenAI API reference: create speech
  6. openai-python on GitHub
  7. IETF RFC 7845: Ogg Opus
  8. openai-node on GitHub
  9. Python documentation
  10. LibriTTS-R paper (arXiv 2305.18802)
  11. curl documentation
  12. ISO 639 language codes

Sitede daha fazla