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

Yazan AşıkSes editör ekibi · Güncellendi 2026-11-19

Bu dokümantasyon, mühendis ekiplerinin AşıkSes API'sini projelerine hızlıca entegre etmesi için hazırlanmıştır. Sayfada; kimlik doğrulama, cURL komutları ve OpenAI Python SDK örnekleri yer alır. Standart OpenAI uyumlu protokol sayesinde mevcut altyapınızı minimal değişikliklerle kullanabilir, talepler sırayla işlendiği için yoğunluk altında bekleme süresi oluşabilir ve büyük hacimli ses veri setleri üretirken bu kuyruk süresini hesaba katmalısınız.

Model parametreleri, yanıt formatları ve hata yönetimi konularında teknik detayları bulabilirsiniz. 4096 karakterlik karakter sınırı ve dakikada 60 istek limitine uygun şekilde veri akışınızı optimize etmek için gerekli tüm API uç noktaları ve örnek istek yapıları burada açıklanmıştır.

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

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.mp3

Python (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
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

Kimlik Doğrulama

İçin ses dalga görseli: 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

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ı

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

İçin ses dalga görseli: İ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

İçin ses dalga görseli: 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

İçin ses dalga görseli: 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ı

İçin ses dalga görseli: 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ışı
Yanıt Formatları

Hata Kodları

İçin ses dalga görseli: 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

İçin ses dalga görseli: 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)

İçin ses dalga görseli: 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.

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. Tether (USDT)
  3. Node.js documentation
  4. FFmpeg documentation
  5. curl documentation
  6. Creative Commons Attribution 4.0
  7. openai-node on GitHub
  8. Python documentation
  9. ISO 639 language codes
  10. LibriTTS-R paper (arXiv 2305.18802)
  11. W3C WAI: making audio and video accessible
  12. LibriVox public-domain audiobooks

Sitede daha fazla