# Inicio rápido

> Ejecuta un gateway local, conecta un proveedor y realiza tu primera solicitud.

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

Esta guía te permite ejecutar un gateway local, conectar un deployment de OpenAI llamado `general` y crear una virtual key para tu aplicación. Si ya tienes un gateway en funcionamiento, comienza con [Tu primer deployment](https://boelabs.com/docs/ai-gateway/first-deployment).

## Antes de empezar [#before-you-start]

Instala Bun 1.4+ y Docker Compose. Necesitas una API key de OpenAI con acceso al modelo del ejemplo. Los comandos de Compose ejecutan Postgres 18 y Redis 8 en tu equipo.

<Callout type="warn" title="Mantén privadas las credenciales del operador">

La **master key** permite administrar AI Gateway. La **API key del proveedor** autentica al gateway ante ese proveedor. Tu aplicación recibe una **virtual key** distinta; no le entregues ninguna de las credenciales del operador.

</Callout>

<Steps>
<Step>

## Ejecutar el gateway [#run-the-gateway]

```bash
git clone https://github.com/boelabs/ai-gateway.git && cd ai-gateway
bun install
docker compose -f docker/compose.yaml -f docker/compose.local.yaml up -d postgres redis
```

Crea `apps/api/.env` a partir de `apps/api/.env.example` e incluye estos valores:

```bash
PORT=4000
NODE_ENV=development
MASTER_KEY=replace-with-at-least-32-random-characters
ENCRYPTION_KEYRING={"primary":"64_hex_chars_32_bytes"}   # value: openssl rand -hex 32
ACTIVE_ENCRYPTION_KEY_ID=primary
DATABASE_URL=postgres://gateway:gateway@localhost:5432/ai_gateway
REDIS_URL=redis://localhost:6379
```

Aplica las migraciones e inicia el gateway:

```bash
bun run --filter @boelabs/ai-gateway-api db:migrate
bun run --filter @boelabs/ai-gateway-api dev
```

Confirma que está activo:

```bash
curl http://localhost:4000/health/ready   # 200 once Postgres + Redis + extensions are healthy
```

Para el resto de esta página:

```bash
export BASE=http://localhost:4000
export MASTER_KEY=replace-with-at-least-32-random-characters
```

</Step>
<Step>

## Registrar un deployment [#register-a-deployment]

Un **deployment** conecta un public model con un adapter, un modelo upstream y sus credenciales. Créalo con la master key. La API key del proveedor se envía en el cuerpo y se almacena cifrada:

```bash
curl -X POST $BASE/admin/deployments \
  -H "Authorization: Bearer $MASTER_KEY" -H "content-type: application/json" -d '{
    "publicModel": "general",
    "adapterKey": "openai",
    "upstreamModel": "gpt-5.5",
    "credentials": { "apiKey": "sk-..." }
  }'
```

`general` ya es un public model. Para inspeccionar las operaciones y los transports **antes de guardar**, utiliza el mismo cuerpo en `POST /admin/deployments/resolve`.

</Step>
<Step>

## Crear una virtual key [#issue-a-virtual-key]

Crea una virtual key para la aplicación. `allowedModels` limita los public models permitidos (`[]` o un valor omitido permite todos):

```bash
curl -X POST $BASE/admin/keys \
  -H "Authorization: Bearer $MASTER_KEY" -H "content-type: application/json" -d '{
    "name": "my-app",
    "allowedModels": ["general"]
  }'
```

La respuesta incluye el secreto. Guárdalo antes de continuar; podrás volver a copiarlo desde la API de administración o el dashboard, salvo que crees la clave con `"private": true`:

```json
{ "data": { "id": "…", "keyPrefix": "sk-abcdefg", "key": "sk-…", "allowedModels": ["general"] } }
```

Consulta [Virtual keys](https://boelabs.com/docs/ai-gateway/virtual-keys) para configurar presupuestos, límites de RPM/TPM y rotación.

</Step>
<Step>

## Realizar una solicitud [#make-a-call]

Utiliza el nombre público en `model` y la virtual key obtenida en el paso anterior.

<Tabs items={["curl", "Python"]}>
<Tab value="curl">

```bash
curl -X POST $BASE/v1/chat/completions \
  -H "Authorization: Bearer sk-..." -H "content-type: application/json" -d '{
    "model": "general",
    "messages": [{ "role": "user", "content": "Say hello in one word." }]
  }'
```

</Tab>
<Tab value="Python">

Instala el SDK con `pip install openai`.

```python
from openai import OpenAI

client = OpenAI(base_url="http://localhost:4000/v1", api_key="sk-...")
resp = client.chat.completions.create(
    model="general",
    messages=[{"role": "user", "content": "Say hello in one word."}],
)
print(resp.choices[0].message.content)
```

</Tab>
</Tabs>

Una respuesta correcta contiene el mensaje del asistente en `choices[0].message.content`. Si falla, comprueba el nombre del modelo, los permisos de la virtual key y las credenciales del proveedor.

La misma key y URL base sirven para `/v1/responses`, `/v1/messages` (formato de Anthropic), `/v1/embeddings`, `/v1/images/*` y `/v1/audio/transcriptions`. Cada respuesta incluye `x-request-id`. Las solicitudes realizadas con virtual keys limitadas también incluyen headers `x-ratelimit-*`.

</Step>
</Steps>

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

- [Conceptos básicos](https://boelabs.com/docs/ai-gateway/concepts): cómo se relacionan public models, pools, adapters y transports.
- [Arquitectura](https://boelabs.com/docs/ai-gateway/architecture): recorrido de una solicitud por cada capa.
- [Crear deployments](https://boelabs.com/docs/ai-gateway/creating-deployments): configuración de proveedores y modelos personalizados.
- [Fallbacks](https://boelabs.com/docs/ai-gateway/fallbacks): cómo responder ante la caída de un proveedor.
- [Solución de problemas](https://boelabs.com/docs/ai-gateway/troubleshooting): qué significan los errores `400`/`401`/`403`/`429`/`503` y cómo resolverlos.