Konuşmatik Developer API

Yerel Konuşmatik TTS ve ASR modellerini REST API veya Realtime WebSocket üzerinden uygulamalarınıza entegre edin.

1
Anahtar Oluşturunkm_live_ anahtarınızı edinin
2
Modeli SeçinKonuşmatik TTS veya ASR
3
Üretime GeçinREST veya Realtime kullanın

Hızlı Başlangıç & Kimlik Doğrulama

Konuşmatik API servislerine doğrudan REST uç noktaları veya OpenAI Python SDK üzerinden bağlanabilirsiniz.

01

API Anahtarınızı Edinin

Konuşmatik web panelinizden (Profil / API Anahtarları) bir anahtar oluşturun ve KONUSMATIK_API_KEY ortam değişkeninde saklayın.

02

OpenAI SDK veya REST Seçin

Canonical uç noktalar resmi OpenAI Python SDK ve cURL istekleriyle doğrudan uyumludur. Yüksek hacimli toplu işler için Kurumsal Asenkron API kullanın.

03

Üretim Modelleriyle Çalışın

Resmi model isimleri: konusmatik-asr-v2 ve konusmatik-tts-v2. TTS sesleri: sila, deniz, taha.

REST APIProduction Base URLhttps://api.konusmatik.com/api/v1
WebSocket APIRealtime Stream URLwss://api.konusmatik.com/api/v1/realtime

Kimlik Doğrulama (Bearer Token)

Tüm API isteklerinizi HTTP Authorization başlığı altında API anahtarınız ile gönderin.

HTTP Header
Authorization: Bearer $KONUSMATIK_API_KEY

OpenAI Python SDK Compatible API

Mevcut OpenAI SDK entegrasyonunuzda yalnızca base_url, API anahtarı ve Konuşmatik model adını tanımlayın. ASR, TTS ve model listeleme işlemlerini standart SDK metotlarıyla çağırın.

Kurulum ve İstemci Tanımı

Resmi openai paketini kurarak başlayın:

pip install openai # Linux / macOSexport KONUSMATIK_API_KEY="km_live_..." # Windows PowerShell$env:KONUSMATIK_API_KEY="km_live_..." # Windows CMDset KONUSMATIK_API_KEY=km_live_...

OpenAI SDK ile Konuşmatik TTS

Konuşmatik TTS, Türkçe metinleri doğal ve akıcı biçimde seslendirir. Sesin tamamı oluşturulduktan sonra üretilen ses verisi istemciye tek bir kayıpsız WAV dosyası olarak döner. Bu yapı özellikle ses dosyası oluşturma, arşivleme ve tamamlanmış içeriğin sonradan oynatıldığı uygulamalar için uygundur.

POST/audio/speech

Sesin tamamı üretildikten sonra başarılı yanıt tek bir audio/wav binary içeriği döndürür. (WAV-Only)

Doğal Türkçe Sesler

Sıla

KadınDoğal & Akıcı

Asistan, müşteri deneyimi, eğitim ve uzun anlatımlar için dengeli doğal kadın sesi.

Deniz

KadınKurumsal & Net

Haber bültenleri, kurumsal duyurular ve resmi açıklamalar için net kadın sesi.

Taha

ErkekDinamik & Güçlü

Diyaloglar, kısa bilgilendirmeler ve dinamik içerikler için modern erkek sesi.

İstek Parametreleri

ParametreTürZorunluVarsayılanAçıklama
modelstringEvetkonusmatik-tts-v2Üretim TTS model adı: konusmatik-tts-v2
inputstringEvet-Seslendirilecek metin (Maksimum 10.000 karakter).
voicestringEvetsilaSes seçimi: sila (Kadın), deniz (Kadın), taha (Erkek).
response_formatstringHayırwavÜretim standardı gereği WAV-only format desteklenir. (audio/wav)
speednumberHayır1.0Konuşma hızı çarpanı (0.25 - 4.0).

Kod Örnekleri

import osfrom pathlib import Pathfrom openai import OpenAI client = OpenAI(    api_key=os.environ["KONUSMATIK_API_KEY"],    base_url="https://api.konusmatik.com/api/v1",) speech_file_path = Path("speech.wav") with client.audio.speech.with_streaming_response.create(    model="konusmatik-tts-v2",    voice="sila",    input="Merhaba, Konuşmatik API testine hoş geldiniz.",    response_format="wav",) as response:    response.stream_to_file(speech_file_path) print(f"Ses dosyası kaydedildi: {speech_file_path}")

OpenAI SDK ile Konuşmatik Streaming TTS

Konuşmatik Streaming TTS, sesin tamamının oluşturulmasını beklemeden üretilen ses verisini istemciye aktarmaya başlar. Bu yapı özellikle gerçek zamanlı ses oynatma, sesli asistanlar ve düşük gecikmeli uygulamalar için uygundur.

POST/audio/speech

PCM ses verisini parça parça aktarır.

Model
konusmatik-streaming-tts-v2
Desteklenen sesler
sila · deniz · taha
Çıktı formatı
PCM16LE
Gerekli parametre
response_format="pcm"

Streaming TTS isteklerinde response_format değeri pcm olmalıdır.

Python SDK Örneği

import asyncioimport osfrom openai import AsyncOpenAIimport openai.helpers.local_audio_player as lapfrom openai.helpers import LocalAudioPlayer lap.SAMPLE_RATE = 48000 openai = AsyncOpenAI(    api_key=os.environ["KONUSMATIK_API_KEY"],    base_url="https://api.konusmatik.com/api/v1",) async def main() -> None:    async with openai.audio.speech.with_streaming_response.create(        model="konusmatik-streaming-tts-v2",        voice="deniz",        input="Merhaba, Konuşmatik Streaming TTS ile ses gerçek zamanlı olarak oluşturulmaktadır.",        response_format="pcm",    ) as response:        await LocalAudioPlayer().play(response) if __name__ == "__main__":    asyncio.run(main())

Response Headers

HTTP Headers
Content-Type: audio/pcm
X-Audio-Sample-Rate: <sample_rate>
X-Audio-Channels: <channels>
X-Audio-Format: pcm_s16le
X-Request-ID: <request_id>

Streaming veri sözleşmesi

Ses verileri stream üzerinden parça parça iletilir. Chunk boyutları sabit değildir ve istemci uygulamaları chunk sınırlarına bağlı bir mantık oluşturmamalıdır. Gelen PCM verileri sırasıyla oynatılabilir, kaydedilebilir veya farklı bir ses formatında işlenebilir.

OpenAI SDK ile Konuşmatik ASR

100 MB boyuta ve 3 saate kadar ses dosyalarını yüksek doğrulukla Türkçe metne dönüştürün.

POST/audio/transcriptions

İstek gövdesi multipart/form-data olarak gönderilmelidir.

Desteklenen formatlar
WAVMP3M4AWEBMOGG

İstek Parametreleri

ParametreTürZorunluVarsayılanAçıklama
filefileEvet-Ses dosyası (Maksimum 100 MB, Maksimum 3 saat / 10.800s).
modelstringEvetkonusmatik-asr-v2Üretim ASR model adı: konusmatik-asr-v2
languagestringHayırtrSes dili (Varsayılan: tr). Şu an yalnızca Türkçe desteklenir; diğer değerler 400 unsupported_language hatası döner.
response_formatstringHayırjsonjson, text veya verbose_json.

Kod Örnekleri

import osfrom openai import OpenAI client = OpenAI(    api_key=os.environ["KONUSMATIK_API_KEY"],    base_url="https://api.konusmatik.com/api/v1",) with open("ses_kaydi.wav", "rb") as audio_file:    transcription = client.audio.transcriptions.create(        model="konusmatik-asr-v2",        file=audio_file,        language="tr",        response_format="json",    ) print("Deşifre Metni:", transcription.text)

OpenAI SDK ile Konuşmatik Realtime ASR

AsyncOpenAI istemcisiyle mikrofonunuzdan PCM16 ses gönderin ve canlı deşifre olaylarını doğrudan dinleyin.

WSS/realtime

OpenAI Python SDK uyumlu gerçek zamanlı deşifre bağlantısı.

Python Örneği

import asyncioimport base64import os import sounddevice as sdfrom openai import AsyncOpenAI SAMPLE_RATE = 24000CHANNELS = 1BLOCK_SIZE = 2400  # 100 ms  async def main():    client = AsyncOpenAI(        api_key=os.environ["KONUSMATIK_API_KEY"],        base_url="https://api.konusmatik.com/api/v1",    )     audio_queue = asyncio.Queue()    loop = asyncio.get_running_loop()     def audio_callback(indata, frames, time, status):        if status:            print(status)         loop.call_soon_threadsafe(            audio_queue.put_nowait,            bytes(indata),        )     async with client.realtime.connect(        model="konusmatik-asr-v2",    ) as connection:        await connection.session.update(            session={                "input_audio_format": "pcm16",                "turn_detection": {                    "type": "server_vad",                },            }        )         async def send_audio():            while True:                pcm_chunk = await audio_queue.get()                audio_b64 = base64.b64encode(pcm_chunk).decode("ascii")                 await connection.input_audio_buffer.append(                    audio=audio_b64,                )         async def receive_events():            async for event in connection:                if event.type == "conversation.item.input_audio_transcription.delta":                    print(event.delta, end="", flush=True)                 elif event.type == "conversation.item.input_audio_transcription.completed":                    print(f"\nFinal: {event.transcript}")                 elif event.type == "error":                    print(f"\nHata: {event}")         with sd.RawInputStream(            samplerate=SAMPLE_RATE,            channels=CHANNELS,            dtype="int16",            blocksize=BLOCK_SIZE,            callback=audio_callback,        ):            print("Dinleniyor... Ctrl+C ile çıkabilirsiniz.")             await asyncio.gather(                send_audio(),                receive_events(),            )  if __name__ == "__main__":    asyncio.run(main())

OpenAI SDK ile Konuşmatik Modelleri

Konuşmatik servisleri kamuya açık resmi model kimlikleriyle çalışır.

konusmatik-asr-v2

Konuşmatik ASR v1

Konuşma Tanıma (STT)

Ses dosyalarını yüksek doğrulukla Türkçe metne dönüştürür.

Girdi
multipart/form-data (MP3, WAV, M4A, WEBM, OGG)
Çıktı
json, text, verbose_json
Kapasite
14 Eşzamanlı GPU İnference
konusmatik-tts-v2

Konuşmatik TTS v1

Doğal Ses Sentezi (TTS)

Türkçe metinleri doğal ve akıcı seslendirerek kayıpsız WAV ses çıktısı üretir.

Girdi
JSON body (max 10.000 karakter)
Çıktı
audio/wav (RIFF/WAVE Binary)
Kapasite
32 Eşzamanlı GPU İnference
GET/models

Aktif üretim modellerini listeler.

Kod Örnekleri

import osfrom openai import OpenAI client = OpenAI(    api_key=os.environ["KONUSMATIK_API_KEY"],    base_url="https://api.konusmatik.com/api/v1",) models = client.models.list()for model in models.data:    print("Model ID:", model.id)

Konuşmatik Asenkron API

Kurumsal API, yüksek hacimli toplu ASR ve TTS işleri için job tabanlı asenkron kuyruk modeli sunar. POST istekleri inference bitimini beklemez; anında HTTP 201 Created ve job_id döndürür.

Konuşmatik Asenkron ASR

Ses dosyasını kuyruğa ekleyin, işi tamamlanana kadar takip edin ve transkripsiyon sonucunu alın.

POST/corporate/asr/jobs

Yeni bir ASR işi kuyruğa ekler ve hemen job_id döndürür.

GET/corporate/asr/jobs/{id}

İş durumunu sorgular (pending, processing, completed, failed).

GET/corporate/asr/jobs/{id}/result

Tamamlanan işin transkripsiyon metnini döndürür.

İş Oluşturma, Polling ve Sonuç Alma

import osimport timeimport requests API_KEY = os.environ["KONUSMATIK_API_KEY"]BASE_URL = "https://api.konusmatik.com/api/v1"HEADERS = {"Authorization": f"Bearer {API_KEY}"} def transcribe_audio_corporate_async(file_path: str) -> str:    # 1. İşi Oluştur (HTTP 201 Created döner, bağlantı inference süresince açık kalmaz)    with open(file_path, "rb") as f:        resp = requests.post(            f"{BASE_URL}/corporate/asr/jobs",            headers=HEADERS,            files={"file": (os.path.basename(file_path), f, "audio/wav")},            data={"language": "tr"}        )    resp.raise_for_status()    job_id = resp.json()["id"]    print(f"İş başarıyla kabul edildi. Job ID: {job_id}")     # 2. Polling ile Durumu Sorgula (2-3 saniyelik makul aralık)    while True:        poll_resp = requests.get(f"{BASE_URL}/corporate/asr/jobs/{job_id}", headers=HEADERS)        poll_resp.raise_for_status()        job_data = poll_resp.json()        status = job_data["status"]         if status == "completed":            print("İş tamamlandı!")            break        elif status == "failed":            raise RuntimeError(f"İş başarısız oldu: {job_data.get('error_message')}")         print(f"Mevcut durum: {status}... Bekleniyor.")        time.sleep(2.5)     # 3. Sonucu Al    result_resp = requests.get(f"{BASE_URL}/corporate/asr/jobs/{job_id}/result", headers=HEADERS)    result_resp.raise_for_status()    return result_resp.json()["text"] if __name__ == "__main__":    text = transcribe_audio_corporate_async("toplanti_kaydi.wav")    print("\nTranskripsiyon Sonucu:\n", text)

URL ile ASR İşi (Dosya Yüklemeden)

Ses veya video dosyasını yüklemek yerine HTTPS adresini verin; Konuşmatik dosyayı sunucu tarafında indirir ve kuyruğa alır. Yanıt HTTP 202 Accepted döner.

POST/corporate/asr/jobs/url

Uzak bir URL'den asenkron ASR işi oluşturur. /corporate/asr/jobs uç noktası da JSON gövdede audio_url kabul eder.

ParametreTürZorunluVarsayılanAçıklama
audio_urlstringEvet-Doğrudan erişilebilir HTTPS ses veya video adresi. Özel/iç ağ adresleri engellenir (SSRF koruması). Maksimum 100 MB.
languagestringHayırtrSes dili. Şu an yalnızca Türkçe (tr) desteklenir; diğer değerler 400 unsupported_language döner.
timestamp_granularitiesstring[]Hayır-"segment" ve/veya "word". Sonuçta zaman damgalı segment ve kelime listesi döner.
webhook_iduuidHayır-Kayıtlı ve aktif bir webhook uç noktasının kimliği. İş bitince olay bu adrese gönderilir.
import osimport requests API_KEY = os.environ["KONUSMATIK_API_KEY"]BASE_URL = "https://api.konusmatik.com/api/v1"HEADERS = {"Authorization": f"Bearer {API_KEY}"} # Dosya yüklemeden, uzak bir URL'den asenkron ASR işi başlat (HTTP 202 Accepted)resp = requests.post(    f"{BASE_URL}/corporate/asr/jobs/url",    headers=HEADERS,    json={        "audio_url": "https://cdn.example.com/kayitlar/toplanti.mp3",        "language": "tr",        "timestamp_granularities": ["segment", "word"],        "webhook_id": "WEBHOOK_ID_BURAYA",  # opsiyonel    },)resp.raise_for_status()job_id = resp.json()["job_id"]print("Job ID:", job_id) # Sonuç: segments, words, srt ve vtt alanlarını içerirresult = requests.get(    f"{BASE_URL}/corporate/asr/jobs/{job_id}/result",    headers=HEADERS,    params={"timestamp_granularities[]": ["segment", "word"]},).json()for word in result["words"][:5]:    print(word["word"], word["start"], word["end"])

Zaman Damgaları ve Sonuç Alanları

İş oluştururken veya sonuç alırken timestamp_granularities[] ile segment ve/veya word seçin. Sonuç ayrıca srt ve vtt altyazı çıktıları içerir.

GET/corporate/asr/jobs/{id}/download

Sonuç dosyası için süreli indirme bağlantısı döndürür (url, expires_in_seconds).

ParametreTürZorunluVarsayılanAçıklama
job_iduuidEvet-İş kimliği.
statusstringEvet-pending, processing, completed veya failed.
textstringHayırnullTam transkripsiyon metni.
segmentsarrayHayır[]Her biri id, start, end, text içeren zaman damgalı cümleler.
wordsarrayHayır[]Her biri word, start, end ve opsiyonel probability içeren kelime zamanları.
srt / vttstringHayırnullHazır altyazı çıktıları.
errorstringHayırnullİş başarısız olduysa hata mesajı.

Senkron ASR

POST/corporate/asr/jobs/sync

Kısa dosyalar için kuyruk beklemeden sonucu aynı istekte döndürür (HTTP 201).

import osimport requests API_KEY = os.environ["KONUSMATIK_API_KEY"]BASE_URL = "https://api.konusmatik.com/api/v1" # Kısa dosyalar için: sonuç aynı istekte döner (HTTP 201)with open("kisa_kayit.wav", "rb") as f:    resp = requests.post(        f"{BASE_URL}/corporate/asr/jobs/sync",        headers={"Authorization": f"Bearer {API_KEY}"},        files={"file": ("kisa_kayit.wav", f, "audio/wav")},        data={"language": "tr", "timestamp_granularities[]": ["segment", "word"]},    )resp.raise_for_status()print(resp.json()["text"])

Webhook Bildirimleri

Polling yapmak yerine, ASR işi tamamlandığında veya başarısız olduğunda Konuşmatik'in HTTPS adresinize imzalı bir olay göndermesini sağlayın.

Uç Nokta Yönetimi

MetodYolAçıklama
POST/corporate/webhooksYeni webhook uç noktası kaydeder. Yanıttaki secret (whsec_...) imza doğrulaması için saklanmalıdır.
GET/corporate/webhooksHesabınıza ait tüm webhook uç noktalarını listeler.
GET/corporate/webhooks/{id}Tek bir uç noktanın ayrıntılarını döndürür.
PATCH/corporate/webhooks/{id}url, description veya is_active alanlarını günceller (PUT da desteklenir).
DELETE/corporate/webhooks/{id}Uç noktayı siler. 204 No Content döner.
POST/corporate/webhooks/{id}/rotate-secretYeni secret üretir; eski secret 24 saat daha geçerli kalır (kesintisiz geçiş).
POST/corporate/webhooks/{id}/pingAdresinize anında test olayı gönderir ve yanıt durumunu döndürür.
GET/corporate/webhooks/{id}/deliveriesSon 100 teslimat kaydını (durum, deneme sayısı, hata kodu) listeler.

İşe bağlamak için ASR iş oluştururken webhook_id gönderin. Uç nokta HTTPS olmalıdır; özel ağ adresleri reddedilir ve yönlendirmeler (redirect) takip edilmez.

import osimport requests API_KEY = os.environ["KONUSMATIK_API_KEY"]BASE_URL = "https://api.konusmatik.com/api/v1"HEADERS = {"Authorization": f"Bearer {API_KEY}"} # 1. Uç nokta kaydet (yalnızca HTTPS)ep = requests.post(    f"{BASE_URL}/corporate/webhooks",    headers=HEADERS,    json={"url": "https://api.sirketiniz.com/hooks/konusmatik", "description": "Üretim"},).json()print("Webhook ID:", ep["id"])print("Secret:", ep["secret"])  # whsec_... güvenli saklayın # 2. Erişilebilirliği test etprint(requests.post(f"{BASE_URL}/corporate/webhooks/{ep['id']}/ping", headers=HEADERS).json()) # 3. ASR işine bağlarequests.post(    f"{BASE_URL}/corporate/asr/jobs/url",    headers=HEADERS,    json={"audio_url": "https://cdn.example.com/a.mp3", "webhook_id": ep["id"]},) # 4. Teslimat geçmişifor d in requests.get(f"{BASE_URL}/corporate/webhooks/{ep['id']}/deliveries", headers=HEADERS).json():    print(d["event_type"], d["status"], d["attempt_count"]) # 5. Secret rotasyonu (eski secret 24 saat geçerli)new = requests.post(f"{BASE_URL}/corporate/webhooks/{ep['id']}/rotate-secret", headers=HEADERS).json()print(new["secret"], new["secret_previous_expires_at"])

Olay Türleri ve Gövde

Desteklenen olaylar: asr.job.completed ve asr.job.failed. Her istek POST + application/json olarak gelir.

{  "event_id": "evt_3f9a1c...",  "event_type": "asr.job.completed",  "event_version": "1",  "created_at": "2026-11-02T10:15:30Z",  "data": {    "job_id": "8c1f6a52-...",    "status": "completed",    "result_url": "https://api.konusmatik.com/api/v1/corporate/asr/jobs/8c1f6a52-.../result"  }}
Hata KoduAçıklama
INSUFFICIENT_QUOTAKota yetersiz.
AUDIO_DOWNLOAD_FAILEDaudio_url indirilemedi.
SECURITY_VIOLATIONURL güvenlik politikası tarafından engellendi.
TIMEOUT_EXCEEDEDİşlem zaman aşımına uğradı.
INVALID_AUDIO_FORMATDesteklenmeyen ses/video formatı.
ASR_PROCESSING_FAILEDGenel işleme hatası.

İstek Başlıkları ve İmza Doğrulama

İmza, HMAC_SHA256(secret, "{timestamp}." + ham_gövde) değerinin hex karşılığıdır. İmzayı ham gövde üzerinden, sabit zamanlı karşılaştırmayla doğrulayın ve 5 dakikadan eski zaman damgalarını reddedin.

BaşlıkÖrnekAçıklama
X-Konusmatik-Eventasr.job.completedOlay türü.
X-Konusmatik-Event-IDevt_...Benzersiz olay kimliği; tekrar teslimatlarda aynıdır (idempotency için kullanın).
X-Konusmatik-Timestamp1767225600İmza zamanı (Unix saniye).
X-Konusmatik-Signaturev1=<hex>[,v1=<hex>]HMAC-SHA256 imzası. Secret rotasyonu sırasında iki imza birlikte gelir.
import hashlibimport hmacimport time from flask import Flask, request, abort app = Flask(__name__)SECRET = "whsec_..."  # kayıt sırasında aldığınız secretTOLERANCE_SECONDS = 300seen_event_ids = set()  # üretimde kalıcı bir depo kullanın def verify(raw_body: bytes, signature_header: str, timestamp: str) -> bool:    if abs(time.time() - int(timestamp)) > TOLERANCE_SECONDS:        return False  # replay koruması    signed = f"{timestamp}.".encode() + raw_body    expected = hmac.new(SECRET.encode(), signed, hashlib.sha256).hexdigest()    for part in signature_header.split(","):        part = part.strip()        if part.startswith("v1=") and hmac.compare_digest(part[3:], expected):            return True    return False @app.post("/hooks/konusmatik")def konusmatik_hook():    raw = request.get_data()  # JSON parse etmeden önce HAM gövdeyi kullanın    if not verify(raw, request.headers["X-Konusmatik-Signature"], request.headers["X-Konusmatik-Timestamp"]):        abort(401)     event = request.get_json()    if event["event_id"] in seen_event_ids:        return "", 200  # tekrar teslimat    seen_event_ids.add(event["event_id"])     if event["event_type"] == "asr.job.completed":        print("Sonuç hazır:", event["data"]["result_url"])    elif event["event_type"] == "asr.job.failed":        print("Hata:", event["data"]["error"]["code"])    return "", 200  # 2xx dönün, aksi halde yeniden denenir

Yeniden Deneme Politikası

2xx yanıtı başarılı sayılır. 408, 429 ve 5xx yanıtları ile ağ hataları toplam 6 denemeye kadar üstel bekleme ile tekrarlanır; diğer 4xx yanıtlar kalıcı hata sayılır ve tekrar denenmez. Başarısız teslimatlar deliveries kaydında dead_letter durumuna geçer. Yanıtınızı 10 saniye içinde döndürün.

DenemeBekleme
1Anında
2~30 saniye
3~2 dakika
4~10 dakika
5~30 dakika
6~2 saat

Konuşmatik Asenkron TTS

Konuşmatik Asenkron TTS, ses sentezi isteğini kuyruğa alır ve sesin oluşturulmasını beklemeden istemciye bir job_id döner. İşlem arka planda tamamlandıktan sonra durum job_id ile takip edilebilir ve üretilen ses tek bir kayıpsız WAV dosyası olarak indirilebilir. Bu yapı özellikle yüksek hacimli, toplu veya uzun süren ses üretim işleri için uygundur.

POST/corporate/tts/jobs

Toplu TTS sentez işi oluşturur.

GET/corporate/tts/jobs/{id}

İş durumunu sorgular.

GET/corporate/tts/jobs/{id}/stream

Üretilen WAV ses akışını indirir.

İş Oluşturma, Polling ve WAV İndirme

import osimport timeimport requests API_KEY = os.environ["KONUSMATIK_API_KEY"]BASE_URL = "https://api.konusmatik.com/api/v1"HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"} def synthesize_corporate_async(text: str, output_path: str = "output.wav"):    # 1. İşi Oluştur (Anında 201 Created döner)    resp = requests.post(        f"{BASE_URL}/corporate/tts/jobs",        headers=HEADERS,        json={            "text": text,            "voice": "deniz",            "synthesis_options": {"format": "wav", "speed": 1.0}        }    )    resp.raise_for_status()    job_id = resp.json()["id"]    print(f"TTS İşi oluşturuldu. Job ID: {job_id}")     # 2. Polling ile Takip Et    while True:        poll_resp = requests.get(f"{BASE_URL}/corporate/tts/jobs/{job_id}", headers={"Authorization": f"Bearer {API_KEY}"})        poll_resp.raise_for_status()        job_data = poll_resp.json()        status = job_data["status"]         if status == "completed":            print("Ses sentezi tamamlandı!")            break        elif status == "failed":            raise RuntimeError(f"Hata: {job_data.get('error_message')}")         time.sleep(2.0)     # 3. Sesi İndir (Stream veya Signed Download URL)    stream_resp = requests.get(f"{BASE_URL}/corporate/tts/jobs/{job_id}/stream", headers={"Authorization": f"Bearer {API_KEY}"})    stream_resp.raise_for_status()    with open(output_path, "wb") as f:        f.write(stream_resp.content)    print(f"WAV Ses dosyası kaydedildi: {output_path}") if __name__ == "__main__":    synthesize_corporate_async("Kurumsal toplu seslendirme sistemi.")

Konuşmatik Asenkron Realtime ASR

PCM16 ses akışını WebSocket üzerinden gerçek zamanlı gönderin; sunucu tabanlı VAD ile kelime kelime veya tam cümle transkriptlerini anlık alın.

WSS/realtime

wss://api.konusmatik.com/api/v1/realtime

Ses Akışı Standartları

Format & Kodlama
PCM16 Little-Endian
Örnekleme Hızı
24 kHz (veya 16 kHz)
Kanal
1 (Mono)
Aktarım
WebSocket Base64 JSON Chunk
VAD (Ses Algılama)
Sunucu Taraflı Server VAD (Client VAD gerekmez)
YönOlay (Event)Açıklama
Server -> Clientsession.createdBağlantı kabul edilince varsayılan oturum objesi döner.
Client -> Serversession.updateModel (konusmatik-asr-v2), ses formatı ve VAD ayarlarını yapılandırır.
Server -> Clientsession.updatedGüncellenen oturum yapılandırmasını onaylar.
Client -> Serverinput_audio_buffer.appendBase64 PCM16 ses parçasını gönderir.
Server -> Clientconversation.item.input_audio_transcription.deltaCanlı transkripsiyon parçasını (kelime/hece) döner.
Server -> Clientconversation.item.input_audio_transcription.completedServer VAD sessizlik tespit ettiğinde nihai cümleyi döner.
Server -> ClienterrorKapasite aşımı, yetki veya biçim hatalarını bildirir.

Canlı Akış Python & cURL Örneği

import asyncioimport base64import jsonimport osimport sysimport sounddevice as sdimport websockets API_KEY = os.environ.get("KONUSMATIK_API_KEY")if not API_KEY:    print("HATA: 'KONUSMATIK_API_KEY' ortam değişkeni bulunamadı.")    print("PowerShell'de ayarlamak için: $env:KONUSMATIK_API_KEY = 'API_ANAHTARINIZ'")    sys.exit(1) WS_URL = "wss://api.konusmatik.com/api/v1/realtime"SAMPLE_RATE = 24000  # Konuşmatik Realtime PCM16 varsayılan örnekleme hızı (24 kHz)CHANNELS = 1          # MonoBLOCK_SIZE = 2400     # Her 100ms için 2400 örnek (4800 byte) async def main():    headers = {"Authorization": f"Bearer {API_KEY}"}    audio_queue = asyncio.Queue()    loop = asyncio.get_running_loop()     # Mikrofon geri çağırma fonksiyonu (ayrı ses thread'inden çalışır)    def audio_callback(indata, frames, time_info, status):        if status:            print(f"[Ses Uyarısı]: {status}", file=sys.stderr)        loop.call_soon_threadsafe(audio_queue.put_nowait, bytes(indata))     print("Konuşmatik Realtime API'ye bağlanılıyor...")    async with websockets.connect(WS_URL, additional_headers=headers) as ws:        # 1. Oturum Yapılandırması        await ws.send(json.dumps({            "type": "session.update",            "session": {                "model": "konusmatik-asr-v2",                "input_audio_format": "pcm16",                "language": "tr",                "turn_detection": {"type": "server_vad"}            }        }))         # 2. Mikrofondan Ses Gönderme Görevi        async def send_audio():            try:                while True:                    data = await audio_queue.get()                    audio_b64 = base64.b64encode(data).decode("ascii")                    await ws.send(json.dumps({                        "type": "input_audio_buffer.append",                        "audio": audio_b64                    }))            except asyncio.CancelledError:                pass         # 3. Sunucudan Gelen Yanıtları Dinleme Görevi        async def receive_events():            try:                async for message in ws:                    event = json.loads(message)                    event_type = event.get("type", "")                     if event_type == "session.updated":                        print("Mikrofon aktif! Konuşmaya başlayabilirsiniz (Çıkmak için Ctrl+C)...")                        print("------------------------------------------------------------------")                    elif event_type == "conversation.item.input_audio_transcription.delta":                        print(event.get("delta", ""), end="", flush=True)                    elif event_type == "conversation.item.input_audio_transcription.completed":                        transcript = event.get("transcript", "")                        print(f"\n[Nihai Cümle]: {transcript}\n")                    elif event_type == "error":                        print(f"\n[Sunucu Hatası]: {event.get('error', event)}")            except asyncio.CancelledError:                pass         # Mikrofon akışını başlat (sounddevice)        stream = sd.RawInputStream(            samplerate=SAMPLE_RATE,            channels=CHANNELS,            dtype="int16",            blocksize=BLOCK_SIZE,            callback=audio_callback        )         with stream:            send_task = asyncio.create_task(send_audio())            receive_task = asyncio.create_task(receive_events())            try:                # İki görevi aynı anda çalıştır                await asyncio.gather(send_task, receive_task)            except asyncio.CancelledError:                pass            finally:                send_task.cancel()                receive_task.cancel() if __name__ == "__main__":    try:        asyncio.run(main())    except KeyboardInterrupt:        print("\n\nProgram kullanıcı tarafından durduruldu.")

Kapasite, Eşzamanlılık ve Hız Sınırları

Konuşmatik altyapısı üç bağımsız koruma katmanıyla donanım kararlılığını garanti altına alır.

01

Rate Limit (İstek Hızı)

Belirli bir zaman aralığında (60s) gönderilebilecek maksimum HTTP istek sayısıdır.

02

Outstanding (Açık İşler)

Henüz tamamlanmamış (pending + processing) kuyrukta bekleyen toplam iş tavanıdır.

03

Active GPU (Aktif İnference)

Donanım/GPU üzerinde aynı anda çalışan gerçek yapay zeka çıkarım limitidir (ASR: 14, TTS: 32).

Paket / Katmanİş YüküHesap Başına Açık İşAktif GPU İnferenceİstek Limiti
StandartTTS (Ses Sentezi)32 açık iş32 eşzamanlı inference120 istek / dk
StandartASR (Deşifre)20 açık iş14 eşzamanlı inference60 istek / dk
KurumsalTTS (Ses Sentezi)128 açık iş / hesap (Global: 256)32 eşzamanlı inference300 istek / dk
KurumsalASR (Deşifre)100 açık iş / hesap (Global: 200)14 eşzamanlı inference120 istek / dk
Realtime CanlıRealtime ASR-50 eşzamanlı canlı oturum60 istek / dk

HTTP 429 & Hata Yönetimi

Kapasite dolduğunda deterministik HTTP 429 Too Many Requests ve Retry-After başlığı döner.

Retry-After Başlığı ile Yeniden Deneme

Kapasite aşımlarında (asr_capacity_saturated, tts_capacity_saturated) sunucunun belirttiği saniye kadar bekleyerek yeniden deneyin:

import timeimport requests def request_with_retry_after(url, headers, payload, max_retries=3):    for attempt in range(max_retries):        response = requests.post(url, headers=headers, json=payload)                if response.status_code == 429:            # Backend'den dönen Retry-After başlığına uyun (Varsayılan 3 saniye)            retry_after = int(response.headers.get("Retry-After", 3))            print(f"Kapasite dolu (429). {retry_after}s sonra tekrar deneniyor... (Deneme {attempt+1}/{max_retries})")            time.sleep(retry_after)            continue                    return response    raise RuntimeError("Maksimum yeniden deneme sınırına ulaşıldı.")
HTTP DurumuHata Türü / KoduAçıklama
400 Bad Requestinvalid_request_errorGeçersiz model, ses adı, parametre veya desteklenmeyen format (WAV dışında format talebi).
401 Unauthorizedauthentication_errorAPI anahtarı eksik, geçersiz veya iptal edilmiş.
402 Payment Requiredinsufficient_corporate_quotaHesap paketindeki kredi veya saniye kotası tükendi.
404 Not Foundresource_not_foundBelirtilen job_id bulunamadı veya başka bir müşteriye ait.
413 Payload Too Largeinvalid_request_error100 MB ses yükleme veya 10.000 karakter metin sınırı aşıldı.
422 Unprocessable Entityvalidation_errorEksik veya hatalı form / JSON alanları.
429 Too Many Requestscapacity_error / rate_limit_errorKapasite doldu veya hız sınırı aşıldı. Retry-After başlığı içerir (asr_capacity_saturated, tts_capacity_saturated).
500 / 503server_errorGeçici sunucu veya kuyruk servis kesintisi.

Konuşmatik API ile geliştirmeye başlayın.

Profilinizden API anahtarınızı oluşturun; TTS, ASR ve Realtime servislerini uygulamanıza entegre edin.