Getting Started with AI Gateway

Make your first AI Gateway request, then verify its model, provider, usage, cost, and routing in the Vercel dashboard. You can start with the AI SDK for TypeScript or Python, send raw HTTP with cURL, use an existing compatible client, or connect a coding agent.

You need a Vercel account and a team with a valid payment method, which unlocks free AI Gateway Credits. The TypeScript path needs Node.js 22 or later, the Python path needs Python 3.12 or later, and the cURL path needs neither.

1. If your team does not have a valid payment method, add one to unlock free credits.
2. Open the Create API Key dialog, enter a name, and create the key.
3. Copy the key immediately. You cannot retrieve its value again.
4. Export the key in the terminal where you will run the example:

export AI_GATEWAY_API_KEY="your_ai_gateway_api_key"

Keep this terminal open so the example can read AI_GATEWAY_API_KEY.

These examples use openai/gpt-5.6-sol and consume AI Gateway Credits. You can replace the model slug with any model your team can access. The free tier covers a subset of the catalog, so if your team has not purchased credits, start from a free-tier model: any other model returns a 403 until you add credits.

mkdir ai-gateway-quickstart
cd ai-gateway-quickstart
pnpm init
pnpm add ai@latest tsx typescript @types/node

import { generateText } from 'ai';
 
async function main() {
  const { text } = await generateText({
    model: 'openai/gpt-5.6-sol',
    prompt: 'Invent a new holiday and describe its traditions.',
  });
 
  console.log(text);
}
 
main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

pnpm tsx index.ts

mkdir ai-gateway-python-quickstart
cd ai-gateway-python-quickstart
uv init
uv add ai

import asyncio
import ai
 
 
async def main() -> None:
    model = ai.get_model('openai/gpt-5.6-sol')
    messages = [
        ai.user_message('Invent a new holiday and describe its traditions.')
    ]
 
    async with ai.stream(model, messages) as stream:
        async for event in stream:
            if isinstance(event, ai.events.TextDelta):
                print(event.chunk, end='', flush=True)
 
    print()
 
 
if __name__ == '__main__':
    asyncio.run(main())

uv run python quickstart.py

curl https://ai-gateway.vercel.sh/v1/chat/completions \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-5.6-sol",
    "messages": [
      {
        "role": "user",
        "content": "Invent a new holiday and describe its traditions."
      }
    ]
  }'

A successful request prints or returns the model's description of a new holiday.

Open AI Gateway Logs and select the newest request. The log shows:

• The HTTP status and model
• The provider that served the request
• Input and output token usage
• Cost and total duration
• Every routing attempt, including recovered failures

Request logs take about 90 seconds to fully ingest. If the request does not appear immediately, wait and refresh the page.

Match the response to its cause below. A 403 has three different causes, so read the error message rather than assuming the first one.

AI Gateway model IDs use a provider/model format, such as openai/gpt-5.6-sol or anthropic/claude-opus-5. A provider's own model name needs its prefix to route, and you should use IDs exactly as the catalog returns them rather than constructing variants by analogy.

Find the current ID for a model in two places:

• The model list, with filters for modality, capability, provider, price, and free-tier eligibility
• GET /v1/models, which returns every model's ID, modalities, capability tags, context window, and pricing, without authentication

For per-provider pricing, regional availability, and live performance on one model, query GET /v1/models/{creator}/{model}/endpoints.

AI Gateway supports several API shapes. Point an existing client at the matching base URL and keep using the same provider/model slugs.

Authentication, model IDs, provider routing, fallbacks, billing, and observability work across these API shapes.

Install Vercel's focused AI Gateway skill. The skill covers current authentication, model discovery, compatible clients, routing, budgets, observability, and verification:

npx skills add vercel/vercel-plugin --skill ai-gateway

Then copy the prompt below into a coding assistant with access to your project:

When the task moves into SDK-specific implementation, the skill can chain to Vercel's AI SDK skill. You can also install the Vercel Plugin with npx plugins add vercel/vercel-plugin for skills across the rest of the Vercel platform.

The AI SDK includes ToolLoopAgent for applications that need model-driven loops and tools, built on the same setup and API key as your first request. See Build agents with the AI SDK. Python applications can use ai.Agent.

The Vercel CLI can configure supported coding agents to route their model requests through AI Gateway. Install the latest CLI and sign in if needed:

npm i -g vercel@latest
vercel login

Run the interactive setup:

vercel ai-gateway coding-agents setup

The command detects installed agents, provisions or reuses an AI Gateway API key, previews every planned configuration change, and asks for confirmation before writing. On macOS, it stores the key in your login Keychain by default rather than in plaintext configuration.

The command configures Claude Code, Cline, Codex, Cursor, Hermes, Kilo Code, omp, OpenClaw, OpenCode, and Pi. To connect specific agents, pass one or more --agent values. For example:

vercel ai-gateway coding-agents setup --agent claude-code --agent codex

For every --agent value, along with --all, --yes, custom paths, Keychain storage, and desktop session migration, see the vercel ai-gateway CLI reference. The coding agents guide covers manual configuration, including agents the command does not handle.

Every docs page ships in agent-readable forms: append .md for Markdown or .graph.md for the cross-link map, and browse llms.txt or the semantic sitemap for the full index.

• Browse models by capability, provider, price, and free-tier availability, or query GET /v1/models
• Migrate an existing application
• Configure provider routing and model fallbacks
• Read the FAQ for pricing, compatibility, and data-handling questions