Referencia de la API
Autenticación, endpoints, errores y ejemplos para integrar AI Gateway.
En esta página
Utiliza esta referencia para elegir un endpoint y conocer la autenticación, los errores y la correlación de solicitudes. La especificación OpenAPI contiene los esquemas exactos y se puede importar en Bruno, Postman o Insomnia.
Los ejemplos utilizan GATEWAY para el origen (por ejemplo, http://localhost:4000) y API_KEY para una virtual key. El campo model siempre nombra un public model configurado en AI Gateway.
Autenticación
- Inferencia (
/v1/*): master key o virtual key medianteAuthorization: Bearer <key>o el headerx-api-key. No se aceptan credenciales en los query parameters, porque las URL pueden aparecer en logs, historiales y referencias./v1/modelsy/v1/models/{model}son las únicas excepciones sin autenticación; consulta Consultar modelos. - Admin (
/admin/*): utiliza la master key para la automatización API. Cuando la autenticación del panel está habilitada, las sesiones del operador también pueden acceder a las rutas permitidas por su rol.
Modelo completo: Seguridad.
Formato de los errores
La mayoría de los errores utilizan el formato compatible con OpenAI. /v1/messages usa la forma de Anthropic y /v1/rerank usa la forma { "error": { "code": <status>, "message": "..." } } de OpenRouter:
{ "error": { "message": "...", "type": "invalid_request_error", "param": "model", "code": "model_not_found" } }Los errores de validación del gateway incluyen la ruta del campo y el motivo del rechazo. Los errores estructurados del proveedor conservan los campos útiles message, param y code, con límites de longitud y ocultando las credenciales y el modelo upstream configurado. El cuerpo original del proveedor nunca se copia en la respuesta. Los fallos operativos (autenticación, permisos, deployments ausentes y rate limits) y las respuestas 5xx usan mensajes estables del gateway para evitar exponer el routing interno. Consulta Solución de problemas para relacionar clases de error, estados HTTP y códigos.
Correlación de solicitudes
Cada respuesta incluye x-request-id; si envías uno, AI Gateway lo conserva. Inclúyelo al informar de un problema. Consulta Headers para conocer el header y Observabilidad para buscar la solicitud en los logs.
Importar en Bruno
En Bruno, selecciona Import Collection → OpenAPI V3 e importa apps/api/openapi.yaml. Configura la variable del servidor baseUrl (por ejemplo, http://localhost:4000) y el Bearer token en la sección de autenticación.
Pasos para habilitar un modelo
POST /admin/deployments: crea un deployment conpublicModel,adapterKey,upstreamModely las credenciales en el cuerpo.POST /admin/keys: crea una virtual key conallowedModels.- Llama a un endpoint de inferencia con el nombre del public model en
model.
POST /admin/deployments/resolve valida el perfil/operaciones/transports sin guardar; consulta Tu primer deployment.
Endpoints disponibles
| endpoint | Contrato | Página |
|---|---|---|
POST /v1/chat/completions | OpenAI Chat Completions | Chat completions |
POST /v1/responses, WS /v1/responses, GET/DELETE /v1/responses/:id, GET /v1/responses/:id/input_items | OpenAI Responses | Responses |
POST /v1/messages | Anthropic Messages | Messages |
POST /v1/images/generations, POST /v1/images/edits | Imágenes de OpenAI | Imágenes |
POST/GET/DELETE /v1/videos, GET /v1/videos/:id/content | Vídeos con formato de OpenAI | Videos |
POST /v1/embeddings | OpenAI Embeddings | Embeddings |
POST /v1/rerank | OpenRouter Reranking | Reranking |
POST /v1/audio/transcriptions | OpenAI Audio | Transcripción de audio |
GET /v1/realtime?model= (WebSocket) | OpenAI Realtime, conversación | Conversaciones en tiempo real |
GET /v1/realtime?intent=transcription (WebSocket) | OpenAI Realtime, transcripción | Transcripción en tiempo real |
POST /v1/realtime/client_secrets | Client secrets de OpenAI Realtime | Conversaciones en tiempo real |
GET /v1/models, GET /v1/models/{model}, GET /v1/models/{model}/deployments | Descubrimiento de modelos | Consultar modelos |
Próximos pasos
- Streaming: formato SSE compartido por los endpoints que admiten streaming.
- Headers: cada header de solicitud/respuesta en una tabla.
- Solución de problemas: clases de error, códigos de estado y síntomas comunes.