API Dokümantasyonu ve Teknik Detaylar Rehberi

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

Bu dokümantasyon, Truman API’nin temel yapı taşlarını ve entegrasyon adımlarını teknik detaylarıyla açıklar. Hedef kitle; WordPress eklentileri geliştiren yazılımcılar ve içerik üretim süreçlerini otomatize etmek isteyen freelancerlardır. Sayfada, API anahtarınızı almanız, cURL ile ilk isteği göndermeniz ve OpenAI SDK’larını mevcut altyapınıza uyarlamanız için gereken tüm teknik bilgiler yer almaktadır.

Metinleri yüksek kaliteli ses dosyalarına dönüştürmek için gereken parametreler, dil ayarları, hız kontrolü ve hata yönetimi konuları adım adım ele alınmıştır. Ayrıca, karakter sınırları, hız limitleri ve sık karşılaşılan entegrasyon sorunlarının çözüm yolları da bu rehberde detaylandırılmıştır. Amacımız, API’nizi minimum kod satırıyla iş akışlarınıza entegre etmenizi sağlamaktır.

API Dokümantasyonu ve Teknik Detaylar Rehberi

Sıkça sorulan sorular

API'yi nasıl kullanmaya başlarım?

Önce /get-api-key/ sayfasından hesap oluşturun. Google veya e-posta ile kayıt olun. API anahtarınızı alın. POST https://api.trumani.net/v1/audio/speech endpoint’ine JSON body gönderin. Authorization header’ına Bearer token’ınızı ekleyin. Metin, model ve ses parametrelerini belirleyin. İstek başarılı olduğunda binary ses dosyasını döndürürüz. Başlangıç için hazır curl örneğini panelinizde bulabilirsiniz.

Hangi SDK'ları destekliyorsunuz?

Resmi SDK’miz yoktur. OpenAI SDK’larını kullanabilirsiniz. base_url’i https://api.trumani.net/v1 olarak ayarlayın. API anahtarınızı yapılandırın. Diğer istemci kütüphaneleri de standard HTTP ile çalışır. Özel bir mobil SDK veya WordPress eklentisi bulunmamaktadır. Doğrudan HTTP istekleri veya OpenAI uyumlu kütüphaneler önerilir. Geriye dönük uyumluluk için endpoint yapısı OpenAI speech endpoint’ine benzer.

OpenAI SDK ile uyumlu musunuz?

Evet, istek şekli OpenAI speech endpoint’ine benzer. base_url’i api.trumani.net/v1 olarak değiştirin. Model adları tts-1 ve tts-1-hd’dir. Parametreler input, voice, response_format ve speed’dir. OpenAI SDK’sının Python veya Node.js sürümlerini doğrudan kullanabilirsiniz. Auth header’ı Bearer token formatındadır. Bu yapı, mevcut OpenAI entegrasyonlarınızı kolayca yönlendirmenizi sağlar.

Dil kodu nasıl belirtilir?

İsteğin JSON body’sine language alanını ekleyin. ISO 639-1 dil kodunu kullanın (örneğin tr, en, de). Dil belirtilmezse sistem script’e göre tahmin yapar. Latin alfabesi varsayılan olarak İngilizce olarak algılanır. Non-English Latin metinler için dil kodunu açıkça belirtin. Desteklenen diller listesindeki 23 dildir. Yanlış dil kodu kullanımı hata döndürmez ancak yanlış ses üretimi olabilir.

Ses dosyası formatı nasıl seçilir?

response_format parametresini kullanın. Desteklenen formatlar: mp3, wav, opus, flac, pcm. İsteğinizin body’sine bu alanı ekleyin. Format seçimi dosya boyutunu ve kaliteyi etkiler. PCM formatı ham veriyi döndürür. FLAC kayıpsız sıkıştırma sağlar. İstenilen formatı belirterek çıktıyı ihtiyacınıza göre optimize edin.

Hız parametresi ne işe yarar?

Speed parametresi sesin okuma hızını ayarlar. Değer aralığı 0.25 ile 4.0 arasındadır. Daha yüksek değerler daha hızlı okuma yapar. Daha düşük değerler daha yavaş ve net okuma sağlar. Bu parametre, metnin dinleyiciye uygun hızda iletilmesi için kullanılır. Ses kalitesini etkilemez, sadece zamanlamayı değiştirir. 0.25’ten düşük veya 4.0’dan yüksek değerler kabul edilmez.

Rate limit aşıldığında ne olur?

Dakikada 60 istek limiti vardır. İlk yükleme öncesi bu limit 10’dur. Limit aşıldığında HTTP 429 hatası döner. İstekleriniz reddedilir ve karakter harcanmaz. Bekleyip tekrar deneyin. Anahtar başına limit uygulanır. Yeni anahtar çıkarırsanız limit sıfırlanır. Yüksek trafikte istekler kuyruğa alınabilir. Bu durum gecikmeye neden olabilir ancak limit aşılmadıkça çalışır.

Hatalı istekler nasıl işlenir?

Sentez hatası oluşursa tam ücret iade edilir. Hatalı istekler karakter hesabınızdan düşülmez. HTTP hata kodu döner. Body’de hata detayı bulunur. İsteğinizi düzeltip tekrar gönderebilirsiniz. Başarısız istekler ücretsizdir. Bu, deneme yaparken veya hatalı parametrelerle çalışırken maliyetinizi korur. Loglarınızda hata durumlarını takip edin.

Uzun metinler nasıl işlenir?

Maksimum 4096 karakter limitidir. Uzun metinleri parçalara bölün. Her parça için ayrı istek gönderin. Dönen ses dosyalarını kendiniz birleştirin. Bu, programatik bir işlemdir. Ortalama hız gerçek zamanlıdır. Kısa cümleler birkaç saniye sürer. Uzun metinler için parçalama stratejinizi belirleyin. Her parça bağımsız olarak işlenir.

Input formatı nedir?

Input, sentezlenecek metin içeren bir string’dir. JSON body’de input alanına yerleştirin. Maksimum 4096 karakterdir. Boşluklar ve noktalama işaretleri karakter sayısına dahildir. Metin Unicode destekler. Model, voice ve format parametreleriyle birlikte gönderilmelidir. Input alanı zorunludur. Boş metin gönderilmesi hata döndürmez ancak boş ses üretir.

API anahtarı nasıl yenilenir?

Hesap panelinizden yeni anahtar oluşturabilirsiniz. Eski anahtar anında geçersiz olur. Tek aktif anahtar vardır. Güvenlik için düzenli yenileme önerilir. Anahtar /get-api-key/ sayfasında görünür. Yeni anahtar oluşturulduğunda eski kullanım durur. Bu işlem anlıktır. Kesinti yaşamamak için istemcilerinizi güncelleyin. Anahtarlar tts-... formatındadır.

Karakter sınırı var mıdır?

Evet, istek başına 4096 karakterdir. Bu sınır input alanı içindir. Uzun metinler için parçalama gerekir. Karakterler boşlukları ve noktalama işaretlerini içerir. 4096’yı aşan metinler hata döndürmez ancak kısmi işleme neden olabilir. Parçalama stratejinizi bu sınıra göre kurun. Her parça ayrı ücretlendirilir.

Hangi sesler kullanılabilir?

8 preset ses mevcuttur. Kadın: aria, nova, luna, sage. Erkek: felix, milo, atlas, orion. Her ses tüm dilleri destekler. Sesler LibriTTS-R verisinden alınmıştır. Sesler arasında geçiş yapabilirsiniz. Sesler synthetic watermark içerir. Seslerin tonları farklıdır. Örneğin aria sıcak, atlas nötrdür. Ses adlarını API’den sorgulayın.

Dil otomatik algılanıyor mu?

Evet, language alanı boşsa script’e göre tahmin yapar. Latin alfabesi varsayılan olarak İngilizce’dir. Non-English Latin metinler için dil kodu belirtilmelidir. Script’e dayalı tahmin %100 doğru olmayabilir. Kesin sonuç için language parametresini kullanın. Desteklenen 23 dildir. Yanlış tahmin, yanlış dilde ses üretir.

İlk istek

curl

curl https://api.trumani.net/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.trumani.net/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.trumani.net/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

Hızlı Başlangıç

İçin ses dalga görseli: Hızlı Başlangıç

Truman API ile çalışmaya başlamak için önce bir API anahtarı oluşturmanız gerekir. /get-api-key/ sayfasından Google veya e-posta ile hesabınızı oluşturun. Sistem size tekil bir tts-... anahtarı sağlar ve bu anahtarı isteklerinizde doğrulama için kullanırsınız.

API anahtarı alma

API anahtarı alma

Anahtarınızı /get-api-key/ sayfasından elde edin. Her hesap için tekil bir aktif anahtar vardır; yeni bir anahtar oluşturduğunuzda eski anahtar anında geçersiz olur. Bu sayede erişim kontrolünüz her zaman güncel kalır.

İlk cURL isteği

İlk cURL isteği

Basit bir metni sesli dosyaya dönüştürmek için POST https://api.trumani.net/v1/audio/speech endpoint'ine istek atın. Aşağıdaki örnek, 'nova' sesini kullanarak kısa bir İngilizce metni MP3 formatında döndürür:

  • curl -X POST https://api.trumani.net/v1/audio/speech \ -H "Authorization: Bearer tts-xxxxx" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Merhaba dünya.", "voice": "nova", "response_format": "mp3"}'
  • Yanıt olarak binary ses dosyası veya hata içeren JSON döner.

JSON yanıt formatı

Başarılı isteklerde ses dosyası binary olarak, hatalı isteklerde ise hata mesajı içeren JSON döner. Hata durumunda error objesi detaylı açıklama ve hata kodunu içerir. Bu yapı, programatik iş akışlarında hatayı kolayca yakalamanızı sağlar.

OpenAI SDK Entegrasyonu

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

Truman API, OpenAI Speech endpoint’iyle aynı JSON yapısını kullandığı için mevcut OpenAI SDK’larınızı doğrudan entegre edebilirsiniz. Tek gereken, isteklerin gönderileceği base_url değerini kendi API adresinize yönlendirmektir. Bu yaklaşım, özellikle WordPress eklentileri veya freelance yazılım projelerinde kod değişikliğini minimize eder.

base_url değiştirme

SDK yapılandırmasında base_url parametresini https://api.trumani.net/v1 olarak ayarlayın. Bu, SDK’nın istekleri doğru sunucuya iletmesini sağlar ve mevcut kodunuzun büyük kısmını korumanıza olanak tanır.

Kullanım örnekleri

Python veya Node.js SDK’larında openai.OpenAI nesnesi oluşturulurken base_url atanır. Ardından client.audio.speech.create() metodu ile TTS isteği gönderilir. Bu yöntem, hem senkron hem de asenkron akışlarda aynı yapıyı kullanır.

  • Python: openai.OpenAI(base_url="https://api.trumani.net/v1", api_key="tts-...")
  • Node.js: new OpenAI({ baseURL: "https://api.trumani.net/v1", apiKey: "tts-..." })
  • Golang: openai.NewClientWithConfig(...) ile base URL ayarı.

Auth header yapılandırması

Kimlik doğrulama, standart Authorization: Bearer <API_KEY> formatında yapılır. SDK’lar bu header’ı otomatik olarak ekler; ancak custom client’lar kullanıyorsanız header’ı manuel olarak eklemelisiniz. API anahtarınız, hesabınızdaki tek aktif anahtardır.

İstek Parametreleri

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

API'nin temel işlevi, JSON formatında gönderilen metinleri ses dosyalarına dönüştürmektir. İstek gövdesindeki parametreler, üretim kalitesini, dilini ve teknik formatını belirler. Bu parametreler, OpenAI Speech endpoint yapısıyla tam uyumludur.

Doğru model ve format seçimi, hem maliyet hem de dosya boyutu açısından kritiktir. Parametrelerin doğru yapılandırılması, beklenen ses kalitesinin elde edilmesi için gereklidir.

model seçimi (tts-1, tts-1-hd)

İki model seçeneği sunulur: "tts-1" ve "tts-1-hd". Her iki model de aynı motoru kullanır ve fiyatlandırma eşittir.

input metin ve karakter sınırı

Gönderilecek metin "input" alanına yerleştirilir. Maksimum karakter sınırı istek başına 4096 karakterdir. Boşluklar ve noktalama işaretleri de karakter sayısına dahildir. 4096 karakteri aşan metinler, istemci tarafında parçalara bölünmeli ve ses dosyaları birleştirilmelidir.

voice ve response_format

Ses parametresi, 8 farklı presetten birini kabul eder. Desteklenen formatlar mp3, wav, opus, flac ve pcm şeklindedir. Seçilen format, dönen yanıtın MIME türünü belirler.

  • Female: aria, nova, luna, sage
  • Male: felix, milo, atlas, orion
  • Formatlar: mp3, wav, opus, flac, pcm

Dil ve Ses Ayarları

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

API, 23 farklı dili destekler ve metnin scriptine göre otomatik dil tahmini yapar. Latin alfabesiyle yazılmış İngilizce dışı metinler için language parametresini açıkça belirtmeniz önerilir; aksi takdirde varsayılan olarak İngilizce kullanılır.

Sesler, belirli bir dile bağlı kalmadan tüm desteklenen dillerde sorunsuz çalışır. Desteklenmeyen diller (Vietnamca, Endonezca vb.) için hata döndürülür veya varsayılan dil kullanılır.

ISO dil kodu kullanımı

Dil parametresi, ISO 639-1 standart kodları (örn. de, fr, ja) ile belirtilir. Bu alan isteğe bağlıdır ancak dilsel doğruluk için kritiktir.

  • Desteklenen diller: Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish.
  • Belirtilmeyen dilde Latin metinler İngilizce olarak işlenir.

Otomatik dil algılama

API, language parametresi gönderilmediğinde metnin karakter kümesinden dili tahmin eder. Kiril alfabesi Rusya dili için, Hiragana/Japonca karakterleri Japonca için varsayılan olarak kabul edilir.

Ses presetleri listesi

8 farklı ses preseti mevcuttur. Her ses, tüm desteklenen dillerde kullanılabilir.

  • Aria: Sıcak, net anlatıcı (Kadın)
  • Nova: Parlak, enerjik (Kadın)
  • Luna: Yumuşak, hikaye anlatan (Kadın)
  • Sage: Sakin, öğretici (Kadın)
  • Felix: Dinamik, promosyon (Erkek)
  • Milo: Samimi, konuşma dili (Erkek)
  • Atlas: Nötr, haber (Erkek)
  • Orion: Derin, belgesel (Erkek)

Hız ve Performans

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

API, uzun metinlerde yaklaşık gerçek zamanlı üretim oranı sağlar; bu, saniyede üretilen ses süresinin, işlenen karakter sayısının 25'te biri kadar olduğunu gösterir. Kısa cümleler genellikle birkaç saniye içinde tamamlanır, ancak yük altında istekler sıraya alınabilir.

Speed parametresi (0.25-4.0)

Hız parametresi, ses dosyasının oynatma hızını doğrudan etkiler. Değer 0.25 ile 4.0 arasında değişebilir. Bu ayar, anlatımın tempo ayarı için kullanılır ancak üretim süresini orantılı olarak değiştirir.

Gerçek zamanlı üretim oranı

Üretim hızı yaklaşık olarak saniyede 25 karakter metin işler. Bu oran, metnin uzunluğuna göre değişmez; kısa cümlelerde sabit bir başlatma süresi nedeniyle oran daha düşük görünebilir. Kısa metinlerde sabit bir başlatma süresi nedeniyle oran daha düşük görünebilir.

Uzun metinler için bölme stratejisi

Her istek maksimum 4096 karakter ile sınırlıdır. Daha uzun metinler için metni bu sınırı aşmayacak şekilde parçalara bölmelisiniz. Her parça için ayrı bir POST isteği gönderin ve resulting ses dosyalarını birleştirin.

Hız ve Performans

Hata Kodları ve Çözümler

İçin ses dalga görseli: Hata Kodları ve Çözümler

API entegrasyonlarında karşılaşılan temel hata durumlarını ve çözüm yollarını bu bölümde açıklıyoruz. Yanlış yapılandırılmış istekler veya geçici kısıtlamalar genellikle kısa süreli bekleme veya basit bir parametre düzeltmesiyle çözülebilir.

Rate limit hataları

Dakikada 60 istek limitini aştığınızda HTTP 429 hatası alırsınız. Yeni hesaplar için bu sınır ilk yükleme yapılana kadar dakikada 10 istek olarak geçerlidir.

  • Hata kodu: 429 Too Many Requests
  • Çözüm: İstekleriniz arasında kısa bekleme süreleri ekleyin veya limit artışı için hesabınıza bakiye yükleyin.

Geçersiz model veya ses

Desteklenmeyen bir ses adı veya model ID'si gönderdiğinizde HTTP 400 hatası döner. Sadece 'tts-1', 'tts-1-hd' modelleri ve listedeki 8 ses preset'i geçerlidir.

  • Geçerli modeller: tts-1, tts-1-hd
  • Desteklenmeyen sesler için GET /v1/voices endpoint'ini kontrol edin.

Input format hataları

Metin 4096 karakteri aşarsa veya JSON yapısı eksiksiz değilse HTTP 400 hatası alırsınız. Boşluklar ve noktalama işaretleri karakter sayısına dahildir.

  • Maksimum karakter sınırı: 4096
  • Uzun metinleri client-side bölüp birleştirin.

Kullanım Limitleri

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

API anahtarınızın veri akışını kesintisiz sürdürmesi için dakikada 60 istek ile sınırlandırılmıştır. Bu limit, uzun metinlerin bölünerek gönderilmesi durumunda bile toplam istek sayısını kapsar.

Karakter sınırı, istek başına 4096 karakterdir. Boşluklar ve noktalama işaretleri de bu sınıra dahil edilir. Metin bu limitin üzerindeyse, parçalara bölünerek gönderilmelidir.

60 istek/dakika limiti

Her API anahtarı için dakikada 60 istek ile sınırlıdır. Bu limit, aynı anahtarla yapılan tüm istekleri kapsar. Limite ulaşıldığında, istekleriniz sıraya alınır veya 429 hatası döndürülür.

İlk yükleme öncesi 10 istek/dakika

Hesabınızda henüz bakiye yüklenmemişse, dakikada 10 istek ile daha düşük bir hıza sahip olursunuz. Bakiye yüklemeniz ve işlenmesi tamamlandıktan sonra, limit otomatik olarak 60 istek/dakika seviyesine yükselir.

Karakter sınırı detayları

Her istek için maksimum 4096 karakter gönderilebilir. Bu sınır, boşluklar ve özel karakterler dahil olmak üzere metnin toplam uzunluğunu ifade eder. Uzun içerikler için bu sınırı aşmamaya özen gösterin.

Sıkça Sorulan Sorular

İçin ses dalga görseli: Sıkça Sorulan Sorular

Freelancerlar ve WordPress geliştiricileri için tasarlanan Truman API, mevcut web sitenizin iş akışına doğrudan entegre edilebilir. PHP cURL veya HTTP istek kütüphaneleri kullanılarak, metinleri anında sesli dosyalara dönüştürme imkanı sağlanır.

API'nin WordPress ile uyumluluğu

Truman API, standart HTTP protokolü üzerinden çalışır. WordPress temanızda veya özel bir eklentide, PHP cURL kullanarak POST https://api.trumani.net/v1/audio/speech endpoint'ine istek gönderebilir ve dönen ses dosyasını wp_insert_attachment ile içeriğe ekleyebilirsiniz.

Ses dosyalarının ticari kullanımı

API üzerinden üretilen tüm ses dosyaları, kaynak veri seti (LibriTTS-R ve LibriVox) lisans koşulları ve API kullanım şartları doğrultusunda ticari amaçlarla kullanılabilir. Üretilen dosyaların içindeki su işareti, sesin sentetik olduğunu gösterir ancak kullanım hakkını kısıtlamaz.

Karakter sayısı nasıl hesaplanır?

Faturalandırma, karakter sayısına göre yapılır. Boşluklar, noktalama işaretleri ve Türkçe karakterler de dahil olmak üzere gönderdiğiniz metnin toplam karakter uzunluğu esas alınır. Örneğin, 1000 karakterlik bir metin için 0.01 USD ödeme yapılır.

8 sesi dinleyin

Aşağıdaki her örnek, aynı cümle bu API tarafından üretilmiştir. Üretim maliyeti, işlenen metnin uzunluğuna doğrudan bağlıdı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. openai-python on GitHub
  3. ISO 639 language codes
  4. Node.js documentation
  5. LibriTTS-R corpus (OpenSLR 141)
  6. LibriTTS-R paper (arXiv 2305.18802)
  7. Creative Commons Attribution 4.0
  8. IETF RFC 7845: Ogg Opus
  9. W3C WAI: making audio and video accessible
  10. OpenAI API reference: create speech
  11. LibriVox public-domain audiobooks
  12. TRON developer hub: TRC-20

Sitede daha fazla