OpenQCoreAI
Başlayın

Kaynaklar · Ses API

Ses API Dokümantasyonu

Gerçek zamanlı ses yürütme, akış olayları, kesme akışı, başlıklar ve hata semantiği için üretim sınıfı referans.

Belgelere DönUç Noktalara Atla

Uç Noktalar

POST /api/v1/voice/chat/meta
POST /api/v1/voice/chat
POST /api/v1/voice/interrupt/{session_id}
WS /api/v1/voice/ws

Gerekli Başlıklar

  • Authorization: Bearer [token] or API key auth
  • Content-Type: application/json
  • X-Scope-Type: personal | workspace
  • X-Workspace-ID: required when scope is workspace

İstek Gövdesi

{
  "message": "Book a follow-up call tomorrow",
  "session_id": "sess_123",
  "stream": true,
  "voice": {
    "input_format": "wav",
    "output_format": "wav",
    "sample_rate": 16000
  },
  "metadata": {
    "lang": "en",
    "client": "web"
  }
}

Yanıt Gövdesi

{
  "success": true,
  "session_id": "sess_123",
  "content": "Sure — I scheduled a follow-up for tomorrow.",
  "provider": "openai",
  "usage": {
    "input_tokens": 210,
    "output_tokens": 96
  },
  "metadata": {
    "latency_ms": 842
  }
}

Akış Olayları

  • session.started — ses oturumu başlatıldı
  • stt.partial — kısmi transkripsiyon parçası
  • llm.delta — artımlı model metin tokenları
  • tts.chunk — üretilen ses parçası
  • session.completed — nihai yanıt + kullanım

Akışı Durdur

Interrupt, belirli bir oturum için devam eden ses üretimini sonlandırır ve aktif yürütme yolunu güvenli şekilde serbest bırakır.

POST /api/v1/voice/interrupt/{session_id}

{
  "reason": "user_barge_in"
}

Ses Formatları

  • Önerilen giriş: WAV (PCM16, mono, 16kHz).
  • WAV dışı girişler STT'den önce dönüştürülebilir.
  • Çıkış formatı sağlayıcıya ve çalışma zamanı ayarlarına bağlıdır.
  • Büyük yüklerde 413 dönebilir.

Meta Veri Başlıkları

X-Trace-IDX-Session-IDX-STT-Time-MSX-LLM-Time-MSX-TTS-Time-MS

Hata Modelleri

400

Geçersiz istek gövdesi veya eksik alanlar.

401

Eksik veya geçersiz kimlik doğrulama.

403

Kapsam/izin yetkisi reddedildi.

409

Oturum zaten işleniyor (kilit çakışması).

413

Ses yükü çok büyük.

415

Medya/içerik türü desteklenmiyor.

422

İstek gövdesi veya başlıklarda doğrulama hatası.

429

İstek limiti aşıldı.

503

Sağlayıcı kullanılamıyor veya sistem aşırı yüklü.

Örnekler

curl -X POST "/api/v1/voice/chat" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "X-Scope-Type: personal" \
  -d '{
    "message":"Summarize this call",
    "session_id":"sess_123",
    "stream":false
  }'