API Dokümantasyonu ve Hızlı Başlangıç Rehberi

Yazan SesReklam Edit editör ekibi · Güncellendi 2026-11-18

Bu sayfa, ses reklam ve radyo spotu üretim süreçlerinizi hızlandırmak için tasarlanmış API’mizin teknik dokümantasyonunu içerir. Hedef kitleniz freelancer reklam üreticileridir; burada metinleri yüksek kaliteli sese dönüştürmek için gerekli endpoint’leri, parametreleri ve entegrasyon yöntemlerini adım adım bulacaksınız.

Sayfada API’nin temel yapısı, kimlik doğrulama yöntemleri, ses ayarları ve format seçenekleri detaylandırılmıştır. Ayrıca OpenAI SDK uyumluluğu, karakter limitleri ve hata yönetimi gibi teknik detaylar, doğrudan kod örneği ve cURL komutları ile açıklanmıştır. Entegrasyon sürecinizi sorunsuz tamamlamanız için gerekli tüm teknik bilgiler burada toplanmıştır.

API Dokümantasyonu ve Hızlı Başlangıç Rehberi

Sıkça sorulan sorular

API endpoint adresi nedir?

Metin okuma için POST isteği https://api.gsbet6688.com/v1/audio/speech adresine gönderilir. Ses listesi ve fiyat bilgisi için GET /v1/voices, model detayları için ise GET /v1/models endpointleri kullanılır. Tüm bu adresler, reklam ve radyo spotu üretimi için gerekli olan API erişiminin temel yapı taşlarını oluşturur.

Hangi kimlik doğrulama yöntemi kullanılır?

Kimlik doğrulama, HTTP başlıklarında Authorization: Bearer tts-... formatında özel anahtar ile sağlanır. Hesap başına yalnızca aktif bir anahtar bulunur. İhtiyaç duyulduğunda yeni bir anahtar oluşturulabilir; bu işlem sırasında eski anahtar anında geçersiz hale gelir. Bu sayede erişim güvenliği sürekli korunur.

JSON body yapısı nasıl olmalıdır?

JSON gövdesi model, input, voice, response_format, speed ve isteğe bağlı language alanlarını içermelidir. model alanı tts-1 veya tts-1-hd olabilir. input alanına okutulacak metin yazılır. voice alanı 8 ses presetinden biri olmalıdır. Bu yapı, OpenAI speech endpoint formatıyla birebir uyumludur.

Hangi sesler desteklenir?

8 farklı ses preseti mevcuttur: Kadın sesler aria, nova, luna ve sage; erkek sesler felix, milo, atlas ve orion. Bu sesler, lisanslı kayıtlara dayanır ve her biri farklı tonlarda (anlatıcı, promosiyon, belgesel vb.) hizmet verir. İstenilen ses, API isteğindeki voice parametresi ile seçilir.

Hız aralığı nedir?

Seslendirme hızı 0.25 ile 4.0 arasında ayarlanabilir. Bu değerler, radyo spotlarının ritmine ve reklam metninin akıcılığına göre esnek kullanım sağlar. Hız parametresi, API isteğindeki speed alanı aracılığıyla belirlenir ve ses dosyasının üretim süresini doğrudan etkiler.

Hangi ses formatları mevcuttur?

Desteklenen ses formatları mp3, wav, opus, flac ve pcm'dir. Bu formatlar, response_format parametresi ile seçilir. İhtiyaç duyulan ses kalitesi ve dosya boyutu bu formatlar arasında değişir. Tüm formatlar, API yanıtında doğrudan audio dosyası olarak döndürülür ve kaydedilebilir.

Rate limit nedir ve nasıl çalışır?

Anahtar başına dakika başına 60 istek limiti vardır. İlk yükleme yapılmadan önce bu limit dakikada 10 istek olarak düşer. Bu limit, API'nin stabil çalışmasını sağlar. Limit aşıldığında istekler reddedilir. Reklam üretimi sırasında yüksek hacimli işlemlerde bu limitin dikkate alınması gerekir.

Karakter sınırı kaçtır?

Her bir API isteğinde maksimum 4096 karakter gönderilebilir. Daha uzun metinler için metin bu sınırı aşmayacak şekilde parçalara bölünmeli ve ses dosyaları ardışık olarak oluşturulmalıdır. Boşluklar ve noktalama işaretleri de karakter sayısına dahil edilir. Bu sınır, tek istek başına geçerlidir.

Hata durumunda ne olur?

Sentez işlemi başarısız olursa, ilgili ücret tam olarak iade edilir. Hata durumunda herhangi bir ücretlendirme yapılmaz. Bu kural, API'nin güvenilirliğini artırır. Hata mesajları, istemci tarafında işlenerek sorunun kaynağı tespit edilebilir. Başarısız istekler, bakiye düşüşüne neden olmaz.

OpenAI SDK ile uyumlu mu?

Evet, API isteği OpenAI speech endpoint formatıyla aynıdır. OpenAI SDK'ları, base_url parametresi https://api.gsbet6688.com/v1 olarak değiştirildiğinde sorunsuz çalışır. Bu uyumluluk, mevcut geliştirme süreçlerini hızlandırır. Ekstra kütüphane kurulumu gerektirmez. Doğrudan mevcut kod yapısını kullanabilirsiniz.

Langauge parametresi nasıl çalışır?

language parametresi isteğe bağlıdır. Belirtilmezse, sistem metnin script'ine göre dili tahmin eder. Latin alfabesiyle yazılmış metinler varsayılan olarak İngilizce olarak kabul edilir. Diğer diller için ISO kodu belirtilmelidir. Desteklenen diller arasında seçim yapılabilir. Yanlış dil algılamasını önlemek için dil kodu verilmelidir.

Ses dosyası nasıl alınır?

API yanıtı, doğrudan ses dosyasını içerir. Bu dosya, istemci tarafında kaydedilebilir. Yanıtın Content-Type başlığı, seçilen response_format'a göre ayarlanır. Dosya, sunucu tarafında depolanmaz ve doğrudan istemciye iletilir. Bu sayede verimlilik artar ve ek depolama maliyeti oluşmaz.

İlk istek

curl

curl https://api.gsbet6688.com/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.gsbet6688.com/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.gsbet6688.com/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

Temel Endpoint

İçin ses dalga görseli: Temel Endpoint

Ses üretim süreçleriniz için temel API noktası POST https://api.gsbet6688.com/v1/audio/speech endpointidir. Metin girdisini göndererek yüksek kaliteli TTS dosyalarınızı oluşturabilirsiniz.

İstekler, OpenAI Speech endpointi ile aynı JSON yapısını kullanır. Bu yapı, mevcut OpenAI SDK'larını doğrudan kullanabilmenizi sağlar.

Speech Endpoint

Speech Endpoint

HTTP POST metodu ile https://api.gsbet6688.com/v1/audio/speech adresine istek gönderin. API, işlenen metne karşılık gelen ses dosyasını döndürür.

Kullanılabilir modeller "tts-1" ve "tts-1-hd" olarak iki seviyede sunulur. Her iki model de aynı motoru kullanır ve fiyatlandırma açısından eşittir.

JSON Body

JSON Body

İstek gövdesi model, input, voice ve response_format alanlarını içermelidir. input alanı karakter sayısını aşmamalıdır.

Opsiyonel olarak speed (0.25–4.0 arası) ve language (ISO kodu) parametrelerini belirleyerek çıktıyı özelleştirebilirsiniz.

  • model: "tts-1" veya "tts-1-hd"
  • input: Okunacak metin (max 4096 karakter)
  • voice: Aşağıda listelenen 8 sesden biri
  • response_format: mp3, wav, opus, flac veya pcm

Auth Header

Kimlik doğrulama, istek başlıklarında Authorization: Bearer tts-... formatında özel API anahtarı ile sağlanır.

Bu anahtarı /get-api-key/ sayfasından alabilirsiniz. Anahtarınızın güvenli olduğundan emin olun.

Kurulum ve Kimlik Doğrulama

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

API'nize erişim sağlamak için öncelikle bir API anahtarı oluşturmanız gerekir. Anahtarınızı almak ve yönetmek için sitenin /get-api-key/ sayfasına giderek Google veya e-posta ile kaydolun. Bu sayfada hem anahtarınızı hem de mevcut bakiyenizi görebilirsiniz.

API Anahtarı

Her hesap için tek bir aktif anahtar bulunur. Bu anahtar, API isteklerinizi kimliklendirmek için kullanılır ve hesabınızın güvenli erişimini sağlar.

Bearer Token

İsteklerinizde HTTP Header alanına Authorization: Bearer tts-... formatında anahtarınızı ekleyin. Bu, sunucunun isteğinizi tanımasını ve işleminizi onaylamasını sağlar.

Anahtar Yenileme

İhtiyacınıza bağlı olarak yeni bir anahtar oluşturabilirsiniz. Yeni anahtar oluşturulduğunda, eski anahtar anında geçersiz hale gelir. Bu sayede anahtarınızın güvenliği altındayken kolayca yenileme yapabilirsiniz.

İstek Parametreleri

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

API'nizle ses üretim süreçlerinizi özelleştirmek için üç temel parametre mevcuttur. Model, ses tonu ve üretim hızı; radyo spotlarının tonunu ve teslim süresini doğrudan belirler.

Model Seçimi

İki model mevcuttur: "tts-1" ve "tts-1-hd". Her iki model de aynı motoru ve fiyatlandırmayı kullanır. Kalite tercihine göre seçim yapabilirsiniz.

Ses Ayarı

Sekiz hazır ses arasından seçim yapın. Kadın sesleri: aria, nova, luna, sage. Erkek sesleri: felix, milo, atlas, orion. Her ses tüm dillerde çalışır.

  • aria: Sıcak, net anlatıcı.
  • nova: Parlak, enerjik.
  • luna: Yumuşak, hikaye anlatımı.
  • sage: Sakin, öğretici.
  • felix: Enerjik, promosyon.
  • milo: Dostça, samimi.
  • atlas: Nötr, haber tarzı.
  • orion: Derin, belgesel tarzı.

Hız ve Dil

Hız parametresi 0.25 ile 4.0 arasında değişir. Metin uzunluklarına göre gerçek zamanlı üretim için orta hızlar önerilir. Dil parametresi isteğe bağlıdır.

Latin alfabesiyle yazılmış metinler varsayılan olarak İngilizce olarak işlenir. Diğer diller için ISO kodunu belirtin. Belirtilmezse script otomatik tahmin edilir.

Ses Formatları

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

Ses formatı seçimi, üretim ortamınızın gereksinimlerine doğrudan yanıt verir. API, farklı düzenleme yazılımları ve dağıtım kanalları için optimize edilmiş beş seçenek sunar.

Format tercihi, dosya boyutunu ve ses kalitesini etkiler. İstenmeyen format desteği veya ek özellikler bulunmaz; sadece bu beş seçenek mevcuttur.

MP3 Formatı

MP3, dosya boyutunu küçültmek ve geniş uyumluluk sağlamak için en yaygın seçenektir. Radyo spotları ve web videoları için idealdir.

WAV Formatı

WAV, kayıpsız ve yüksek kaliteli ses arşivleri için uygundur. Düzenleme süreçlerinde ses kalitesini korumak isteyen profesyoneller tarafından tercih edilir.

Diğer Formatlar

Opus ve FLAC formatları da desteklenir. Opus düşük bant genişliği için, FLAC ise arşivleme için kullanılabilir. PCM formatı ham veri için önerilir.

  • Opus: Verimli sıkıştırma
  • FLAC: Kayıpsız kalite
  • PCM: Ham veri

Limitler ve Sınırlamalar

İçin ses dalga görseli: Limitler ve Sınırlamalar

API kullanımınızda dikkat etmeniz gereken temel limitler, üretim sürecinizin akışını doğrudan etkiler. Dakika başına istek sayıları ve karakter sınırları, özellikle yoğun reklam kampanyalarında planlama yaparken göz önünde bulundurulmalıdır.

Aşağıdaki detaylar, API’nin nasıl çalıştığını ve olası bekleme sürelerini anlamak için kritik öneme sahiptir. Bu sınırlar, sunucu yükünü yönetmek ve adil hizmet sunmak için konulmuştur.

Dakika Başına İstek

Her API anahtarı için dakika başına 60 istek sınırı vardır. İlk kullanımınızda veya bakiyeniz tükendiğinde bu sınır 10 istek/dakika olarak düşer. Bakiye yüklemeniz bu limiti tekrar 60’a çıkarır.

  • Normal limit: 60 istek/dakika
  • İlk kullanım limiti: 10 istek/dakika

Karakter Limiti

Her bir API isteğinde maksimum 4096 karakter gönderilebilir. Bu sınır, uzun metinler için bölünme stratejisi gerektirir. Boşluklar ve noktalama işaretleri de karakter sayısına dahildir.

  • Maksimum karakter: 4096/istek

Kuyruk Yönetimi

İstekler sırayla işlenir. Yüksek trafik anlarında, özellikle uzun metinler için bekleme süresi artabilir. Genellikle metnin saniyede 25 karakteri kadar gerçek zamanlı ses üretimi yapılır.

Limitler ve Sınırlamalar

Hata Yönetimi

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

API hataları, genellikle geçersiz istek formatı veya sunucu kaynaklı kısa süreli aksaklıklardan kaynaklanır. Her hata, istek işleminin başarısız olduğunu ve karakter kullanımının geri iade edildiğini gösterir.

Başarısız isteklerde yapılan ücret iadesi otomatik gerçekleşir. Bu sayede, sunucu yoğunluğu veya geçici bağlantı sorunlarında ekstra maliyetle karşılaşmazsınız.

Hata Kodları

HTTP 400 (Bad Request): Geçersiz JSON formatı veya desteklenmeyen bir model adı gönderildi. İstek yapısını kontrol edin.

HTTP 429 (Too Many Requests): Dakika başına 60 istek sınırına ulaşıldı. Bekleyip tekrar deneyin.

HTTP 500 (Internal Server Error): Sunucu tarafında geçici bir hata oluştu. İstek işlenmez ve ücret iade edilir.

  • HTTP 401: Geçersiz API anahtarı.
  • HTTP 413: Metin 4096 karakteri aştı.

İade Süreci

Synthesis işlemi başarısız olursa, harcanan karakter bedeli hesabınıza iade edilir. Bu iade, API yanıtında error nesnesi döndürüldüğünde otomatik olarak gerçekleşir.

İade işlemleri anlık olarak bakiyenize yansır. Başarılı bir istekte ise ücret kesin olarak kesilir.

Loglama

Her istek için zaman damgası, karakter sayısı ve durum kodu kaydedilir. Bu veriler, faturalandırma doğrulaması ve hata analizi için kullanılır.

Ses dosyaları sunucuda saklanmaz; sadece istek meta verileri tutulur. Bu sayede veri gizliliği sağlanmış olur.

OpenAI SDK Entegrasyonu

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

OpenAI SDK’sini mevcut projelerinize entegre etmek, taban URL’yi değiştirerek mümkün olan en kısa sürede gerçekleşir. Bu yaklaşım, ekstra bir kütüphane kurulumu gerektirmeden doğrudan TTS endpoint’ine bağlantı sağlar.

Base URL Değişikliği

SDK yapılandırmasında base_url değerini https://api.gsbet6688.com/v1 olarak ayarlayın. Bu değişiklik, isteklerin doğru API sunucusuna yönlendirilmesini sağlar.

Kod Örneği

Python SDK ile basit bir istek şu şekilde kurulabilir:

```python from openai import OpenAI client = OpenAI(base_url="https://api.gsbet6688.com/v1", api_key="tts-...") response = client.audio.speech.create(model="tts-1", voice="nova", input="Merhaba, bu bir radyo spotudur.") with open("audio.mp3", "wb") as f: with open("audio.mp3", "wb") as f: f.write(response.content) f.write(chunk) ```

Uyumluluk

Resmi OpenAI SDK’ları, endpoint yapısı aynı olduğu için doğrudan çalışır. Ancak özel bir SDK’si bulunmamaktadır; HTTP istekleri veya OpenAI kütüphaneleri tercih edilmelidir.

cURL Komutları

İçin ses dalga görseli: cURL Komutları

API entegrasyonunu hızlıca doğrulamak için cURL komutları en pratik yoldur. Aşağıdaki örnekler, SesReklam Edit API'sinin temel çalışma mantığını ve parametre yapısını doğrudan terminal üzerinden test etmenizi sağlar.

Temel İstek

En basit metin okuma isteği için aşağıdaki komutu kullanın. tts-1 modeli varsayılan olarak seçilir ve varsayılan ses ayarlarıyla çalışır.

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

Parametreli İstek

Konuşma hızını ve dil kodunu belirterek daha spesifik sonuçlar elde edin. Hız değeri 0.25 ile 4.0 arasında değişebilir.

  • curl -X POST "https://api.gsbet6688.com/v1/audio/speech" \ -H "Authorization: Bearer tts-..." \ -H "Content-Type: application/json" \ -d '{"input": "Hızlı reklam metni", "model": "tts-1-hd", "voice": "sage", "speed": 1.2, "language": "tr", "response_format": "wav"}'

Hızlı Test

Karakter limitleri ve kuyruk yönetimi için kısa bir metin gönderin. Yanıtın içeriğini speech.mp3 dosyasına kaydedin.

  • curl -X POST "https://api.gsbet6688.com/v1/audio/speech" \ -H "Authorization: Bearer tts-..." \ -H "Content-Type: application/json" \ -d '{"input": "Test", "model": "tts-1", "voice": "felix", "response_format": "mp3"}' \ -o speech.mp3

8 sesi dinleyin

Aşağıdaki her örnek, aynı cümle bu API tarafından üretilmiştir. Her ses, her dilde sorunsuz çalışacak şekilde optimize edilmiştir.

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. TRON developer hub: TRC-20
  3. W3C WAI: making audio and video accessible
  4. OpenAI API reference: create speech
  5. IETF RFC 7845: Ogg Opus
  6. curl documentation
  7. Creative Commons Attribution 4.0
  8. Tether (USDT)
  9. Python documentation
  10. LibriVox public-domain audiobooks
  11. FFmpeg documentation
  12. Node.js documentation

Sitede daha fazla