OpenQCoreAI
Comenzar

Recursos · API de voz

Documentación de la API de voz

Referencia de nivel de producción para ejecución de voz en tiempo real, eventos en streaming, flujo de interrupciones, encabezados y semántica de errores.

Volver a la documentaciónIr a endpoints

Puntos finales

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

Encabezados requeridos

  • Authorization: Bearer [token] o autenticación con clave de API
  • Content-Type: application/json
  • X-Scope-Type: personal | espacio de trabajo
  • X-Workspace-ID: requerido cuando el ámbito es espacio de trabajo

Cuerpo de la solicitud

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

Cuerpo de la respuesta

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

Eventos en streaming

  • session.started — sesión de voz inicializada
  • stt.partial — fragmento de transcripción parcial
  • llm.delta — tokens de texto incrementales del modelo
  • tts.chunk — fragmento de audio producido
  • session.completed — respuesta final + uso

Flujo de interrupciones

Interrupt detiene la generación de voz en curso para una sesión específica y libera de forma segura la ruta de ejecución activa.

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

{
  "reason": "user_barge_in"
}

Formatos de audio

  • Entrada recomendada: WAV (PCM16, mono, 16 kHz).
  • Las entradas no WAV pueden convertirse antes de STT.
  • El formato de salida depende del proveedor y de la configuración de ejecución.
  • Las cargas útiles grandes pueden devolver 413.

Encabezados de metadatos

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

Modelos de error

400

Carga de solicitud inválida o campos faltantes.

401

Autenticación faltante o inválida.

403

Ámbito/permiso no permitido.

409

Sesión ya en procesamiento (conflicto de bloqueo).

413

Carga de audio demasiado grande.

415

Tipo de medio/contenido no compatible.

422

Fallo de validación en el cuerpo o los encabezados.

429

Límite de solicitudes excedido.

503

Proveedor no disponible o sobrecarga del sistema.

Ejemplos

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