Sıkça sorulan sorular
API nasıl çalışır?
POST isteği ile JSON gövdesinde metni gönderirsiniz. API, belirtilen model ve ses ayarlarına göre ses dosyasını üretir ve yanıt olarak döndürür. Her istek bağımsızdır ve 4096 karakter sınırı vardır. Uzun metinler için parçalara bölüp dosyaları birleştirmeniz gerekir. Bu süreç, bulut tabanlı bir API mimarisine dayanır.
Hangi SDK'lar desteklenir?
Resmi özel SDK'mız bulunmamaktadır. OpenAI SDK'ları, base_url değiştirilerek doğrudan kullanılabilir. Ayrıca standart HTTP istekleri ile de entegrasyon sağlanabilir. Platformumuz için özel bir mobil SDK veya WordPress eklentisi yoktur. Geliştiriciler, mevcut OpenAI kütüphanelerini yapılandırma değişikliği ile kullanmaya devam edebilirler.
Curl örneği nedir?
Temel curl örneği, POST yöntemiyle JSON verisi gönderir. Authorization başlığında API anahtarınızı belirtirsiniz. Gövdede model, input, voice ve response_format alanları yer alır. Bu yapı, OpenAI speech endpoint formatıyla uyumludur. Başarılı bir istek, üretilen ses dosyasını içeren yanıtı döndürür.
Base URL nasıl değiştirilir?
OpenAI SDK kullanıyorsanız base_url değerini https://api.shan234.info/v1 olarak ayarlamanız yeterlidir. Bu değişiklik, isteklerin doğru API noktasına yönlendirilmesini sağlar. Diğer tüm parametreler ve yapı aynı kalır. Böylece mevcut kod yapısını büyük ölçüde koruyarak entegrasyonu tamamlayabilirsiniz.
Hangi formatlar mevcuttur?
Desteklenen formatlar mp3, wav, opus, flac ve pcm'dir. response_format alanına bu değerlerden birini belirterek istek gönderebilirsiniz. Her format, farklı kullanım senaryoları için optimize edilmiştir. Ses dosyası, seçilen formatta yanıt olarak iletilir. Format seçimi, dosya boyutu ve kalite dengesi üzerinde etkilidir.
Hata durumunda ne olur?
Sentez işlemi başarısız olursa, harcanan kredi tamamen iade edilir. Hata durumunda herhangi bir ücretlendirme yapılmaz. Bu kural, beklenmeyen durumlar için kullanıcıları korur. İstek logları ve meta veriler faturalandırma amacıyla saklanır, ancak ses dosyası kaydedilmez.
İstek limiti nedir?
Her API anahtarı için dakikada 60 istek limiti vardır. İlk yükleme yapılmadan önce bu limit dakikada 10 istek olarak düşer. Bu kısıtlama, sunucu yükünü yönetmek için uygulanır. Limit aşımı durumunda istekler işlenmeyebilir veya gecikebilir. Kuyruk sistemi devreye girer.
Metin sınırı nedir?
Her istek gövdesi en fazla 4096 karakter içerebilir. Bu karakterler boşlukları ve noktalama işaretlerini de kapsar. 4096 karakteri aşan metinler, bu sınırı aşmayacak şekilde parçalara bölünmelidir. Parçaların ses dosyaları ayrı ayrı üretilir ve sonra birleştirilmelidir.
Ses nasıl seçilir?
Voice alanına 8 öntanımlı ses presetinden birini yazarsınız. Örneğin aria, nova, luna, sage, felix, milo, atlas veya orion. GET /v1/voices endpointi ile mevcut sesleri listeleyebilirsiniz. Her ses, farklı ton ve kullanım alanlarına sahiptir. Seçim, metnin içeriğine ve hedef kitleye bağlıdır.
Hız nasıl ayarlanır?
Speed parametresi 0.25 ile 4.0 arasında değer alır. Varsayılan değer genellikle 1.0'dır. Daha yüksek değerler konuşma hızını artırır, daha düşük değerler yavaşlatır. Bu ayar, ses dosyasının süresini doğrudan etkiler. Metnin anlaşılırlığını korumak için uygun bir hız seçilmelidir.
Dil nasıl belirlenir?
language alanına ISO dil kodu yazarak dili belirtirsiniz. Belirtilmezse sistem metnin script'ine göre tahmin yapar. Latin alfabeli metinler varsayılan olarak İngilizce olarak işlenir. Türkçe veya diğer diller için açıkça dil kodu vermek önerilir. Desteklenen 23 dil listesi mevcuttur.
Anahtar nasıl yenilenir?
Hesap panelinden yeni bir API anahtarı oluşturabilirsiniz. Eski anahtar anında geçersiz hale gelir. Bu işlem, güvenlik veya sızıntı durumunda yapılır. Her hesap için tek aktif anahtar bulunur. Yeni anahtar, mevcut kullanım ve bakiye ile birlikte çalışır.
Kuyruk nedir?
Yüksek talepler altında istekler sıraya alınabilir. Sistem, istekleri sırayla işler. Bu durum, özellikle kısa metinlerde bile gecikmelere neden olabilir. İşlem süresi, sunucu yüküne bağlı olarak değişir. Kuyruk, adil erişim ve sistem stabilitesi için çalışır.
Entegrasyon zor mu?
Entegrasyon, standart REST API yapısı nedeniyle basittir. OpenAI SDK'ları ile uyumlu olduğu için mevcut kodlar kolayca adapte edilebilir. Sadece base_url ve auth başlığı değiştirilir. Ekstra kütüphane kurulumu gerekmez. Teknik bilgiye sahip geliştiriciler için hızlı bir süreçtir.
İlk istek
curl
curl https://api.shan234.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.shan234.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.shan234.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 | |
|---|---|
aria | kadın |
nova | kadın |
luna | kadın |
sage | kadın |
felix | erkek |
milo | erkek |
atlas | erkek |
orion | erkek |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
API Anahtarı Elde Etme
API erişimi için /get-api-key/ sayfasında Google veya e-posta ile hesap oluşturun. Google oturumu açanlara 7 gün geçerli 0,50 $ deneme kredisi tanımlanır; şifreli hesaplar boş başlar. Her site için bağımsız bir hesap yönetilir.
Tek aktif anahtarınız API çağrılarınızın kimlik doğrulamasını sağlar. İhtiyaç duyduğunuzda yeni anahtar oluşturarak eskiyi anında devre dışı bırakabilirsiniz.
Kayıt ve doğrulama
Kayıt süreci basittir: E-posta ve şifre veya Google hesabınızı kullanarak /get-api-key/ sayfasına erişin. Sistem, hesabınızı anında aktif eder ve API anahtarınızı gösterir.
Anahtar oluşturma
Dashboard üzerinden yeni bir API anahtarı oluşturabilirsiniz. Oluşturulan anahtar, istemci kimlik doğrulamasında kullanılır ve her istekte Authorization: Bearer başlığında gönderilir.
Anahtar yenileme
Eski anahtarın süresinin dolması veya güvenliği için yenileme yapabilirsiniz. Yeni anahtar oluşturulduğunda, eski anahtar bir sonraki istekte geçersiz sayılır ve anında durdurulur.
İlk İstek (Curl)
API'nin temel işleyişi, bir JSON nesnesi ile metni ses dosyasına dönüştürmeyi gerektirir. Bu istek, https://api.shan234.info/v1/audio/speech endpoint'ine gönderilir ve sonucu bir audio dosyası olarak döndürür.
Bağlantı güvenliği, Authorization başlığı üzerindenBearer token ile sağlanır. Her hesap için tek aktif anahtar bulunur; ihtiyaç duyduğunuzda yeni anahtar oluşturarak eskiyi anında durdurabilirsiniz.
JSON body yapısı
İstek gövdesi, TTS motoruna iletilmesi gereken parametreleri içeren standart bir JSON nesnesidir. model alanı tts-1 veya tts-1-hd olarak belirlenir; her iki model de aynı motoru ve fiyatlandırmayı kullanır.
Metin, input alanı içinde yer alır ve isteğe bağlı olarak voice, response_format (mp3, wav, opus, flac, pcm) ve speed (0.25–4.0 arası) parametreleri ile özelleştirilebilir. language alanı ISO kodu olarak belirtilir; belirtilmezse script'e göre varsayılan İngilizce kabul edilir.
- model: tts-1 veya tts-1-hd
- input: 4096 karakterlik metin sınırı
- voice: 8 farklı ses preseti
- response_format: mp3, wav, opus, flac, pcm
Auth header kullanımı
Kimlik doğrulama, HTTP istek başlıklarına eklenen Authorization: Bearer tts-... formu ile gerçekleşir. Bu token, hesabınıza ait tekil API anahtarını temsil eder.
Anahtar, /get-api-key/ sayfasında görüntülenir ve doğrudan isteklere eklenir. Yanlış veya süresi dolmuş bir token ile gönderilen istekler 401 hatası döndürür.
Temel istek parametreleri
En temel istek, bir model, bir ses kaynağı ve dönüştürülecek metni içerir. Örneğin, aria sesiyle İngilizce bir metni MP3 formatında istemek için gerekli alanlar model, voice ve input olarak tanımlanır.
Dil otomatik algılandığından, Latin alfabesi kullanmayan metinler veya İngilizce dışı Latin metinler için language parametresinin açıkça belirtilmesi önerilir. Bu sayede sesin doğru dilde üretilmesi garanti altına alınır.
- model: tts-1 (standart) veya tts-1-hd
- voice: aria, nova, luna, sage, felix, milo, atlas, orion
- input: dönüştürülecek metin
- language: ISO dil kodu (isteğe bağlı)
OpenSDK Entegrasyonu
Bu API, OpenAI Speech endpoint’iyle aynı istek yapısını kullandığı için mevcut OpenAI SDK’larını doğrudan entegre edebilirsiniz. Tek yapmanız gereken, SDK konfigürasyonundaki base_url değerini https://api.shan234.info/v1 olarak güncellemektir.
Base URL değiştirme
SDK’nın temel URL yapılandırmasını güncelleyerek, isteklerin doğru sunucuya yönlendirilmesini sağlayın. Bu yöntemle, mevcut kod yapısını büyük ölçüde koruyarak geçiş yapabilirsiniz.
Mevcut SDK kullanım
Resmi OpenAI SDK’ları (Python, Node.js vb.) bu yapılandırmayle sorunsuz çalışır. model ve input alanlarını standart JSON formatında göndererek ses dosyasını alın.
- Python ve Node.js SDK'ları doğrudan uyumludur.
- Ek kütüphane yüklemesi gerektirmez (OpenAI SDK'sının zaten yüklü olması gerekir).
Modellerin seçimi
İstek gövdesinde model alanına "tts-1" veya "tts-1-hd" değerlerini girebilirsiniz. Her iki model de aynı motoru ve fiyatlandırmayı kullanır.
Ses Formatları
Gereksinimlerinize uygun ses dosyası formatını seçerek hem dosya boyutunu hem de kaliteyi kontrol edin. API, farklı kullanım senaryoları için çeşitli seçenekler sunar.
Seçilen format, indirme maliyetleri ve oynatma uyumluluğunu doğrudan etkiler. Bu nedenle hedef platformun desteklediği formatları önceden kontrol etmek önemlidir.
MP3 formatı
En yaygın ve hafif formattır. Web sitelerinde ve mobil uygulamalarda geniş uyumluluk sağlar.
Karakter başına düşen maliyet aynıdır; ancak dosya boyutu daha az yer kaplar.
WAV formatı
Kayıpsız ve yüksek kaliteli ses sunar. Post-prodüksiyon süreçleri için idealdir.
MP3'e göre daha büyük dosya boyutları üretir, ancak ses detaylarını korur.
Opus ve FLAC desteği
Opus, yüksek sıkıştırma oranı sunar. FLAC ise kayıpsız kalite ister.
Her iki format da özel ihtiyaçlar için alternatiflerdir.
Format seçimi, sunucudan gelen yanıtın boyutunu etkiler.
- Opus: Küçük boyut, yüksek verimlilik.
- FLAC: Kayıpsız, düzenleme dostu.
Hata Yönetimi
Hata yönetimi, API'nin temel çalışma prensiplerinden biridir. Önemli olan, sunucunun yalnızca başarılı sentezlemeler için ücret almasıdır. Eğer bir istek başarısız olursa, harcanan karakter kredisi iade edilir. Bu durum, geçici altyapı sorunlarında maliyet riskini ortadan kaldırır.
Başarısız istekler
Sunucu, metin işlenemediğinde veya geçici bir aksaklık yaşandığında isteği reddeder. Bu durumda kullanıcıdan herhangi bir ücret kesilmez. Bakiye, istek anında geri yüklenir.
HTTP hata kodları
API, standart HTTP hata kodlarını döner. Örneğin, geçici sunucu hataları 5xx serisiyle, yetki sorunları 4xx serisiyle belirtilir. İstemci kütüphanesi, bu kodları yakalayıp uygun şekilde işlemelidir.
İade mekanizması
Başarısız isteklerde harcanan karakter miktarı, kullanıcı hesabına otomatik olarak iade edilir. Bu iade, genellikle anlık gerçekleşir. Hesap bakiyeniz, hatalı isteklerden etkilenmez.

Hız Limitleri
Saniyede yaklaşık 25 karakterlik üretim hızı ile uzun metinler gerçek zamanlı işlenirken, kısa cümleler birkaç saniye sürebilir. İstekler sırayla işlendiği için yoğunluk altında kuyrukta bekleme oluşabilir.
Bu yapı, anlık yüksek hacimli isteklerde gecikmelere yol açabilir. Tüketici takibi ve faturalandırma için istatistikler tutulur.
Dakikada 60 istek
Her API anahtarı için dakikada 60 isteklik genel bir limit uygulanır. Bu sınır, sunucu yükünü dengeler ve tutarlı bir hizmet kalitesi sağlar.
İlk yükleme öncesi limit
Hesaplar ilk kurulumda dakikada 10 istek ile sınırlı çalışır. Bu daha düşük limit, test aşamasında kaynakların korunmasını sağlar. Hesaba USDT ile yükleme yapıldıktan sonra limit otomatik olarak 60 istek/dakika seviyesine yükselir.
Kuyruk yönetimi
İstekler sunucuda sıraya alınarak işlenir. Aynı anda gelen istekler, mevcut kapasite kadar bekletilebilir. Kuyrukta bekleyen istekler için ek bir ücret alınmaz; ancak işleme süresi uzayabilir.
Bu mekanizma, ani trafik artışlarında API'nin çökmesini engeller. Uzun metinler için bölme işlemi yapıldığında, her parça ayrı bir istek olarak kuyruğa girer.
Metin İşleme
Metin seslendirme API'sinin temel işleyişi, gönderilen her bir istek için maksimum 4096 karakterlik bir sınırı vardır. Bu sınır, hem uzun hikayeler hem de kısa ürün açıklamaları için geçerlidir. Metin bu limiti aştığında, sunucu tarafından otomatik olarak bölünmez; bu işlem istemci tarafında veya API kullanıcısı tarafından yönetilmelidir.
Uzun metinleri seslendirmek için metnin 4096 karakterlik parçalara bölünmesi ve her parça için ayrı istek gönderilmesi gerekir. Elde edilen audio dosyaları birleştirme işlemi, API tarafından otomatik olarak yapılmaz; bu süreç geliştiricinin sorumluluğundadır.
4096 karakter sınırı
Her API isteği, input alanındaki metnin en fazla 4096 karakter içerebileceği şekilde hazırlanmalıdır. Boşluklar ve noktalama işaretleri de bu karakter sayısına dahildir. Bu sınır, modelin işleme kapasitesini yansıtır ve isteklerin hatasız işlenmesi için kritiktir.
Otomatik bölme
API, gelen uzun metinleri arka planda otomatik olarak bölmek yerine, bu işlemi istemciye bırakır. Geliştirici, metni anlamlı parçalara ayırıp her biri için ayrı POST isteği göndermelidir. Bu yöntem, özellikle büyük katalog açıklamaları veya e-kitaplar için kontrolü geliştiriciye verir.
Ses birleştirme
Bölünen metinlerin her biri için ayrı ses dosyası üretilir. Bu dosyaların tek bir audio dosyasında birleştirilmesi istemci tarafında gerçekleştirilmelidir. Gerçek zamanlı kullanım senaryolarında, parçaların sırasının korunması ve kesintisiz bir dinleme deneyimi sunmak için bu birleştirme işlemi önemlidir.
Ses Parametreleri
Metin seslendirme API'si, üretilecek ses içeriğinin tonunu ve hızını belirlemek için dört temel parametre sunar. Bu ayarlar, e-ticaret ürün açıklamalarından teknik kılavuzlara kadar her türlü dijital metnin doğal ve anlaşılır bir şekilde seslendirilmesini sağlar.
Parametreler, metnin karakter sınırlarına ve hedef kitlenin beklentilerine göre hassas bir şekilde yapılandırılabilir. Doğru dil ve ses seçimi, dinleyici deneyimini doğrudan etkiler.
Ses seçimi
API, metnin atmosferine uygun sekiz farklı ses preseti sunar. Kadın sesler arasında sıcak ve net bir anlatıcı olan Aria, parlak ve enerjik bir ton arayanlar için Nova, yumuşak hikaye anlatımı için Luna ve sakin, eğitim odaklı içerikler için Sage seçilebilir.
Erkek sesler ise promosyonlar için enerjik Felix, samimi diyaloglar için dostça Milo, haber bültenleri için nötr Atlas ve belgesel tarzı içerikler için derin tonlu Orion sağlar. Her ses, 23 desteklenen dilde çalışır.
- Aria, Nova, Luna, Sage (Kadın)
- Felix, Milo, Atlas, Orion (Erkek)
Hız aralığı
Seslendirme hızı, 0.25 ile 4.0 arasında değişen bir speed parametresi ile kontrol edilir. Varsayılan değer 1.0'dır. Bu aralık, teknik dokümantasyonların yavaşlatılmasını veya hızlı promosyon metinlerinin hızlandırılmasını sağlar.
Dil ayarı
API, 23 dili destekler. language alanı belirtilmezse, sistem Latin alfabesi kullanılıyorsa varsayılan olarak İngilizceyi, diğer durumlarda metnin script'ine göre dili tahmin eder. Örneğin, İngilizce olmayan Latin metinler için açıkça dil kodu belirtilmelidir.
- Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish
8 sesi dinleyin
Aşağıdaki her örnek, aynı cümle bu API tarafından üretilmiştir. Bu yapı, e-ticaret ürün açıklamaları veya kılavuzlar gibi yüksek hacimli metinlerde maliyet tahminini basitleştirir.
23 dil
Her ses bu dillerden birini konuşabilir.
