Recursos · Chat API

Documentación de la API de Chat

Referencia de nivel empresarial para /chat/completions que incluye el esquema de solicitud, eventos de streaming, comportamiento en tiempo de ejecución y semántica de errores.

Volver a la documentación Ir a los endpoints

Puntos finales

GET /api/v1/chat/health

POST /api/v1/chat/completions

Encabezados requeridos

Authorization: Bearer [token] o autenticación mediante clave APIContent-Type: application/jsonX-Scope-Type: personal | espacio de trabajoX-Workspace-ID: requerido solo cuando el alcance es espacio de trabajo

Cuerpo de la solicitud

json

{
  "message": "Summarize the last meeting in bullet points",
  "session_id": "sess_123",
  "stream": true,
  "attachments": [],
  "metadata": {
    "locale": "en",
    "channel": "web"
  }
}

Cuerpo de la respuesta

json

{
  "success": true,
  "session_id": "sess_123",
  "content": "• Discussed roadmap\n• Confirmed release scope\n• Assigned owners",
  "provider": "pulse",
  "usage": {
    "input_tokens": 324,
    "output_tokens": 118
  },
  "metadata": {
    "latency_ms": 612
  }
}

Eventos de streaming

response.started — ejecución del chat iniciada
response.delta — tokens de texto incrementales
response.tool_call — evento de invocación de herramienta (si corresponde)
response.usage — actualización de uso/tokens
response.completed — respuesta final ensamblada

Comportamientos en tiempo de ejecución

El control de contrapresión rechaza la sobrecarga con 503.
El bloqueo distribuido evita el procesamiento duplicado en curso.
La caché de deduplicación atiende solicitudes no streaming repetidas.
La persistencia de sesión almacena los turnos del usuario y del asistente.
La validación protege el cuerpo de la solicitud, los adjuntos y el contexto de acceso.

Modelos de error

400

Carga útil de la solicitud inválida o faltan campos obligatorios.

401

Autenticación faltante o inválida.

403

Restricción de alcance/permiso.

409

Conflicto de bloqueo: la solicitud ya se está procesando.

422

Error de validación en encabezados/cuerpo/contexto.

429

Se excedió el límite de solicitudes.

503

Sobrecarga del sistema o indisponibilidad aguas arriba.

Ejemplos

bash

curl -X POST "/api/v1/chat/completions" \
  -H "Authorization: Bearer [token]" \
  -H "Content-Type: application/json" \
  -H "X-Scope-Type: personal" \
  -d '{
    "message":"Write a short product update",
    "session_id":"sess_123",
    "stream":false
  }'