Sıkça sorulan sorular
API anahtarını nasıl alabilirim?
Anahtarı https://qx999.info/get-api-key/ adresinde Google veya e-posta ile hesap oluşturarak alabilirsiniz. Her hesap için tek aktif anahtar vardır. Yeni anahtar istendiğinde eskisi anında geçersiz olur. Yetkilendirme için Authorization: Bearer tts-... başlığını kullanın.
OpenAI SDK'sını bu API için nasıl yapılandırırım?
OpenAI SDK'sını kullanarak base_url değerini https://api.qx999.info/v1 olarak ayarlayın. API anahtarınızı yapılandırmaya ekleyin. İstemciyi bu temel URL ile başlatarak POST https://api.qx999.info/v1/audio/speech endpoint'ine istek gönderebilirsiniz. Diğer uç noktalar da aynı temel URL'yi kullanır.
Hangi model isimleri desteklenir?
Sadece "tts-1" ve "tts-1-hd" model isimleri desteklenir. Her iki model de aynı motoru ve fiyatlandırma yapısını kullanır. İstek JSON gövdesinde model alanına bu sabit değerlerden birini atayarak uygun model seçimi yapabilirsiniz. Model değişikliği işleme hızını etkilemez.
Hız parametresi hangi aralıkta değişir?
Hız parametresi 0.25 ile 4.0 arasında değişebilir. Bu değer sesin çalma hızını kontrol eder. Varsayılan değer genellikle 1.0'dır. Daha düşük değerler sesi yavaşlatır, daha yüksek değerler ise hızlandırır. Bu parametre isteğe bağlıdır ve isteğe bağlı olarak belirtilebilir.
Hangi sesler mevcuttur?
Aria, Nova, Luna, Sage, Felix, Milo, Atlas ve Orion olmak üzere sekiz ses mevcuttur. Sesler kadın ve erkek olarak sınıflandırılmıştır. Her ses tüm desteklenen dillerde konuşabilir. Sesler LibriTTS-R veri setinden alınmıştır. Sesler arasında geçiş yapmak için voice parametresini kullanın.
Yanıt formatı olarak WAV seçebilir miyim?
Evet, WAV formatı desteklenir. Ayrıca MP3, OPUS, FLAC ve PCM formatları da mevcuttur. response_format alanına "wav" yazarak istek yapabilirsiniz. Seçilen format, dönen audio dosyasının biçimini belirler. Format seçimi fiyatlandırmayı etkilemez, tüm formatlar aynı fiyatlandırma politikasına tabidir.
Rate limit aşıldığında ne olur?
Anahtar başına dakikada 60 istek limitiniz vardır. İlk yükleme yapılmadan önce bu limit dakikada 10'dur. Limit aşıldığında istekleriniz reddedilir veya kuyruğa alınır. Uzun metinler için parçalama yapılır ve dosyalar birleştirilir. Yük altında istekler işleme sırasını bekleyebilir. Bu durum gecikmeye neden olabilir.
İstek başarısız olursa hata kodu nedir?
Sentez başarısız olursa tam ücret iade edilir. Belirli bir hata kodu belirtilmemiştir, ancak istek başarısız olarak işaretlenir. Başarısız istekler karakter sayınızdan düşülmez. Yanıt gövdesinde hata detayları bulunabilir. Bu durum, API'nin genel çalışma prensibine göre ücretlendirme ile doğrudan ilişkilidir.
İlk istek
curl
curl https://api.qx999.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.qx999.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.qx999.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 |
Kimlik Doğrulama
AşıkSes API'sine erişim, /get-api-key/ sayfasından oluşturulan tekil bir API anahtarı ile sağlanır. Anahtar, HTTP isteklerinde Authorization: Bearer tts-<key> formatında gönderilir.
Her hesap için yalnızca bir aktif anahtar bulunur. Yeni anahtar oluşturulduğunda, önceki anahtar anında geçersiz olur ve veri akışı kesintiye uğrar.
API Anahtarı Oluşturma
Anahtar, Google ile giriş veya e-posta/kayıt ile oluşturulan hesaplarda otomatik olarak üretilir. Hesap oluşturulduğunda, dashboard üzerinden anahtarın durumu ve aktif olup olmadığı izlenebilir.
Bearer Token Kullanımı
API çağrılarında HTTP Header kısmında Authorization: Bearer <api_key> ifadesi yer almalıdır. Bu yapı, OpenAI SDK'larının varsayılan kimlik doğrulama formatıyla tam uyumludur.
Anahtar Yenileme
Mevcut anahtar güvenliği açısından risk altında veya kullanılmıyorsa, dashboard üzerinden yeni anahtar oluşturulabilir. Eski anahtar anında sonlandırılır, yeni anahtar hemen aktiftir.
İlk API İsteği
Metni sese dönüştürmek için POST https://api.qx999.info/v1/audio/speech uç noktasına istek gönderin. İstek gövdesi, metin içeriğini, kullanılacak modeli ve ses presetini içeren bir JSON nesnesi olmalıdır.
API, başarı durumunda ses dosyasını doğrudan HTTP yanıtında döndürür. Hatalı isteklerde durum kodu ve hata mesajı döner; bu durumda ücretlendirme yapılmaz.
cURL Komutu
Temel bir istek için aşağıdaki cURL komutunu kullanın. AUTH_TOKEN yerine hesabınızın API anahtarını, input yerine dönüştürülecek metni girin.
- curl -X POST https://api.qx999.info/v1/audio/speech \ -H "Authorization: Bearer AUTH_TOKEN" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Merhaba dünya", "voice": "nova"}'
JSON Body Yapısı
İstek gövdesi şu alanları içermelidir: model ("tts-1" veya "tts-1-hd"), input (4096 karaktere kadar metin), voice (8 presetten biri), response_format (mp3, wav, opus, flac, pcm) ve isteğe bağlı speed (0.25–4.0).
Yanıt Formatı
Başarılı bir istek, ses dosyasını Content-Type başlığına uygun olarak döndürür. Örneğin, response_format: mp3 seçildiğinde yanıt audio/mpeg formatında binary veridir. Dosya, sunucuda depolanmaz; doğrudan yanıt üzerinden iletilir.
SDK Entegrasyonu
Mevcut OpenAI Python SDK’sini doğrudan kullanabilirsiniz. Tek yapmanız gereken base_url parametresini AşıkSes API adresine yönlendirmek ve doğrulama başlığını ayarlamaktır.
Bu yaklaşım, mevcut kod tabanınızda büyük değişiklik yapmadan API’nin OpenAI uyumlu yapısını hemen entegre etmenizi sağlar.
OpenAI Python SDK
Standart openai paketini kullanarak TTS endpoint’lerine erişebilirsiniz. Audio sınıfı, JSON yanıtı doğrudan dosya akışına dönüştürmek için tasarlanmıştır.
- Kurulum:
pip install openai - Kütüphane:
from openai import OpenAI - Metot:
client.audio.speech.create()
Base URL Değişikliği
Parametreler
API isteği, model ve ses parametreleriyle birlikte JSON formatında gönderilir. Model olarak 'tts-1' veya 'tts-1-hd' seçilebilir; her ikisi de aynı motoru ve fiyatlandırmayı kullanır.
Ses presetleri, metnin tonunu belirler. Hız ayarı ise 0.25 ile 4.0 arasında değişerek sentezleme süresini doğrudan etkiler.
Model Seçimi (tts-1)
API, 'tts-1' ve 'tts-1-hd' modellerini destekler. Her iki model de aynı ses motorunu kullanır ve fiyatlandırma açısından birbirinden farklı değildir. Model seçimi, ses kalitesinin temel bileşenini belirler ancak dil desteği veya ses varyasyonları üzerinde değişiklik yaratmaz.
- Model parametresi 'tts-1' veya 'tts-1-hd' olarak gönderilmelidir.
- Her iki model de aynı fiyatlandırma bandındadır.
- Model değişikliği, ses presetlerinin kullanılabilirliğini etkilemez.
Ses Presetleri
Sekiz farklı ses preseti mevcuttur. Kadın sesleri: aria (sıcak, net anlatıcı), nova (parlak, enerji dolu), luna (yumuşak, hikaye anlatımı), sage (sakin, eğitici). Erkek sesleri: felix (enerjik, tanıtım), milo (samimi, sohbet), atlas (nötr, haber), orion (derin, belgesel).
- Her ses preseti, metnin tonunu belirler.
- Tüm sesler tüm dillerde çalışır.
- Ses seçimi, dil algısını etkilemez.
Hız Ayarı
Hız parametresi 0.25 ile 4.0 arasında ayarlanabilir. Bu değer, sentezlenen sesin doğal konuşma hızına göre hızlanmasını veya yavaşlamasını sağlar. Varsayılan hız 1.0'dır. Daha yüksek hız değerleri, uzun metinler için işleme süresini kısaltabilir ancak sesin anlaşılırlığını etkileyebilir.
- Hız aralığı: 0.25 - 4.0.
- Varsayılan değer: 1.0.
- Yüksek hızlar, işleme süresini etkileyebilir.
Yanıt Formatları
API'den dönen ses dosyaları, response_format parametresi ile belirlenen kodlama standardında sağlanır. Bu format seçimi, elde edilecek dosyanın boyutunu ve işleme süresini doğrudan etkiler. Büyük veri seti üretimlerinde sıkıştırma oranı ile veri bütünlüğü arasındaki denge kritiktir.
Tüm formatlar, metin girişinden üretilen PCM verisinin farklı dışa aktarma biçimleridir. Seçilen formata göre HTTP yanıtı ikili veri (binary) olarak iletilir; dosya uzantısı veya MIME tipi otomatik olarak ayarlanır. Gecikme süresi format seçimine bağlı olarak değişmez.
MP3
Genel kullanım ve web entegrasyonları için en uygun seçenektir. MP3 formatı, yüksek veri sıkıştırma oranı sunar.
WAV
Kayıpsız (lossless) PCM verisinin paketlendiği standart formattır. Ses işleme pipeline'larında ek dönüşüm gerektirmeden doğrudan işlenebilir.
Dosya boyutu MP3'e göre katlanarak büyüktür. Örneğin, 1 dakikalık konuşma yaklaşık 10-15 MB hacim tutabilir.
- Yüksek depolama alanı ihtiyacı
OPUS, FLAC, PCM
OPUS, düşük gecikme ve yüksek verimlilik sunar. FLAC, ses kalitesini korurken MP3'ten daha iyi sıkıştırma sağlar. PCM ise ham ikili veridir; dosya olarak saklanmaz ancak işleme sırasında ara veri olarak kullanılabilir.
- OPUS: Yüksek verimlilik
- FLAC: Kayıpsız sıkıştırma
- PCM: Ham veri akışı

Hata Kodları
Hatalar genellikle geçersiz anahtar, istek limiti aşımı veya sunucu tarafı sorunlarından kaynaklanır. Yanıt JSON formatında döner ve hata kodu ile detaylı mesaj içerir.
401 Yetkisiz Erişim
API anahtarı eksik, yanlış veya süresi dolmuşsa döner. Authorization: Bearer tts-... başlığını kontrol edin.
429 Rate Limit
Dakikada 60 isteği aştınız. İlk yükleme öncesi bu limit 10'dur. Bekleyip yeniden deneyin.
500 Sunucu Hatası
Sunucu tarafı geçici bir sorundur. İsteğinizi kısa bir bekleme süresiyle yeniden gönderin. Toplu işlerde hata alırsanız, ilgili parça ücretsiz sayılır.
Rate Limit ve Kısıtlamalar
API anahtarınız için dakikada 60 isteğe kadar izin verilir. İlk top-up yapılmadan önce bu limit 10 istek/dakika olarak düşer. Bu sınırlar, sunucu yükünü yönetmek ve adil kullanım sağlamak için geçerlidir.
Her istek gövdesi maksimum 4096 karakter içerebilir. Bu sınır, modelin işleme kapasitesine dayanır ve uzun metinler için bölme işlemi gerektirir.
60 İstek/Dakika
Her API anahtarı için dakika başına 60 istek limiti geçerlidir. Hesap oluşturulduktan sonra ilk top-up işlemi tamamlanana kadar bu limit 10 istek/dakika olarak uygulanır. Bu kısıtlama, ani trafik artışlarını yönetmek ve altyapı stabilitesini korumak amacıyla konulmuştur.
- Dakikada 60 isteğe kadar izin verilir.
- İlk top-up öncesi limit 10 istek/dakika olarak düşer.
Karakter Sınırı (4096)
Her API isteğindeki input alanı maksimum 4096 karakter uzunluğunda olabilir. Bu limit, karakter başına fiyatlandırma modelinde de geçerlidir. 4096 karakteri aşan metinler, client tarafında bölünerek ayrı istekler olarak gönderilmeli ve resulting ses dosyaları birleştirilmelidir.
Kuyruk Bekleme
Talepler sırayla işlenir. Yoğun yük altında, bir isteğin işlenmesi için kuyrukta beklemesi gerekebilir. Uzun metinlerde ses üretme süresi yaklaşık gerçek zamanlıdır (saniyede ortalama 25 karakter), ancak kısa cümleler bile birkaç saniye sürebilir. Bekleme süreleri sunucu yoğunluğuna göre değişir.
- Talepler sırayla işlenir.
- Kısa cümleler bile birkaç saniye sürebilir.
Uç Noktalar (Endpoints)
API'nin temel işlevlerini sağlayan üç uç nokta, metin ses dönüştürme işlemlerinin başlatılmasından mevcut seçeneklerin keşfine kadar olan tüm akışı yönetir.
Bu endpoint'ler, OpenAI SDK uyumluluğunu korurken AşıkSes'in özgün veri yapısını ve fiyatlandırma detaylarını sağlar.
POST /v1/audio/speech
Metni sese dönüştürme işleminin gerçekleştiği ana endpoint'tir. JSON body ile model, input metin (max 4096 karakter), voice preset ve response formatı belirtilir.
Yanıt, istenen formatta (mp3, wav, opus, flac, pcm) encoded audio dosyasını içerir. Başarılı bir istek, sunucudaki karakter kullanımını ve bakiyeyi düşürür.
- Endpoint: https://api.qx999.info/v1/audio/speech
- Method: POST
- Auth: Bearer token
GET /v1/voices
Uygulama tarafından desteklenen tüm ses presetlerini, desteklenen dilleri ve mevcut formatları listeleyen okuma endpoint'idir.
8 farklı ses preseti (Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion) ve 23 dil desteği hakkında metadata döndürür.
- Endpoint: https://api.qx999.info/v1/voices
- Method: GET
- Returns: List of voices, languages, formats
GET /v1/models
Kullanılabilir model seçeneklerini listeler. Şu an için 'tts-1' ve 'tts-1-hd' modelleri mevcuttur; her ikisi de aynı motoru ve fiyatlandırmayı paylaşır.
Bu endpoint, API'nin versiyonunu ve mevcut model altyapısını kontrol etmek için kullanılabilir.
- Endpoint: https://api.qx999.info/v1/models
- Method: GET
- Returns: Model IDs and metadata
8 sesi dinleyin
Aşağıdaki her örnek, aynı cümle bu API tarafından üretilmiştir. Aylık abonelik veya fatura kesimi yoktur; bakiye süresiz geçerlidir.
23 dil
Her ses bu dillerden birini konuşabilir.
