# Referencia de la API

> Autenticación, endpoints, errores y ejemplos para integrar AI Gateway.

URL: https://boelabs.com/docs/ai-gateway/api-overview
Language: Español

Utiliza esta referencia para elegir un endpoint y conocer la autenticación, los errores y la correlación de solicitudes. La [especificación OpenAPI](https://github.com/boelabs/ai-gateway/blob/main/apps/api/openapi.yaml) 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 [#authentication]

- **Inferencia** (`/v1/*`): master key o virtual key mediante `Authorization: Bearer <key>` o el header `x-api-key`. No se aceptan credenciales en los query parameters, porque las URL pueden aparecer en logs, historiales y referencias. `/v1/models` y `/v1/models/{model}` son las únicas excepciones sin autenticación; consulta [Consultar modelos](https://boelabs.com/docs/ai-gateway/models-discovery).
- **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](https://boelabs.com/docs/ai-gateway/security).

## Formato de los errores [#error-shape]

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:

```json
{ "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](https://boelabs.com/docs/ai-gateway/troubleshooting) para relacionar clases de error, estados HTTP y códigos.

## Correlación de solicitudes [#request-correlation]

Cada respuesta incluye `x-request-id`; si envías uno, AI Gateway lo conserva. **Inclúyelo al informar de un problema.** Consulta [Headers](https://boelabs.com/docs/ai-gateway/headers) para conocer el header y [Observabilidad](https://boelabs.com/docs/ai-gateway/observability) para buscar la solicitud en los logs.

## Importar en Bruno [#importing-into-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 [#typical-flow-to-serve-a-model]

1. `POST /admin/deployments`: crea un deployment con `publicModel`, `adapterKey`, `upstreamModel` y las credenciales en el cuerpo.
2. `POST /admin/keys`: crea una virtual key con `allowedModels`.
3. 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](https://boelabs.com/docs/ai-gateway/first-deployment).

## Endpoints disponibles [#the-endpoints]

| endpoint | Contrato | Página |
|---|---|---|
| `POST /v1/chat/completions` | OpenAI Chat Completions | [Chat completions](https://boelabs.com/docs/ai-gateway/chat-completions) |
| `POST /v1/responses`, `WS /v1/responses`, `GET/DELETE /v1/responses/:id`, `GET /v1/responses/:id/input_items` | OpenAI Responses | [Responses](https://boelabs.com/docs/ai-gateway/responses) |
| `POST /v1/messages` | Anthropic Messages | [Messages](https://boelabs.com/docs/ai-gateway/messages) |
| `POST /v1/images/generations`, `POST /v1/images/edits` | Imágenes de OpenAI | [Imágenes](https://boelabs.com/docs/ai-gateway/images) |
| `POST/GET/DELETE /v1/videos`, `GET /v1/videos/:id/content` | Vídeos con formato de OpenAI | [Videos](https://boelabs.com/docs/ai-gateway/videos) |
| `POST /v1/embeddings` | OpenAI Embeddings | [Embeddings](https://boelabs.com/docs/ai-gateway/embeddings) |
| `POST /v1/rerank` | OpenRouter Reranking | [Reranking](https://boelabs.com/docs/ai-gateway/reranking) |
| `POST /v1/audio/transcriptions` | OpenAI Audio | [Transcripción de audio](https://boelabs.com/docs/ai-gateway/audio-transcriptions) |
| `GET /v1/realtime?model=` (WebSocket) | OpenAI Realtime, conversación | [Conversaciones en tiempo real](https://boelabs.com/docs/ai-gateway/realtime-conversations) |
| `GET /v1/realtime?intent=transcription` (WebSocket) | OpenAI Realtime, transcripción | [Transcripción en tiempo real](https://boelabs.com/docs/ai-gateway/realtime-transcription) |
| `POST /v1/realtime/client_secrets` | Client secrets de OpenAI Realtime | [Conversaciones en tiempo real](https://boelabs.com/docs/ai-gateway/realtime-conversations#client-secrets) |
| `GET /v1/models`, `GET /v1/models/{model}`, `GET /v1/models/{model}/deployments` | Descubrimiento de modelos | [Consultar modelos](https://boelabs.com/docs/ai-gateway/models-discovery) |

## Próximos pasos [#next-steps]

- [Streaming](https://boelabs.com/docs/ai-gateway/streaming): formato SSE compartido por los endpoints que admiten streaming.
- [Headers](https://boelabs.com/docs/ai-gateway/headers): cada header de solicitud/respuesta en una tabla.
- [Solución de problemas](https://boelabs.com/docs/ai-gateway/troubleshooting): clases de error, códigos de estado y síntomas comunes.