TTS API Entegrasyonu: OpenAI SDK ile Metinden Ses Üretimi

Yazan SesArayüzü editör ekibi · Güncellendi 2026-11-19

Bu dokümantasyon, sesli asistanlar ve sohbet botları geliştiren bağımsız yazılımcılar için TTS API entegrasyonunu adım adım açıklar. Metinden ses üretme sürecini, OpenAI SDK’sını kullanarak nasıl yöneteceğinizi ve API endpoint’lerini nasıl yapılandıracağınızı öğrenin.

Kimlik doğrulama, istek alanları, ses formatları ve hız limitleri gibi teknik detayları bulabilirsiniz. Başarısız isteklerde karakter sınırı ve hata kodları hakkında da bilgi alın. Sayfa, API’nin temel işleyişini ve entegrasyon adımlarını net bir şekilde anlatır.

TTS API Entegrasyonu: OpenAI SDK ile Metinden Ses Üretimi

Sıkça sorulan sorular

API nasıl çalışır?

Metin göndererek JSON formatında istek yaparsınız. API, belirtilen parametrelere göre ses dosyasını üretir ve yanıt olarak döndürür. Uzun metinler için 4096 karakterlik parçalara bölme ve birleştirme işlemi gerekir. İstekler sırayla işlenir; yüksek yük altında kuyrukta bekleme süresi oluşabilir. Gerçek zamanlı akış (streaming) desteği bulunmamaktadır.

Hangi endpoint'ler var?

Ana ses üretimi için POST /v1/audio/speech endpoint'i kullanılır. Mevcut sesler, diller, formatlar ve fiyat bilgileri için GET /v1/voices endpoint'i erişime açıktır. Model listesi için GET /v1/models endpoint'i kullanılabilir. Tüm istekler https://api.rip3.info/v1 baz URL'i üzerinden yapılır.

Kimlik doğrulama nasıl yapılır?

İstek başlıklarında Authorization: Bearer tts-... formunda API anahtarı belirtilmelidir. Her hesap için tek aktif anahtar vardır. Yeni anahtar oluşturulduğunda eski anahtar anında geçersiz olur. Anahtarı güvenlik duvarı arkasında tutmanız ve isteklerinize eklemeniz yeterlidir. Anahtar eksik veya hatalı ise istek reddedilir.

OpenAI SDK kullanabilir miyim?

Evet, istek yapısı OpenAI speech endpoint'iyle aynıdır. Resmi OpenAI SDK'larını kullanarak entegrasyon kurabilirsiniz. Tek yapmanız gereken base_url değerini kendi API adresinize yönlendirmektir. Bu sayede mevcut OpenAI kod yapısını doğrudan kullanabilir ve minimum kod değişikliği ile ses üretimini başlatabilirsiniz.

Base URL nasıl değişir?

OpenAI SDK yapılandırmasında base_url parametresini https://api.rip3.info/v1 olarak ayarlamanız gerekir. Bu ayar, API'nin tüm isteklerini doğru sunucuya yönlendirir. Diğer parametreler (model, voice, input) standart şekilde iletilir. Bu yapı, OpenAI SDK'sının varsayılan davranışını bozmadan API'mize bağlanmanızı sağlar.

Hangi ses formatları desteklenir?

mp3, wav, opus, flac ve pcm formatları desteklenir. response_format parametresi ile istediğiniz formatı belirtebilirsiniz. İstenen format, üretilen ses dosyasının kodlama biçimini belirler. Tüm formatlar aynı kalitede üretilir, sadece dosya boyutu ve uyumluluk değişir. Varsayılan format genellikle mp3'tür.

Dakikada kaç istek yapabilirim?

Kullanım limiti dakikada 60 istektir. İlk yükleme yapılmadan önce bu limit dakikada 10 istek olarak düşer. Bu limit, hesabınızdaki aktif API anahtarı başına geçerli olur. Limit aşıldığında istekler reddedilir veya kuyruğa alınabilir. Yüksek trafikli uygulamalar için limit yönetimi önemlidir.

Hata durumunda ne olur?

Sentez işlemi başarısız olursa istek ücretsiz sayılır. Giderilen karakter kredisi iade edilir. Yanıt kodu ve hata mesajı döndürülür. Bu durum, sunucu yoğunluğu veya geçici sorunlar nedeniyle oluşabilir. Hatalı isteklerde bakiyenizden herhangi bir düşüş yaşanmaz.

Başarısız istekler ücretsiz mi?

Evet, sentez başarısız olursa ücret iade edilir. Karakter kredisi tam olarak geri yüklenir. Bu, API'nin güvenilirliğini artırır. Sadece başarılı ve tamamlanan sentez işlemlerinden ücret alınır. Hata durumlarında kullanıcı bakiyesinden herhangi bir kayıp yaşanmaz.

Hangi modeller mevcut?

tts-1 ve tts-1-hd modelleri mevcuttur. Her iki model de aynı motoru kullanır ve aynı fiyattadır. tts-1-hd genellikle daha yüksek kalite sunar. Model seçimi, ses kalitesi tercihine bağlıdır. Her iki model de tüm sesler ve dillerle uyumludur.

Model nasıl seçilir?

request body içinde model alanına tts-1 veya tts-1-hd değerini yazın. Her iki model de aynı fiyat ve kalite altyapısını paylaşır. tts-1-hd daha yüksek çözünürlük sağlar. İhtiyacınıza göre seçim yapabilirsiniz. Farklı model parametreleri gerekmez.

Input alanı ne kadar karakter destekler?

Her istek maksimum 4096 karakter destekler. Bu karakterler boşlukları ve noktalama işaretlerini de içerir. Daha uzun metinler için client tarafında bölme yapılmalıdır. Parçalar ayrı ayrı isteklerle üretilir ve sonradan birleştirilir. Karakter sınırı aşıldığında hata döndürülür.

Voice parametresi ne işe yarar?

Seslendirme için kullanılacak ses preset'ini belirler. 8 farklı ses seçeneği mevcuttur: aria, nova, luna, sage, felix, milo, atlas, orion. Bu parametre, metnin hangi ton ve tarzda okunacağını belirler. Sesler, metnin diline ve anlamına göre uyarlanır.

Hız parametresi nasıl çalışır?

speed parametresi 0.25 ile 4.0 arasında değer alır. Varsayılan hız 1.0'dır. Değer arttıkça ses daha hızlı, azaldıkça daha yavaş okunur. Bu parametre, sesin doğal akışını korurken okuma hızını ayarlamanızı sağlar. 0.25 en yavaş, 4.0 en hızlı hıza karşılık gelir.

İlk istek

curl

curl https://api.rip3.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.rip3.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.rip3.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 Endpoint Yapısı

İçin ses dalga görseli: API Endpoint Yapısı

API’niz, metni ses dosyasına dönüştürmek için standart bir REST mimarisini takip eder. Temel işlevsellik POST /v1/audio/speech endpointi üzerinden sağlanırken, mevcut seçenekleri keşfetmek için GET /v1/voices ve GET /v1/models uç noktaları kullanılır.

POST /v1/audio/speech

POST /v1/audio/speech

Bu endpoint, JSON formatında gönderilen metni işleyerek ses dosyasını döndürür. İstek gövdesinde model, input metni, ses ayarı ve dil parametreleri yer alır. Metin 4096 karakteri geçmemelidir; daha uzun metinler için bölme işlemi gerekir.

  • Endpoint: https://api.rip3.info/v1/audio/speech
  • Yöntem: POST
  • Girdi: JSON body (model, input, voice vb.)

GET /v1/voices

GET /v1/voices

Erişilebilir sesler, desteklenen diller ve formatlar hakkında bilgi almak için kullanılır. Bu uç nokta, mevcut 8 ses presetini ve 23 dili listeler. Bu sayede API'nin desteklediği dil kodlarını doğrulayabilirsiniz.

GET /v1/models

Mevcut model yapılandırmasını sorgulamak için kullanılır. tts-1 ve tts-1-hd modellerinin teknik detaylarını ve fiyatlandırma eşdeğerliğini buradan teyit edebilirsiniz.

Kimlik Doğrulama

İçin ses dalga görseli: Kimlik Doğrulama

API'ye erişim, istek başlığındaki Authorization: Bearer tts-... formuyla sağlanır. Her hesap için tek bir aktif anahtar bulunur; bu anahtar, OpenAI SDK'larının base_url ayarıyla doğrudan çalışır.

Kimlik doğrulama, güvenli bir bağlantı üzerinden yapılan her POST veya GET isteğinde geçerlidir. Anahtarın geçerliliği, sunucu tarafında anlık olarak kontrol edilir.

Bearer token

Kimlik doğrulama, HTTP başlığında Authorization: Bearer tts-<api-key> formatında iletilir. Bu yapı, standard REST API erişimini sağlar ve SDK'larla uyumludur.

  • Anahtar, tts- ön ekiyle başlar.
  • Her istekte başlıkta gönderilmelidir.

API anahtarı

API anahtarı, /get-api-key/ sayfasında görüntülenir. Tek bir anahtar ile hem okuma hem yazma işlemleri yapılabilir. Anahtar, hesap bakiyesi ve kullanım limitleriyle ilişkilidir.

  • Anahtar, güvenli bir şekilde saklanmalıdır.
  • Anahtar değiştirildiğinde eski hemen geçersiz olur.

Tek anahtar yönetimi

Hesapta yalnızca bir aktif anahtar bulunur. Yeni bir anahtar oluşturulduğunda, önceki anahtar anında sonlandırılır. Bu durum, anahtarın çalınması veya yanlış kullanılması durumunda güvenliği artırır.

  • Anahtar yenileme anlıktır.
  • Eski anahtar hemen kullanılamaz hale gelir.

İstek Alanları

İçin ses dalga görseli: İstek Alanları

API’nin çekirdeği, gönderilen JSON yapısı ve beklenen response formatıdır. Her istek, model, metin, ses ve dil gibi temel alanları içermelidir. Bu alanlar, ses dosyasının nasıl üretileceğini ve hangi dilde konuşulacağını belirler.

Model seçimi

İki model mevcuttur: tts-1 ve tts-1-hd. Her ikisi de aynı motoru kullanır ve fiyatlandırma aynıdır. HD modeli, daha yüksek kalite sunar ancak teknik fark sadece çıktı kalitesidir.

Input metin

Gönderilecek metin input alanına yazılır. Bir istekte maksimum 4096 karakter gönderilebilir. Boşluklar ve noktalama işaretleri karakter sayısına dahildir. Daha uzun metinler için client tarafında bölme ve birleştirme yapılmalıdır.

Voice parametresi

Sesli asistanlar için uygun 8 ses vardır. Female: aria, nova, luna, sage. Male: felix, milo, atlas, orion. Her ses tüm dilleri destekler. İsteğe bağlı language alanı ile dil belirtilebilir, aksi takdirde script'e göre tahmin edilir.

Curl Örneği

İçin ses dalga görseli: Curl Örneği

Ses dosyasını doğrudan terminalde test etmek için curl komutu en hızlı yoldur. Aşağıdaki örnek, tts-1 modeliyle Türkçe metni nova sesiyle MP3 formatında üretir. Başarılı bir istek, binary audio verisini stdout'a yazar.

Temel istek

Komut, API anahtarınızı header'a ekler ve isteği https://api.rip3.info/v1/audio/speech adresine gönderir. --silent bayrağı, indirme çubuğunu gizler; --output ile dosyayı kaydedin.

Parametreler

Metin 4096 karakteri geçmemelidir. voice alanı için aria, nova, luna, sage, felix, milo, atlas veya orion kullanılabilir. model olarak tts-1 veya tts-1-hd seçilebilir.

  • Authorization: Bearer YOUR_API_KEY
  • model: tts-1
  • voice: nova
  • input: "Merhaba, dünya!"
  • response_format: mp3

JSON yapısı

İstek gövdesi, OpenAI SDK ile uyumlu standart bir JSON nesnesidir. speed parametresi 0.25 ile 4.0 arasında değişir. language kodu belirtilmezse, metnin script'inden varsayılan olarak İngilizce varsayılır.

OpenAI SDK Uyumluluğu

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

API'niz OpenAI Speech endpoint'inin istek yapısını birebir taklit ettiği için, mevcut OpenAI SDK'larını (Node.js, Python vb.) doğrudan kullanabilirsiniz. Tek gereken, SDK'nın base_url değerini https://api.rip3.info/v1 olarak ayarlamaktır. Bu sayede ekstra bir wrapper veya özel kütüphane yazmanıza gerek kalmaz.

Kullanıcılar, standart OpenAI istek şemasını (model, input, voice, response_format) aynen aktararak çalışmaya başlar. Bu uyumluluk, mevcut projelerinizdeki API entegrasyonlarını değiştirmeden SesArayüzü altyapısına geçişi hızlandırır.

Base URL değiştirme

SDK konfigürasyonunda base URL'i https://api.rip3.info/v1 olarak belirtmeniz yeterlidir. Bu basit yapılandırma değişikliği, tüm isteklerin doğru sunucuya yönlendirilmesini sağlar. API anahtarınızı (tts-...) standart Authorization header'ı ile gönderdiğinizde, SDK bu değişikliği otomatik olarak işler.

Aynı request şekli

İstek gövdesi (JSON body), OpenAI Speech endpoint'indekiyle aynı alanları içerir: model (tts-1 veya tts-1-hd), input (4096 karaktere kadar metin), voice ve response_format. Parametre isimleri ve veri yapıları birebir eşleştiği için mevcut kod parçacıklarınızda büyük bir değişiklik yapmanıza gerek kalmaz.

Resmi SDK desteği

SesArayüzü, OpenAI'nin resmi SDK'larını (node, python, vb.) doğrudan destekler. Kendimize ait özel bir SDK yayınlamıyoruz; geliştiriciler, endüstri standardı olan OpenAI kütüphanelerini kullanarak hem basit hem de güvenilir entegrasyonlar kurabilirler. Bu sayede SDK güncellemelerini takip etme yükü de minimize edilir.

OpenAI SDK Uyumluluğu

Ses Formatları

İçin ses dalga görseli: Ses Formatları

Ses dosyası formatını response_format parametresi ile belirtin. MP3, WAV, OPUS, FLAC ve PCM desteklenir.

Her format farklı kullanım senaryoları için optimize edilmiştir. Ses kalitesi ve dosya boyutu ihtiyaçlarınıza göre seçin.

MP3 formatı

Genel kullanım için en uygun seçenektir. Dosya boyutları küçüktür ve neredeyse tüm platformlarda desteklenir.

Konuşma asistanları ve web uygulamaları için idealdir. Hızlı yükleme ve düşük bant genişliği gerektirir.

WAV formatı

Kayıpsız ve yüksek kalite sunar. İşleme sırasında ek dönüşüm gerektirmez.

Profesyonel ses düzenleme veya yerel oynatma için uygundur. Dosya boyutları MP3'e göre daha büyüktür.

OPUS ve FLAC

OPUS, düşük bant genişliğinde yüksek kalite sağlar. FLAC ise tam kayıtsız kalite sunar.

Her iki format da modern web teknolojileri ve profesyonel arşivleme için seçilmiştir.

Hız Limitleri

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

Dakikada 60 istek limiti, API anahtarınızın eşzamanlı işleyebileceği maksimum hacmini belirler. Bu sınır, sunucuların aşırı yüklenmesini önler ve stabil bir deneyim sunar. Her hesap için tek bir aktif anahtar kullanılır; bu da limitin net ve takip edilebilir olmasını sağlar.

Dakikada 60 istek

Rate limiti dakikada 60 istektir. İlk yükleme yapılmadan önce bu oran dakikada 10'a düşer. Bu kısıtlama, API anahtarı başına geçerlidir ve birden fazla uygulama için ortak bir bütçe niteliğindedir.

  • Dakikada 60 istek (yüklemeli)
  • Dakikada 10 istek (ilk dönem)

Kuyruk yönetimi

İstekler sırayla işlenir. Yoğun dönemlerde ses üretim işlemi için kuyruğa alınabilirler. Bu durum, özellikle uzun metinlerde veya yüksek trafikte beklemeye neden olabilir.

Eş zamanlı işleme

Sistem, istekleri ardışık olarak işler. Paralel bağlantılar aynı kuyruk içinde değerlendirilir. Bu mimari, kaynak verimliliğini artırır ancak anlık yanıt süresini etkileyebilir.

Hata Kodları

İçin ses dalga görseli: Hata Kodları

API hataları, sunucu tarafındaki geçici sorunlar veya istek parametrelerindeki eksiklikler nedeniyle oluşabilir. Başarısız bir sentez isteğinde, harcanan karakter kredisi tamamen iade edilir; bu nedenle geçici hatalarda tekrar denemek güvenlidir.

Başarısız istek

Sentez sırasında sunucu hatası alırsanız, ilgili karakter kredisi hesabınıza geri yüklenir. Bu durum, geçici yüklenme veya ağ sorunlarında beklenen bir davranıştır.

Karakter sınırı

Her istek maksimum 4096 karakteri aşamaz. Bu sınırı aşan metinleri göndermek için metni parçalara bölüp ses dosyalarını birleştirmeniz gerekir. Boşluklar ve noktalama işaretleri karakter sayısına dahildir.

Geçersiz model

Desteklenen modeller yalnızca tts-1 ve tts-1-hd'dir. Yanlış model kodu gönderilmesi durumunda istek reddedilir ve hata döndürülür. Diğer model isimlerini kullanmayın.

8 sesi dinleyin

Aşağıdaki her örnek, aynı cümle bu API tarafından üretilmiştir. Doğru dil algılaması, özellikle çok dilli sohbet botları için kritik öneme sahiptir.

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. FFmpeg documentation
  3. LibriTTS-R corpus (OpenSLR 141)
  4. curl documentation
  5. W3C WAI: making audio and video accessible
  6. openai-node on GitHub
  7. Node.js documentation
  8. Tether (USDT)
  9. openai-python on GitHub
  10. MDN: Web Speech API
  11. OpenAI API reference: create speech
  12. Creative Commons Attribution 4.0

Sitede daha fazla