Sıkça sorulan sorular
API anahtarı nasıl alınır?
Anahtarı scp012.info/get-api-key/ adresinde Google veya e-posta ile kaydolarak alırsınız. Hesap başına tek aktif anahtar vardır. İstediğiniz zaman yeni anahtar oluşturabilirsiniz; eski anahtar anında geçersiz olur. Başlangıçta $0.50 deneme kredisi verilir.
Hangi SDK'lar desteklenir?
Resmi özel SDK'mız yoktur. OpenAI SDK'larını kullanabilirsiniz. base_url'i https://api.scp012.info/v1 olarak değiştirip kendi API anahtarınızı ayarlayın. Standart HTTP istekleri de doğrudan desteklenir. Başka bir mobil veya özel yazılım geliştirme kiti bulunmamaktadır.
base_url nedir?
API'nin temel adresidir: https://api.scp012.info/v1. OpenAI SDK'larını kullanırken bu adresi yapılandırmanız gerekir. Bu URL, POST /v1/audio/speech ve GET /v1/voices gibi uç noktaların temelini oluşturur. Anahtarınızı Authorization başlığında bu adrese gönderirsiniz.
Hangi ses formatları mevcuttur?
MP3, WAV, Opus, FLAC ve PCM formatlarını destekleriz. response_format alanına bu değerlerden birini göndererek istek yapabilirsiniz. Varsayılan format mp3'tür. Tüm formatlar eşit fiyatlandırma ile sunulur.
İstek limiti nedir?
Anahtar başına dakikada 60 istek limitiniz vardır. İlk yüklemeniz yapılmadan önce bu limit dakikada 10'dur. Bu limitler API anahtarınız için geçerlidir. Limit aşımında istekleriniz reddedilir. Uzun metinler için parçalama stratejisi bu limiti verimli kullanmanızı sağlar.
Ses dosyası nasıl indirilir?
API yanıtı doğrudan ses dosyasını içerir. HTTP isteklerinizde yanıt gövdesini kaydederek dosyayı elde edersiniz. Dosya sunucuda saklanmaz, anlık olarak iletilir. İndirme işlemi için ek bir endpoint gerekmez; POST isteğinizin sonucu doğrudan audio verisidir.
Hangi hata kodları döner?
Belirtilmiş spesifik hata kodları listesi yoktur. Yanıt durum kodları HTTP standartlarına uygundur. Örneğin, yetkisiz erişim 401 döner. API yanıt gövdesinde hata detayları yer alabilir. Belirli bir hata kodu referans listesi mevcut değildir.
Karakter sınırı nedir?
Her istek için maksimum 4096 karakter sınırı vardır. Bu sınırı aşan metinleri client tarafında parçalara bölüp ayrı istekler göndermelisiniz. Boşluklar ve noktalama işaretleri karakter sayısına dahildir. Parçaları birleştirerek daha uzun metinleri seslendirebilirsiniz. Bu sayede esnek kullanım sağlanır.
Ses hızı ayarlanabilir mi?
Evet, speed parametresi ile 0.25 ile 4.0 arasında hız ayarı yapabilirsiniz. Bu ayar, sesin daha hızlı veya daha yavaş konuşmasını sağlar. Özellikle navigasyon ipuçları için hızı optimize edebilirsiniz. Parametre isteğe bağlıdır.
Hangi diller desteklenir?
23 dil desteklenir: İngilizce, Türkçe, Almanca, İspanyolca, Fransızca, Arapça, Çince, Japonca ve diğerleri. Sesler tüm dillerde çalışır. Dil belirtmezseniz script'e göre tahmin yapılır; Latin alfabesi varsayılan olarak İngilizce kabul edilir. Desteklenmeyen diller listesi mevcuttur.
Sesler nasıl seçilir?
8 preset ses arasından seçim yapın: Aria, Nova, Luna, Sage (kadın); Felix, Milo, Atlas, Orion (erkek). Her sesin farklı tonu vardır. GET /v1/voices endpointi ile mevcut sesleri listeleyebilirsiniz. Sesler lisanslı kayıtlardan oluşturulmuştur. Doğru sesi seçmek deneyimi iyileştirir.
Hata durumunda ne olur?
Sentez başarısız olursa ücret iade edilir. Tam ücret iadesi yapılır. Başarısız istekler ücretsizdir. Yanıtınızda hata detaylarını kontrol edin. Ses dosyası üretilmezse herhangi bir ücret yansıtılmaz. Bu politika, teknik aksaklıklarda müşteriyi korur.
İstekler nasıl yapılır?
POST https://api.scp012.info/v1/audio/speech adresine JSON body gönderin. Authorization başlığında Bearer token kullanın. Model, input, voice ve response_format alanlarını doldurun. OpenAI SDK yapısı ile uyumludur. İstekler sırayla işlenir, yük altında kuyruk oluşabilir.
Veri formatı nedir?
İstekler JSON formatında gönderilir. Yanıt ise seçilen ses formatında (mp3, wav vb.) binary veridir. JSON body'de model, input, voice ve hız parametreleri bulunur. Input alanı metni içerir. Yanıt gövdesi doğrudan ses dosyası akışıdır. Başlıklar HTTP standardındadır.
İlk istek
curl
curl https://api.scp012.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.scp012.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.scp012.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ı Almak
AracAPI'ye erişim için /get-api-key/ sayfasına giderek hesabınızı oluşturun. Google hesabınızla giriş yapmak, 7 gün geçerli $0.50 deneme kredisi (yaklaşık 50.000 karakter) ile başlamanızı sağlar. Bu kredi, navigasyon metinlerinizin ilk testlerini gerçekleştirmeniz için yeterli bir başlangıç noktasıdır.
E-posta ve şifre ile kayıt olan kullanıcılar deneme kredisi almaz ancak doğrudan kullanıma başlar. Her hesap için tek bir aktif API anahtarı üretilir. Bu anahtar, API isteklerinizin yetkilendirilmesi için Authorization: Bearer başlığında kullanılır.
Google ile kayıt
Kayıt sırasında Google hesabınızı kullanarak hızlıca erişim sağlayın. Sistem, hesabınızı oluştururken otomatik olarak $0.50 deneme kredisi yükler. Bu kredi 7 gün boyunca geçerlidir ve karakter başı $0.01 fiyatlandırmaya göre yaklaşık 50.000 karakterlik metin işlemenize olanak tanır.
- Anında erişim ve deneme kredisi
- Yüksek doğrulama güvenliği
- 7 günlük geçerlilik süresi
E-posta ile kayıt
Daha geleneksel bir yöntemle, e-posta ve şifre kombinasyonu ile hesap oluşturabilirsiniz. Bu yöntemle kayıt olan kullanıcılar deneme kredisi ile başlamaz; ancak istedikleri an USDT (TRC-20) ile bakiye yükleyerek doğrudan üretim ortamına geçebilirler.
- Kredi bağımsız kullanım
- Geleneksel kimlik doğrulama
- Doğrudan top-up seçeneği
Anahtar yenileme
API anahtarınız güvenliği nedeniyle değiştiğinde veya eski anahtarın erişimini kesmek istediğinizde, panel üzerinden yeni bir anahtar üretebilirsiniz. Eski anahtar anında geçersiz hale gelir. Yeni anahtarınız panelde listelenir ve tüm isteklerinizde bu yeni değeri kullanmanız gerekir.
- Anında geçersizlik
- Tek aktif anahtar kuralı
- Panel üzerinden yönetim
İlk İstek (cURL)
AracAPI ile ses üretmek için POST https://api.scp012.info/v1/audio/speech endpoint'ine bir JSON isteği göndermeniz gerekir. Bu yapı, OpenAI Speech endpoint'i ile aynıdır; bu nedenle mevcut araçlarınızda sadece base_url'i güncellemeniz yeterlidir.
İstek gövdesinde model, ses, dil ve çıktı formatı gibi parametreleri belirleyerek metninizden ses dosyasına geçiş yapabilirsiniz. Başarılı bir istek, binary olarak ses dosyasını döndürür.
JSON body yapısı
İstek gövdesi şu alanları içermelidir: model ("tts-1" veya "tts-1-hd"), input (maksimum 4096 karakter metin), voice (8 presetten biri) ve response_format (mp3, wav, opus, flac, pcm). speed parametresi 0.25 ile 4.0 arasında ayarlanabilir. language alanı opsiyoneldir; belirtilmezse sistem dili tahmin etmeye çalışır.
Metin, araba içi kullanım için optimize edilmiş kısa cümleler halinde hazırlanmalıdır. Her istek bağımsızdır; uzun metinler için client-side parçalama yapılması önerilir.
Ses dosyası üretme
API, isteği aldıktan sonra metni işleyip belirlenen formatta ses dosyasını döndürür. Ortalama hız, uzun metinlerde saniyede yaklaşık 25 karakterlik metne karşılık gelen gerçek zamanlı üretim hızındadır.
Kısa ifadeler için üretim birkaç saniye sürebilir. İstekler sırayla işlendiğinden, yüksek yük altında bir kuyruk oluşabilir.
- Metin uzunluğu: 4096 karakter sınır
- Karakter hesabı: Boşluklar ve noktalama işaretleri dahildir
- Formatlar: mp3, wav, opus, flac, pcm
Hata kodları
Geçersiz parametreler veya karakter sınırı aşımı durumunda 4xx hataları döndürülür. API sunucusundaki yoğunluk veya geçici arızalar 5xx hatalarına neden olabilir.
Önemli olan: Sentez başarısız olursa, istek bedeli iade edilir. Yani, hatalı istekler için ödeme yapılmaz. Bu nedenle, hata kodlarını yakalayıp kullanıcıya bildirmek kritik öneme sahiptir.
OpenAI SDK Entegrasyonu
AracAPI, OpenAI Speech endpoint’iyle aynı JSON yapısını kullandığı için mevcut OpenAI SDK’lerini doğrudan entegre edebilirsiniz. Tek yapmanız gereken base_url parametresini https://api.scp012.info/v1 olarak ayarlamak ve API anahtarınızı geçmektir.
Bu yöntemle hem Python hem de JavaScript SDK’larını sorunsuz kullanabilir, ekstra bir kütüphane kurulumu yapmadan projelerinize TTS özelliğini ekleyebilirsiniz.
base_url değiştirme
SDK yapılandırmasında base_url alanını https://api.scp012.info/v1 olarak güncelleyin. Bu, isteklerin doğru API’ye yönlendirilmesini sağlar.
Kod örneği
Aşağıdaki Python kodu, OpenAI SDK’sını kullanarak ses üretir. base_url ve api_key alanlarını kendi bilgilerinizle doldurun.
```python import openai client = openai.OpenAI( base_url="https://api.scp012.info/v1", api_key="tts-..." ) response = client.audio.speech.create( model="tts-1", voice="nova", input="Navigasyon yönergeleri güncellendi." ) response.stream_to_file("navigation.mp3") ```
Kütüphane uyumluluğu
Resmi OpenAI Python ve JavaScript SDK’ları bu yapıyla tam uyumludur. tts-1 ve tts-1-hd modelleri desteklenir; diğer OpenAI TTS modelleri bu endpoint’te mevcut değildir.
Ses Formatları
API, üretim ve geliştirme süreçleriniz için dört farklı ses formatı sunar. İster hafif bir web uygulaması ister yüksek kaliteli bir navigasyon sistemi geliştirin, format seçimi dosya boyutu ve uyumluluk arasında denge kurmanızı sağlar.
Her format, belirli kullanım senaryolarına göre optimize edilmiştir. MP3, geniş uyumluluk için idealken; WAV ve FLAC, işleme gerektirmeyen ham veri akışı için tasarlanmıştır.
MP3 desteği
MP3, geniş cihaz desteği ve düşük dosya boyutu sayesinde navigasyon uygulamaları için varsayılan tercihtir. Metinler araba içi dinamiklere uygun şekilde dönüştürüldüğünde, ağ trafiği minimize edilir ve kullanıcı deneyimi hızlanır.
API, MP3 formatını varsayılan olarak döndürür.
WAV ve Opus
WAV formatı, başlık bilgisi olmadan ham PCM verisi sağlar ve işlemci yükünü azaltır. Opus ise yüksek sıkıştırma oranıyla modern tarayıcılar ve mobil uygulamalar için verimlidir.
Bu formatlar, özellikle ses dosyalarının sunucuda depolanmadığı, doğrudan kullanıcıya iletilmediği senaryolarda işleniş hızını artırır. İsteğe bağlı olarak response_format parametresiyle seçilebilirler.
FLAC ve PCM
FLAC, kayıpsız sıkıştırma sunar ve ses kalitesini bozmadan dosya boyutunu küçültür. PCM ise sıkıştırmasız ham dijital ses verisi sağlar; özellikle ses işleme yazılımlarıyla entegrasyon için idealdir.
Bu formatlar, navigasyon sistemlerinde sesin sonradan işlenmesi veya analizi gereken durumlarda tercih edilir. API, bu formatları doğrudan yanıt olarak döndürür.
Hız ve Limitler
AracAPI, dakikada 60 isteklik bir limit ile yüksek frekanslı navigasyon senaryolarını destekler. Bu limit, her API anahtarı için geçerlidir ve kısa süreli yüksek trafikte bile istikrarlı bir hizmet sunar. Test aşamasında bu limit 10 istek/dakika olarak düşer.
Dakikada 60 istek
Her API anahtarı için dakikada 60 istek hakkı tanınır. Bu oran, navigasyon uygulamalarında sık tekrarlanan kısa uyarılar için yeterlidir. İlk kullanım sırasında bu limit dakikada 10 istek olarak başlar.
- Dakikada 60 istek (test modunda 10)
Karakter sınırı
Her istek için maksimum 4096 karakter metin gönderilebilir. Boşluklar ve noktalama işaretleri de bu sınıra dahildir. Daha uzun metinler için istemci tarafında bölme ve birleştirme işlemi yapılmalıdır.
Kuyruk yönetimi
İstekler sırayla işlenir. Yüksek talepte bir istek, kuyrukta bekleyebilir. Ortalama hız, saniyede yaklaşık 25 karakter metnin işlenmesiyle gerçek zamanlı ses üretimine eşdeğerdir.

Ses Seçenekleri
AracAPI, navigasyon ve içeren metinler için optimize edilmiş 8 önceden ayarlanmış ses sunar. Her ses, belirli bir ton ve kullanım senaryosu için tasarlanmıştır; bu da aracın içindeki dinamiklere uygun doğal bir dinleme deneyimi sağlar.
8 preset ses
Sistemde 8 farklı ses profili bulunur: Aria, Nova, Luna ve Sage kadın; Felix, Milo, Atlas ve Orion erkek sesleridir. Bu sesler, LibriTTS-R verisi ve LibriVox'dan alınan kamu malı ses kayıtlarına dayanır. Her ses, belirli bir atmosferi yansıtmak üzere eğitilmiştir.
- Aria: Sıcak, net anlatıcı
- Nova: Parlak, enerjik
- Luna: Yumuşak, hikaye anlatımı
- Sage: Sakin, yönerge tarzı
- Felix: Enerjik, promosyon
- Milo: Dostça, konuşma tarzı
- Atlas: Nötr, haber tarzı
- Orion: Derin, belgesel tarzı
Cinsiyet ve ton
Sesler, cinsiyet ve ton ayrımıyla kategorize edilmiştir. Örneğin, Felix promosyon metinleri için uygunken, Atlas haber bültenleri için daha nötr bir tonda çalışır. Orion, belgesel tarzı içerikler için derin bir ses sunar. Bu tonlar, navigasyon metinlerinin dinleyici üzerinde yaratacağı etkiyi belirler.
Dil seçimi
API, 23 dilde ses üretimi sağlar. Bu diller arasında Arapça, Çince, İngilizce, Almanca, İspanyolca ve Türkçe bulunur. Eğer 'language' alanı belirtilmezse, sistem metnin scriptine göre dil tahmini yapar; Latin alfabesi kullanılıyorsa varsayılan olarak İngilizce kabul edilir. Diğer diller için dil kodunu açıkça belirtmek önerilir.
Hata Yönetimi
API istekleriniz sırasında karşılaşabileceğiniz hata durumları, genellikle geçici kuyruk yoğunluğu veya geçersiz parametrelerden kaynaklanır. 4xx hataları istek formatındaki eksiklikleri, 5xx hataları ise sunucu tarafındaki anlık yüklenmeleri işaret eder.
4xx ve 5xx hatalar
401 Yetkisiz hata, yanlış API anahtarı kullanıldığını gösterir. 400 Bad Request, 4096 karakter sınırını aşan metinler veya desteklenmeyen format parametreleri için döner. 500 veya 503 hataları, sunucunun anlık yoğunluk nedeniyle yanıt veremediğini belirtir.
- 401: Geçersiz API anahtarı
- 400: Geçersiz istek parametresi
- 503: Servis geçici olarak kullanılamıyor
Tekrar deneme stratejisi
Dakikada 60 istek limiti ve kuyruk yapısı nedeniyle kısa süreli gecikmeler yaşanabilir. Hızlı tekrar denemeler (exponential backoff) yerine, isteklerinizin sırayla işlendiğini göz önünde bulundurarak daha geniş aralıklarla deneme yapmanız sistemi yormaz ve başarı şansınızı artırır.
Başarısız istekler
Sunucu tarafında bir sentez hatası oluşursa, istek başarısız sayılır ve ücret iade edilir. Bu durumda herhangi bir ekstra ücret yansıtılmaz. İstek meta verileri faturalandırma için saklanır ancak ses dosyası kaydedilmez, bu da veri bütünlüğünüzü korur.
Kod Örnekleri
Entegrasyon, hedef kitleye uygun araç içi seslendirme akışlarını hızlıca hayata geçirmek için kritik öneme sahiptir. Aşağıdaki örnekler, AracAPI'nin OpenAI SDK uyumlu yapısını ve temel HTTP protokolünü gösterir.
Python ve JavaScript örnekleri, metnin parçalara bölünmesi ve ses dosyalarının birleştirilmesi gibi karmaşık senaryoları basitleştirir. Bu yaklaşımlar, GPS yönergeleri veya trafik bilgilendirmeleri gibi kısa metinlerin sorunsuz çalışmasını sağlar.
Python örneği
OpenAI Python SDK'sını kullanarak base_url'i https://api.scp012.info/v1 olarak ayarlayın. API anahtarınızı tts-... formatında girerek ses üretin. 4096 karakter sınırını aşan metinler için kendi bölme mantığınızı ekleyin.
JavaScript örneği
Aynı mantık Node.js ortamında da geçerlidir. fetch API'sini kullanarak POST isteği gönderin veya OpenAI JS SDK'sını yapılandırın. Yanıtı arraybuffer olarak alın ve ses dosyasını kaydedin.
HTTP isteği
Doğrudan HTTP POST isteği ile https://api.scp012.info/v1/audio/speech adresine veri gönderin. Authorization: Bearer tts-... başlığını ekleyin. JSON body'de model, input ve voice alanlarını doldurun.
8 sesi dinleyin
Aşağıdaki her örnek, aynı cümle bu API tarafından üretilmiştir. Sesli asistanlar, sürücülerle etkileşim kurarak bilgi sağlar.
23 dil
Her ses bu dillerden birini konuşabilir.
