OpenQCoreAI
Começar

Recursos · API de Voz

Documentação da API de Voz

Referência de nível de produção para execução de voz em tempo real, eventos em streaming, fluxo de interrupção, cabeçalhos e semântica de erros.

Voltar à documentaçãoIr para os endpoints

Endpoints

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

Cabeçalhos obrigatórios

  • Authorization: Bearer [token] ou autenticação por chave de API
  • Content-Type: application/json
  • X-Scope-Type: personal | workspace
  • X-Workspace-ID: obrigatório quando o escopo for workspace

Corpo da Requisição

{
  "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 da Resposta

{
  "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 de streaming

  • session.started — sessão de voz inicializada
  • stt.partial — trecho de transcrição parcial
  • llm.delta — tokens de texto incrementais do modelo
  • tts.chunk — trecho de áudio produzido
  • session.completed — resposta final e uso

Fluxo de Interrupção

Interrupt interrompe a geração de voz em andamento para uma sessão específica e libera com segurança o caminho de execução ativo.

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

{
  "reason": "user_barge_in"
}

Formatos de Áudio

  • Entrada recomendada: WAV (PCM16, mono, 16kHz).
  • Arquivos não WAV podem ser convertidos antes do STT.
  • O formato de saída depende do provedor e das configurações de runtime.
  • Requisições com payloads muito grandes podem retornar 413.

Cabeçalhos de Metadados

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

Modelos de Erro

400

Corpo da requisição inválido ou campos ausentes.

401

Autenticação ausente ou inválida.

403

Escopo/permissão não autorizados.

409

Sessão já em processamento (conflito de bloqueio).

413

Carga útil de áudio muito grande.

415

Tipo de mídia/conteúdo não suportado.

422

Falha de validação no corpo ou nos cabeçalhos.

429

Limite de requisições excedido.

503

Provedor indisponível ou sistema sobrecarregado.

Exemplos

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