OpenQCoreAI
Inizia

Risorse · API vocale

Documentazione API vocale

Riferimento pronto per la produzione per l'esecuzione vocale in tempo reale, eventi in streaming, flusso di interruzione, intestazioni e semantica degli errori.

Torna alla documentazioneVai agli endpoint

Endpoint

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

Intestazioni richieste

  • Authorization: Bearer [token] o autenticazione con API key
  • Content-Type: application/json
  • X-Scope-Type: personale | workspace
  • X-Workspace-ID: richiesto quando lo scope è workspace

Corpo della richiesta

{
  "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"
  }
}

Corpo della risposta

{
  "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
  }
}

Eventi in streaming

  • session.started — sessione vocale inizializzata
  • stt.partial — frammento di trascrizione parziale
  • llm.delta — token di testo incrementali del modello
  • tts.chunk — blocco audio prodotto
  • session.completed — risposta finale + utilizzo

Flusso di interruzione

L'interrupt interrompe la generazione vocale in corso per una sessione specifica e rilascia in modo sicuro il percorso di esecuzione attivo.

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

{
  "reason": "user_barge_in"
}

Formati audio

  • Input consigliato: WAV (PCM16, mono, 16kHz).
  • Gli input non WAV possono essere convertiti prima dello STT.
  • Il formato di output dipende dal provider e dalle impostazioni di runtime.
  • Payload di grandi dimensioni possono restituire 413.

Intestazioni dei metadati

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

Modelli di errore

400

Payload della richiesta non valido o campi mancanti.

401

Autenticazione mancante o non valida.

403

Ambito/permesso non consentito.

409

Sessione già in elaborazione (conflitto di blocco).

413

Payload audio troppo grande.

415

Tipo di media/contenuto non supportato.

422

Errore di validazione nel corpo o nelle intestazioni.

429

Limite di richieste superato.

503

Provider non disponibile o sistema sovraccarico.

Esempi

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
  }'