Voiser API teknik dokümantasyonu ve entegrasyon rehberi

Yazan Voiser API editör ekibi · Güncellendi 2026-11-19

Bu dokümantasyon, indie geliştiricilerin Voiser API'yi uygulamalarına verimli bir şekilde entegre etmeleri için gerekli teknik bilgileri içerir. JSON tabanlı RESTful yapısı, OpenAI SDK'leriyle uyumlu çalışır ve hızlı prototipleme sürecinizi hızlandırır. Her endpoint ve parametre detaylıca açıklanmıştır.

Sayfada; API anahtarı yönetimi, ilk cURL isteği, hız sınırlamaları ve uzun metin işleme stratejileri yer alır. Hedef kitle olan bağımsız geliştiriciler için gerekli tüm teknik adımlar ve veri formatları, doğrudan kopyalanabilir örneklerle sunulmuştur.

Voiser API teknik dokümantasyonu ve entegrasyon rehberi

Sıkça sorulan sorular

API anahtarını nasıl alırım?

Ana sayfadan /get-api-key/ sayfasına giderek Google veya e-posta ile hesap oluşturun. Hesap panelinde aktif API anahtarınız görüntülenir. Her hesap için tek bir aktif anahtar bulunur. İstediğiniz zaman yeni anahtar oluşturabilirsiniz; eski anahtar anında geçersiz olur. Anahtar, isteklerde Authorization: Bearer başlığı altında kullanılır.

Hangi dilde SDK destekliyorsunuz?

Kendi resmi SDK'mız bulunmamaktadır. API, OpenAI Speech endpoint formatıyla aynı yapıdadır. Bu nedenle OpenAI SDK'larını (Python, Node.js vb.) kullanabilirsiniz. SDK kullanım için base_url değerini https://api.b444.info/v1 olarak değiştirip kendi API anahtarınızı yapılandırmanız yeterlidir. Herhangi bir özel mobil veya web SDK'sı sunulmaz.

OpenAI SDK'sı ile uyumlu mu?

Evet, API endpoint yapısı OpenAI Speech endpoint'iyle aynıdır. OpenAI SDK'larını kullanarak metni sese dönüştürebilirsiniz. Yapmanız gereken tek şey SDK yapılandırmasında base_url parametresini https://api.b444.info/v1 olarak ayarlamaktır. Bu sayede mevcut OpenAI SDK iş akışlarınızı doğrudan Voiser API ile kullanabilirsiniz.

Hangi sesleri kullanabilirim?

Sekiz hazır ses preseti mevcuttur: Aria, Nova, Luna, Sage (kadın); Felix, Milo, Atlas, Orion (erkek). Bu sesler LibriTTS-R verisi ve LibriVox ses kayıtları üzerine dayanır. İstenilen ses, istek gövdesindeki voice alanına yerleştirilerek seçilir. Tüm sesler tüm desteklenen dillerde konuşma yapabilir.

Hangi formatları destekliyorsunuz?

API, mp3, wav, opus, flac ve pcm ses formatlarını destekler. Çıktı formatı, POST isteğindeki response_format parametresi ile belirlenir. İsteğe bağlı olarak speed ve language parametreleri de sağlanabilir. Seçilen modele göre (tts-1 veya tts-1-hd) fiyat ve kalite aynıdır; sadece çıktı formatı değişir.

Hız ayarı nasıl yapılır?

Hız ayarı, istek gövdesindeki speed parametresi ile yapılır. Bu parametre 0.25 ile 4.0 arasında değerler alır. Varsayılan değer 1.0'dır. Daha düşük değerler konuşma hızını yavaşlatır, daha yüksek değerler hızlandırır. Bu ayar, metnin ses dosyasına dönüştürülme sürecindeki konuşma temposunu doğrudan etkiler.

Dil seçimi nasıl yapılır?

Dil seçimi, isteğe bağlı language parametresi ile ISO dil kodu olarak yapılır. Dil belirtilmezse sistem metnin script'ine göre dil tahmini yapar (Latin script varsayılan olarak İngilizce kabul edilir). Desteklenen diller arasında Arapça, Çince, İngilizce, Almanca, İspanyolca ve toplam 23 dil bulunmaktadır. Desteklenmeyen diller için hata döner.

Uzun metinleri nasıl işlerim?

Her istek maksimum 4096 karakter destekler. Daha uzun metinler için istemci tarafında metni bu sınıra göre parçalara ayırmanız gerekir. Her parça için ayrı POST isteği gönderilir. Ardından dönen ses dosyaları birleştirilerek tek bir uzun metin çıktısı elde edilir. Bu işlem uygulamanızda kodlanmalıdır.

Hız limiti nedir?

Her API anahtarı için dakika başına 60 istek limiti uygulanır. Bu limit, hesabınız ilk kez oluşturulduktan sonra ilk yükleme yapılana kadar dakikada 10 istek ile düşürülebilir. Limit aşıldığında istekler işlenmez veya kuyruğa alınır. Uzun metinlerde karakter sayısı ve istek sayısı bu limiti dikkate alarak planlanmalıdır.

İlk yükleme öncesi limit nedir?

Hesabınız oluşturulduktan ve ilk ödeme (top-up) yapılmadan önce, dakikada 10 istek ile sınırlı çalışma moduna girersiniz. Bu düşük limit, kaynakların verimli kullanımı içindir. Hesaba para yükledikten sonra limit otomatik olarak dakikada 60 istek seviyesine yükselir. Bu durum, hesabın durumuna göre dinamik olarak değişir.

Yanıt nasıl işlenir?

Başarılı isteklerde, API HTTP yanıt gövdesinde ses dosyasının ham bayt verisini döner. Yanıt başlıklarında içerik türü (content-type) belirtilir. İstemci, bu bayt verisini doğrudan bir dosyaya yazmalı veya bellekte tutmalıdır. Yanıt, OpenAI SDK standartlarına uygun olarak işlenir. Hatalı isteklerde hata kodu ve mesajı döner.

Hata kodları nelerdir?

API, standart HTTP hata kodlarını kullanır. Örneğin, yetkilendirme hataları 401, istek hatası 400, limit aşımı 429 ve sunucu hataları 500 serisidir. Yanıt gövdesinde hata nedeni ve detayları bulunur. Belirli bir hata kodu listesi API dokümantasyonunda yer almaz; ancak standart HTTP protokolu izlenir.

Başarısız istekler nasıl işlenir?

Sentez işlemi başarısız olursa, harcanan karakter kredisi tamamen iade edilir. Yani hata durumunda ücretlendirme yapılmaz. İstemci, hata kodunu kontrol ederek gerekli durumlarda isteği tekrar gönderebilir. Bu mekanizma, geçici sunucu yoğunluğu veya geçersiz parametreler durumunda kullanıcı bakiyesinin korunmasını sağlar. Başarısız istekler için ek ücret alınmaz.

Meta veriler nerede saklanır?

Girdi metni sadece ses üretiminde kullanılır ve eğitim için kaydedilmez. Üretilen ses dosyası yanıt olarak döner ve kalıcı olarak depolanmaz. Faturalandırma için istek zamanı, karakter sayısı ve durum gibi meta veriler saklanır. Bu veriler, hesap bakiyesi ve kullanım istatistiklerini görüntülemek için API panelinde gösterilir.

İlk istek

curl

curl https://api.b444.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.b444.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.b444.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 Anahtarı Alın

İçin ses dalga görseli: API Anahtarı Alın

Voiser API’ye erişim için b444.info/get-api-key/ adresine giderek Google ile veya e-posta ve şifre ile kayıt olmanız gerekir. Her site için ayrı bir hesap oluşturulur ve doğrulama tamamlandığında API anahtarınız otomatik olarak atanır.

Tek bir aktif anahtar ile tüm isteklerinizi yönetebilirsiniz. Anahtarınızı güvenli bir yerde saklayın ve gereksiz yerlerde paylaşmayın. Her istek, Authorization başlığına Bearer token olarak eklenir.

Kayıt ve doğrulama

Kayıt ve doğrulama

Kayıt işlemi sırasında Google hesabınız veya e-posta adresiniz doğrulanır. Google ile giriş yapan kullanıcılara 7 gün geçerli $0.50 deneme kredisi tanımlanır. E-posta ve şifre ile kayıt olanlar bu krediyi almaz.

Kayıt tamamlandıktan sonra panelinizde API anahtarınız görüntülenir. Bu anahtar, API isteklerinizde kimlik doğrulama için kullanılır.

Anahtar yönetimi

Anahtar yönetimi

Her hesap için yalnızca bir aktif API anahtarı bulunur. Bu anahtar, tüm API isteklerinizde kullanılır. Anahtarınızı gizli tutun ve gereksiz yerlerde paylaşmayın.

API anahtarınızı kullandığınız her istek, o anahtara bağlı olarak sayılır. Anahtarınızı kaybettiğinizde veya güvenliği tehlikede olduğunda hemen yenileme yapabilirsiniz.

Yeni anahtar verme

Panel üzerinden yeni bir API anahtarı oluşturabilirsiniz. Eski anahtar, yeni anahtar oluşturulduğu anda geçersiz hale gelir.

Yeni anahtar, eski anahtarın tüm isteklerini hemen durdurur. Bu özellik, anahtarın kötüye kullanımını önlemek için kullanışlıdır.

İlk İstek (cURL)

İçin ses dalga görseli: İlk İstek (cURL)

Voiser API'ye ilk isteğinizi göndermek için temel HTTP başlıklarını ve geçerli API anahtarınızı yapılandırın. Bu adım, sunucunun isteğinizi doğrulaması ve ses üretim işlemini başlatması için zorunludur.

JSON body yapısı, model, ses ve metin parametrelerini içerir. Yanıt formatı, başarı durumunda ses dosyasını veya hata durumunda detaylı hata mesajını döndürür.

Gerekli başlıklar

POST isteğinizde Content-Type: application/json ve Authorization: Bearer tts-<API_KEY> başlıklarını belirtin. API anahtarınızı, /get-api-key/ sayfasından edindiğiniz aktif anahtar ile değiştirin.

JSON body yapısı

İstek gövdesi şu alanları içermelidir: model ("tts-1" veya "tts-1-hd"), input (4096 karakteri geçmeyen metin), voice (8 presetten biri) ve isteğe bağlı response_format ile speed.

  • model: "tts-1" veya "tts-1-hd"
  • input: Metin (max 4096 karakter)
  • voice: aria, nova, luna, sage, felix, milo, atlas, orion
  • response_format: mp3, wav, opus, flac, pcm

Yanıt formatı

Başarılı isteklerde, ses dosyası doğrudan yanıt gövdesinde döndürülür. Hata durumunda, HTTP hata kodu ve hata açıklaması içeren bir JSON nesnesi döndürülür. Başarısız sentezler için ücret iade edilir.

OpenAI SDK Entegrasyonu

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

OpenAI SDK’sini kullanarak entegrasyonunuzu gerçekleştirebilirsiniz. Tek yapmanız gereken base_url parametresini https://api.b444.info/v1 olarak ayarlamak ve mevcut API anahtarınızı yapılandırmaktır.

Bu yaklaşım, standart HTTP isteklerinden ziyade SDK'nın sağladığı yapılandırma kolaylığını sunar. Kodunuzu doğrudan kullanıma hazır hale getirir.

base_url değiştirme

OpenAI Python veya Node.js SDK’sını yükleyin. Yapılandırma nesnesinde base_url değerini https://api.b444.info/v1 olarak güncelleyin. api_key alanına Voiser anahtarınızı girin.

  • SDK sürümünüzün güncel olduğundan emin olun.
  • Temel URL doğru yazıldığından emin olun.

Kullanım örnekleri

Standart AudioModels.speech veya benzeri metotları çağırarak JSON gövdesini gönderin. İsteğin formatı OpenAI ile aynıdır; model, ses ve giriş metni parametrelerini iletin.

  • JSON yapısını doğrudan SDK metoduna geçirin.
  • Hata yönetimi için try-catch bloklarını kullanın.

Uyumluluk kontrolü

İstemci kütüphanesinin desteklediği endpoint yapısı ile Voiser API’si uyumludur. Parametrelerin doğru işlendiğinden emin olmak için test istekleri gönderin.

Ses ve Model Seçimi

İçin ses dalga görseli: Ses ve Model Seçimi

API, tts-1 ve tts-1-hd olmak üzere iki model sunar; her ikisi de aynı ses motorunu ve fiyatlandırmayı kullanır. Bu modeller, metni yüksek kaliteli ses dosyalarına dönüştürmek için temel yapı taşlarını oluşturur.

8 farklı ses preseti mevcuttur. Sesler, belirli ton ve kullanım alanlarına göre tasarlanmıştır. Bu yapı, endüstriyel bildirimler ve arayüzler için deterministik sonuçlar elde etmenizi sağlar.

tts-1 ve tts-1-hd modelleri

Her iki model de aynı motoru kullanır. Fiyat ve teknik özellikler açısından fark yoktur. İhtiyacınıza göre seçim yapabilirsiniz.

Ses listesi ve özellikleri

4 kadın ve 4 erkek ses vardır. Aria, Nova, Luna ve Sage kadın seslerdir. Felix, Milo, Atlas ve Orion erkek seslerdir. Sesler, LibriTTS-R verisinden üretilmiştir.

Her ses 23 dili destekler. Dil kodu belirtilmezse metne göre tahmin yapılır. Latin alfabeli metinler varsayılan olarak İngilizce olarak işlenir.

  • Aria: Sıcak, net anlatıcı.
  • Nova: Parlak, enerjik.
  • Luna: Yumuşak, hikaye anlatımı.
  • Sage: Sakin, öğretici.
  • Felix: Dinamik, tanıtım.
  • Milo: Samimi, sohbet.

Doğru ses seçimi

Sesler, belirli ton ve kullanım alanlarına göre tasarlanmıştır. Atlas nötr ve haber tonu sunar. Orion derin ve belgesel tarzındadır. Kullanım senaryonuza uygun sesi seçin.

İsteğin Gönderilmesi

İçin ses dalga görseli: İsteğin Gönderilmesi

Metin işleme, API'nin temel işlevi olarak, istemciden gelen JSON verisinin doğrulanması ve TTS motoruna iletilmesi ile başlar. Her istek, belirlenen karakter limitleri ve model seçimi doğrultusunda işlenir.

POST isteği yapısı

İstekler, POST https://api.b444.info/v1/audio/speech endpoint'ine JSON formatında gönderilir. Başlık alanında Authorization: Bearer <key> header'ı zorunludur.

Parametreler (model, input, voice)

Gövde kısmında model (tts-1 veya tts-1-hd), input (metin, max 4096 karakter) ve voice (8 preset) alanları tanımlanmalıdır. input alanı, ses dosyasına dönüştürülecek ham metni içerir.

  • Model: tts-1 veya tts-1-hd
  • Input: Karakter sınırı 4096
  • Voice: aria, nova, luna, sage, felix, milo, atlas, orion

Hız ve dil ayarları

speed parametresi 0.25 ile 4.0 arasında hız ayarı yapmanızı sağlar. language alanı opsiyoneldir; belirtilmezse sistem script'e göre tahmin yürütür (Latin script varsayılan İngilizce'dir).

Belirtilen dil kodu, sentezleme sırasında doğru dil modelinin kullanılmasını garantiler.

  • Speed: 0.25 - 4.0
  • Language: ISO kodu (opsiyonel)
İsteğin Gönderilmesi

Yanıt İşleme

İçin ses dalga görseli: Yanıt İşleme

API, başarılı sentezler için ses dosyasını doğrudan HTTP yanıt gövdesinde döndürür. İsteğe bağlı olarak response_format parametresiyle mp3, wav, opus, flac veya pcm formatı seçilebilir. Veri akışı, indirilebilir bir dosya olarak işlenir.

Yanıt başlıkları ve gövdesi, standart HTTP yapısında döndürülür. Gecikme, sunucu yüküne göre değişebilir; kısa cümleler için birkaç saniye, uzun metinler için gerçek zamanlıya yakın süreler öngörülür.

Ses dosyasının alınması

Başarılı bir istek sonrası, dönen HTTP yanıtının gövdesi doğrudan istenen ses formatında (örneğin mp3 veya wav) dosya verisi içerir. Bu veriyi kaydederek veya işleyerek uygulamalarınıza entegre edebilirsiniz.

Yanıt, Content-Type başlığıyla doğru MIME türünü belirtir. Dosya boyutu, metin uzunluğu ve seçilen formata göre değişir ancak doğrudan kullanılabilir yapıdadır.

Hata kodları

API, standart HTTP hata kodlarını kullanır. 4xx serisi istek hatalarını (geçersiz format, eksik parametre), 5xx serisi ise sunucu tarafındaki sorunları işaret eder.

Geçersiz parametreler 400 Bad Request döndürür. Yetkilendirme hataları ise 401 Unauthorized olarak karşılık bulur.

Başarısız istekler

Sentez işlemi sırasında bir hata oluşursa, harç ücreti tam olarak iade edilir. Hesabınızdan herhangi bir kesinti yapılmaz.

Bu durum, geçici sunucu yoğunluğu veya geçici bağlantı sorunları nedeniyle gerçekleşebilir. İsteği tekrar etmek, sorunun çözüldüğünden emin olmanızı sağlar.

Hız Sınırlamaları

İçin ses dalga görseli: Hız Sınırlamaları

API anahtarı başına dakikada 60 istek sınırı uygulanır. Bu limit, paralel isteklerin doğru işlenmesini sağlar.

Bu kural, sistem stabilitesini korur ve gereksiz yüklenmeyi önler.

Dakikada 60 istek

Her API anahtarı için dakika başına 60 istek sınırı geçerlidir. Bu limit, sunucu kaynaklarının adil dağıtımını sağlar.

Yükleme öncesi limit

Hesaplar ilk top-up işlemini gerçekleştirene kadar dakikada 10 istek sınırı ile çalışır. Bu, yeni kullanıcıların sistem kullanımını test etmesini sağlar.

Kuyruk yönetimi

İstekler sırayla işlenir. Yüksek trafikte bir istek kuyrukta bekleyebilir. Gerçek zamanlı akış yoktur, bu nedenle bekleyen istekler için zaman aşımı stratejileri geliştirin.

Uzun Metin İşleme

İçin ses dalga görseli: Uzun Metin İşleme

Tek bir API isteğinde işlenebilecek metin uzunluğu 4096 karakterle sınırlıdır. Bu sınır, hem standart hem de HD model için geçerlidir. Karakterler arasında boşluklar ve noktalama işaretleri de sayılır. Bu nedenle, uzun bildirim metinlerini veya kullanıcı arayüzü içeriklerini doğrud göndermek mümkün değildir.

4096 karakter sınırı

API, tek bir POST isteğinde maksimum 4096 karakterlik veri kabul eder. Bu limit, metnin bütünlüğü için kritiktir. Metin bu sınırı aştığında, sunucu hata döndürmez ancak işlemin tamamlanamayacağı anlamına gelir. Bu nedenle, içerikleriniz bu uzunluğa göre hazırlanmalıdır.

Bölümleme stratejisi

Uzun metinleri, karakter sınırlarını aşmayacak şekilde parçalara bölmelisiniz. Bölme işlemi, cümle sonlarında veya mantıksal birimlerde yapılmalıdır. Bu sayede, her parça bağımsız olarak işlenebilir. Parçaların sıralaması, orijinal metnin akışını bozmamak için dikkatlice korunmalıdır.

  • Mantıksal cümle yapılarını koruyun.
  • Aşırı uzun cümleleri ikiye bölün.
  • Boşlukları karakter sayısına dahil edin.

Ses birleştirme

Her bir parça için ayrı bir TTS isteği gönderin. Elde edilen ses dosyalarını, orijinal metnin sırasına göre ardışık olarak birleştirin. Bu işlem, istemci tarafında veya bir sunucu hizmetinde gerçekleştirilebilir. Birleştirme süreci, ses kalitesini etkilemez.

8 sesi dinleyin

Aşağıdaki her örnek, aynı cümle bu API tarafından üretilmiştir. Kısa uyarı mesajları veya bildirimler için bu süre birkaç saniye olarak gerçekleşir.

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. OpenAI API reference: create speech
  3. LibriTTS-R corpus (OpenSLR 141)
  4. FFmpeg documentation
  5. curl documentation
  6. openai-python on GitHub
  7. W3C WAI: making audio and video accessible
  8. Creative Commons Attribution 4.0
  9. Python documentation
  10. LibriTTS-R paper (arXiv 2305.18802)
  11. IETF RFC 7845: Ogg Opus
  12. Tether (USDT)

Sitede daha fazla