Skip to content
Docs

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:
Terminal
export AI_GATEWAY_API_KEY="your_ai_gateway_api_key"

Keep this terminal open so the example can read AI_GATEWAY_API_KEY.

Applications deployed on Vercel can use an OIDC token instead of a long-lived API key. This tutorial uses an API key so the same examples work locally and outside Vercel.

What you want to doStart here
Make a request with TypeScript, Python, or cURLMake your first request
Use the OpenAI or Anthropic APIUse an existing client
Move an existing provider integrationMigrate to AI Gateway
Build an agent applicationBuild an agent
Route a coding agent through AI GatewayConnect a coding agent

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.

Create a project and install the AI SDK:

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

Create index.ts:

index.ts
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;
});

Run the script:

Terminal
pnpm tsx index.ts

Create a project with uv and install the AI SDK for Python:

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

Create quickstart.py:

quickstart.py
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())

Run the script:

Terminal
uv run python quickstart.py

Send a Chat Completions request directly to AI Gateway:

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

The response is a Chat Completions JSON object. The generated text is in choices[0].message.content.

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.

Response or symptomWhat it meansWhat to do
401The API key or OIDC token is missing, invalid, or revokedExport a current AI Gateway key and retry
402 whose type is not quota_for_entity_exceededThe team does not have a positive credit balanceAdd AI Gateway Credits
402 with quota_for_entity_exceededA team, project, API key, or user budget has reached its limitWait for the budget to refresh or raise its limit
403 with customer_verification_requiredThe team must add a valid payment method before it can use free creditsAdd a payment method from the link in the error response
403 whose message names the free tierThe model is not in the free-tier subset, so it needs purchased creditsPick a free-tier model or add AI Gateway Credits
403 whose message names team restrictionsA model or provider allowlist blocks the requestChoose an allowed model, or ask a team owner to update the allowlist
429A rate limit was exceeded, from AI Gateway or the upstream providerRetry after a short wait; the paid tier removes AI Gateway's rate limits

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.

Client or APIAI Gateway URLGuide
AI SDKNo base URL needed for string model IDsAI SDK
AI SDK for PythonNo base URL needed for string model IDsAI SDK for Python
OpenAI Chat Completions or Responseshttps://ai-gateway.vercel.sh/v1OpenAI Chat Completions and OpenAI Responses
Anthropic Messageshttps://ai-gateway.vercel.shAnthropic Messages
OpenResponseshttps://ai-gateway.vercel.sh/v1OpenResponses
LangChain, LlamaIndex, Pydantic AI, and other frameworksVaries by integrationFramework integrations

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:

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

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

Agent Prompt

Use the AI Gateway skill to add text generation to this project. Read AI_GATEWAY_API_KEY from the environment or .env.local, and stop and tell me to create a key if it is not set anywhere. Choose a current text model such as openai/gpt-5.6-sol from the live AI Gateway model list, print the generated text, run the result, and run the project's type checker. Report the files changed and command output.

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:

Terminal
npm i -g vercel@latest
vercel login

Run the interactive setup:

Terminal
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:

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

Last updated September 2, 2026

Was this helpful?

supported.