API compatible con OpenAI
Endpoints /v1, chat completions, encabezados, códigos de error, streaming y caché.
El gateway expone endpoints compatibles con OpenAI bajo la URL base /v1. Los clientes OpenAI pueden usar el gateway en lugar del proveedor.
Endpoints#
| Método y ruta | Propósito |
|---|---|
| POST /v1/chat/completions | Chat completions estilo OpenAI, nativo o por facade hacia backends Anthropic. |
| POST /v1/responses | Relay Responses API para SDK recientes; se adapta a chat y usa el mismo pipeline. |
| POST /v1/embeddings | Embeddings estilo OpenAI, enrutados al proveedor configurado. |
| GET /v1/models | Lista modelos registrados. |
Se aceptan alias de rutas habituales para conectar SDK y herramientas existentes sin cambios.
Endpoint Gateway: imágenes, audio, archivos, fine-tuning y lotes#
Además de chat, messages y embeddings, se pueden habilitar otras interfaces compatibles con OpenAI. Están deshabilitadas por defecto; una ruta deshabilitada devuelve 404 endpoint_disabled. Configure Settings -> Endpoint Gateway:
| Superficie | Control | Comportamiento |
|---|---|---|
| /v1/images/generations, edits, variations | images | Inspecciona, enmascara y comprime prompt JSON como chat; inspecciona metadatos y usa caché de generation sujeta a inspección. |
| /v1/audio/speech | audio | Inspecciona entrada como prompt de chat y reenvía. |
| /v1/audio/transcriptions, translations | passthrough | Relay multipart gobernado, con inyección de key y auditoría. |
| /v1/files | files | Decodifica e inspecciona archivos de texto; bloquea cargas con infracciones y deja pasar binarios. |
| /v1/fine_tuning/jobs, /v1/batches | passthrough | Relay gobernado con inyección de key y auditoría. |
No se analizan píxeles ni ondas de audio; solo texto asociado. El registro de transacciones indica el tipo de endpoint.
Encabezados#
| Encabezado | Propósito |
|---|---|
| Authorization: Bearer [key] | Autenticación del cliente y/o clave upstream según los modos configurados. |
| X-Agent-ID | Identidad del agente para seguimiento, enrutamiento, riesgo y ámbito de caché. |
| X-User-Id | Identidad del usuario; se prefieren claims sub del token autenticado. |
| x-aifw-cache-refresh | Omite la consulta a caché, pero permite escribir. |
Solicitud estándar#
POST /v1/chat/completions
{
"model": "gpt-4o",
"messages": [
{ "role": "system", "content": "You are a helpful assistant." },
{ "role": "user", "content": "Hello!" }
],
"stream": false
}| Campo | Notas |
|---|---|
| model | Opcional; si se omite, usa el modelo predeterminado configurado. |
| messages | Mensajes estándar; tool_calls/tool pasan sin cambios de bytes. |
| stream | true aplica el modo efectivo buffered o live. |
Códigos de error#
Las solicitudes bloqueadas o rechazadas devuelven HTTP 400 con error estructurado:
{
"error": {
"message": "The transaction was intercepted and blocked by corporate AI security policy.",
"type": "guardrail_violation",
"code": "prompt_injection_detected",
"details": { "policy_id": "BUILTIN-JAILBREAK", "timestamp": "2025-01-15T10:00:00Z" }
}
}| Código | Significado |
|---|---|
| guardrail_violation | Bloqueo por regla integrada o personalizada; detalles incluyen ID de política. |
| prompt_injection_detected | Coincide regla de jailbreak o inyección. |
| semantic_rule_violation:rule | Score semántico supera umbral de bloqueo. |
| model_disabled | Modelo registrado pero deshabilitado. |
| model_not_registered | Modo estricto activo y modelo no registrado. |
| backend_not_configured | No hay URL de backend para el modelo resuelto. |
| default_policy_block | Ninguna regla coincide y acción predeterminada es block. |
Respuestas bloqueadas incluyen X-Gateway-Security: Violated. Fallos de autenticación devuelven 401; rutas desconocidas, 404.
Streaming#
Con stream: true, respuestas usan server-sent events y terminan con data: [DONE].
- buffered (predeterminado): analiza la respuesta completa antes de entregar tokens; infracción devuelve 400 antes de la entrega.
- stream: transmite tokens en vivo; una infracción termina SSE con guardrail_violation. Los tokens ya entregados no pueden retirarse.
Caché#
Con un ámbito configurado, las respuestas pueden servirse desde completion cache. Los hits se registran y el body vuelve a pasar por inspección.