---
name: aigateway
description: Use when integrating with, calling, or choosing models on AIgateway (aigateway.sh) — one OpenAI-compatible API for 1000+ frontier and open-weight models across every modality (chat, vision, images, audio/STT/TTS, video, music, embeddings, rerank, classification, moderation, OCR, object detection, 3D). Covers auth, the base-URL swap, live model discovery, picking the right model and endpoint, the auto-router, async jobs, and aggregator primitives.
---

# AIgateway

One API key, every model, every modality. AIgateway is a drop-in OpenAI-compatible endpoint in front of 1000+ models. Keep your existing OpenAI SDK code; change the base URL and key.

- HTTP API: `https://api.aigateway.sh/v1`
- Anthropic Messages API: `POST /v1/messages` and `POST /anthropic/v1/messages` (+ `…/count_tokens`) — the official Anthropic SDK and Claude Code work drop-in; auth via `x-api-key: sk-aig-...` (or Bearer) with header `anthropic-version: 2023-06-01`. Any catalog slug is selectable (bare `claude-*` names resolve to `anthropic/*`; pass `provider/slug` to run on any other model).
- MCP server: `https://api.aigateway.sh/mcp` (Streamable HTTP, MCP 2025-03-26) · legacy SSE `…/mcp/sse` · inspector `…/mcp/inspect`
- Auth: `Authorization: Bearer sk-aig-...` — get a key at https://aigateway.sh/signin

## Golden rule: discover live, never guess

The catalog changes every day. Do **not** hardcode model ids, prices, or context windows from memory — they go stale. Before invoking a model you have not used, look up its real contract:

- **MCP (preferred for agents):** call `get_model` with the slug → returns the exact endpoint, request/response/streaming examples, model-specific quirks, and runnable curl/Python/TS snippets. Browse with `list_models` / `search_models` (filter by `modality`, `provider`, or `capability`).
- **REST:** `GET /v1/models/{id}/schema` (per-model invocation contract) · `GET /v1/models?modality=&provider=&capability=` (browse) · `GET /v1/capabilities` (the authoritative capability → endpoint map).
- **Quick answers:** fetch `https://aigateway.sh/llms.txt` (cheapest / longest-context / best-coding / fastest / free) and `https://aigateway.sh/llms-full.txt` (full catalog with prices).

## Connect (OpenAI SDK drop-in)

```python
from openai import OpenAI
client = OpenAI(base_url="https://api.aigateway.sh/v1", api_key="sk-aig-...")
# model ids are "provider/slug" — discover current ones with list_models; don't assume
resp = client.chat.completions.create(
    model="<provider/slug>",
    messages=[{"role": "user", "content": "Hi"}],
)
```

```typescript
import OpenAI from "openai";
const client = new OpenAI({ baseURL: "https://api.aigateway.sh/v1", apiKey: process.env.AIG_KEY });
await client.chat.completions.create({ model: "<provider/slug>", messages: [{ role: "user", content: "Hi" }] });
```

## MCP — the agent-native surface

Add the server to your host, then use the tools directly:

```json
{ "mcpServers": { "aigateway": { "type": "http", "url": "https://api.aigateway.sh/mcp", "headers": { "Authorization": "Bearer sk-aig-..." } } } }
```

- **Discovery:** `list_models`, `search_models`, `get_model`
- **Invocation:** `chat`, `embed`, `generate_image`, `transcribe`, `speak`, `translate`, `classify`, `moderate`, `rerank`, `ocr`, `detect_objects`
- **Async:** `generate_video`, `generate_music`, `generate_3d` → return a job id; poll `get_job` (or `cancel_job`)

## Pick the endpoint by modality

`/v1/capabilities` is the source of truth (each capability lists its endpoint). The common mapping:

| Modality | Endpoint |
|---|---|
| chat / vision / reasoning / tool-calling | `POST /v1/chat/completions` |
| embeddings | `POST /v1/embeddings` |
| image | `POST /v1/images/generations` |
| speech-to-text | `POST /v1/audio/transcriptions` |
| text-to-speech | `POST /v1/audio/speech` |
| rerank · classify · moderate · translate · ocr · detect | `POST /v1/rerank` · `/v1/classifications` · `/v1/moderations` · `/v1/translations` · `/v1/ocr` · `/v1/detections` |
| video · music · 3D (async) | `POST /v1/videos/generations` · `/v1/audio/music` · `/v1/3d/generations` → poll `GET /v1/jobs/{id}` |

## Auto-router

Pass `model: "auto"` to let the gateway route by request complexity within the requested modality — cheaper on easy calls, stronger on hard ones. Works across modalities.

## Aggregator primitives (REST/SDK, not MCP)

- **Sub-accounts** — scoped keys with spend caps for per-customer billing (`POST /v1/sub-accounts`).
- **Evals** — grade candidate models on your dataset; route to the live winner with `model: "eval:<name>"`.
- **Replays** — re-run a past request on a different model.
- **Webhooks** — signed callbacks for async jobs; both SDKs ship verifiers.

Use `aigateway-py` / `aigateway-js` for these; use the `openai` package for chat/embeddings/images/audio.

## Errors

OpenAI-shaped envelope: `{ error: { message, type, code } }`. On HTTP 429 honor `Retry-After`.

## When unsure

- Full per-endpoint reference: https://aigateway.sh/reference.md
- Agent integration playbook (Claude Code, Cursor, Cline, Windsurf, …): https://aigateway.sh/agents.md
- For any unfamiliar model, call `get_model` / `GET /v1/models/{id}/schema` **first** — never guess the request shape.