OpenQCoreAI
Commencer

Ressources · API vocale

Documentation de l'API vocale

Référence de niveau production pour l'exécution vocale en temps réel, les événements en streaming, le flux d'interruption, les en-têtes et la sémantique des erreurs.

Retour à la documentationAller aux points de terminaison

Points de terminaison

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

En-têtes requis

  • Authorization: Bearer [token] ou authentification par clé API
  • Content-Type: application/json
  • X-Scope-Type: personal | workspace
  • X-Workspace-ID: requis lorsque la portée est workspace

Corps de la requête

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

Corps de la réponse

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

Événements en streaming

  • session.started — session vocale initialisée
  • stt.partial — fragment de transcription partiel
  • llm.delta — jetons textuels incrémentaux du modèle
  • tts.chunk — fragment audio produit
  • session.completed — réponse finale + utilisation

Flux d'interruption

Interruption arrête la génération vocale en cours pour une session spécifique et libère en toute sécurité le chemin d'exécution actif.

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

{
  "reason": "user_barge_in"
}

Formats audio

  • Entrée recommandée : WAV (PCM16, mono, 16 kHz).
  • Les entrées non WAV peuvent être converties avant la STT.
  • Le format de sortie dépend du fournisseur et des paramètres d'exécution.
  • Les charges utiles volumineuses peuvent renvoyer 413.

En-têtes de métadonnées

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

Modèles d'erreurs

400

Charge utile de la requête invalide ou champs manquants.

401

Authentification manquante ou invalide.

403

Portée/permission non autorisées.

409

Session déjà en cours de traitement (conflit de verrou).

413

Charge audio trop volumineuse.

415

Type de média/contenu non pris en charge.

422

Échec de validation dans le corps ou les en-têtes.

429

Limite de requêtes dépassée.

503

Fournisseur indisponible ou surcharge du système.

Exemples

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