Inicio rápido

Ejecutar el gateway

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:

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:

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

Confirma que está activo:

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

Para el resto de esta página:

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

Registrar un 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:

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.

Crear una virtual key

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

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:

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

Consulta Virtual keys para configurar presupuestos, límites de RPM/TPM y rotación.

Realizar una solicitud

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

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." }]
  }'

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-*.