/ai-gateway

Setup and compatible APIs

Use this reference for first requests, authentication setup, migration, and compatible clients.

First request

1. Confirm a Vercel account and team are available.
2. For free AI Gateway Credits, the team needs a valid payment method. If the gateway returns customer_verification_required, use the action URL in the error.
3. Create an AI Gateway API key from the dashboard or CLI, or use OIDC for a Vercel deployment.
4. Export AI_GATEWAY_API_KEY in the shell or load it from an uncommitted environment file.
5. Fetch /v1/models, choose a current model, and make one request.
6. Print or return the result.
7. Open AI Gateway Logs and inspect the model, provider, usage, cost, status, and routing attempts. Allow about 90 seconds for ingestion.

Canonical tutorial: https://vercel.com/docs/ai-gateway/getting-started

When a user asks a coding agent to make this request, the coding agent is the tool writing and running the API call. Its own inference does not need to use AI Gateway. The selected provider/model is the target of the request, not the identity of the coding agent. Routing the agent's own model traffic is a separate workflow routed from SKILL.md.

API key setup

Dashboard: https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai-gateway%2Fapi-keys&title=AI+Gateway+API+Keys

export AI_GATEWAY_API_KEY="your_ai_gateway_api_key"

The key value is shown once. Never write it to committed source or print it in a response.

Agent-safe credential handling

Reuse an existing key without revealing it. Do not inspect the environment with broad commands such as env, bare set, or printenv, and do not echo the value. Use a subshell so tracing is restored automatically:

(
  set +x
  if [ -n "${AI_GATEWAY_API_KEY:-}" ]; then
    echo "AI_GATEWAY_API_KEY is set"
  else
    echo "AI_GATEWAY_API_KEY is missing"
  fi
)

If the key exists, skip CLI login and team-scope discovery unless another requested operation needs them. If it is missing and the user authorized key creation:

1. Use the existing project CLI when available; otherwise use npx vercel@latest without installing globally.
2. Read ai-gateway api-keys create --help before choosing flags.
3. Reuse the current CLI team scope. Ask for a team only when that scope is missing or ambiguous.
4. Prefer an interactive prompt or OS credential store. Never put a literal key in shell history or a command argument, and never send raw key output through agent logs or chat.
5. Keep shell tracing disabled while a secret is in scope; prefer a subshell so the prior tracing state returns automatically.

For a one-request smoke test, report the generated content, whether the request succeeded, and any action the user must take. Do not dump authorization headers or an unfiltered raw response.

Use the CLI when the user asks for CLI management:

vercel ai-gateway api-keys create --name my-api-key

The CLI can bind a budget, spend alerts, and an expiry at creation, which beats re-editing the key later:

vercel ai-gateway api-keys create --budget 500 --alert-thresholds 75,100 --expiration 90d

inspect shows a key's budget, spend, BYOK spend, alerts, and expiry; list shows every key. Run vercel ai-gateway api-keys create --help before scripting because available quota, expiration, alert, and restriction-exemption flags change.

OIDC setup

OIDC is preferred for Vercel deployments because the deployment receives VERCEL_OIDC_TOKEN automatically. For local development against a linked Vercel project:

vercel link
vercel env pull

The current OIDC documentation states that locally pulled tokens are valid for 12 hours. Re-run vercel env pull when the token expires.

Do not say that OIDC removes request authentication. The token authenticates the request to AI Gateway. BYOK credentials are separate provider credentials.

Docs: https://vercel.com/docs/ai-gateway/authentication-and-byok/oidc

AI SDK

Current AI SDK JavaScript releases require Node.js 22 or later. Verify the installed package rather than upgrading an established project without approval.

A plain provider/model string uses AI Gateway:

import { generateText } from 'ai';

const model = process.env.AI_GATEWAY_MODEL;
if (!model) {
  throw new Error('Set AI_GATEWAY_MODEL to an ID returned by /v1/models');
}

const { text } = await generateText({
  model,
  prompt: 'Explain this codebase.',
});

console.log(text);

Load the ai-sdk skill and read node_modules/ai/docs/ before writing SDK-specific code. Use @ai-sdk/gateway exports only when needed. Do not add a provider-specific package for a model called through AI Gateway.

AI SDK for Python

Current AI SDK for Python releases require Python 3.12 or later. Install and follow its current docs:

uv add ai

import asyncio
import os
import ai


async def main() -> None:
    model = ai.get_model(os.environ['AI_GATEWAY_MODEL'])
    messages = [ai.user_message('Explain this project.')]

    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)


asyncio.run(main())

Docs: https://vercel.com/docs/ai-gateway/sdks-and-apis/ai-sdk-python

Compatible clients

Keep the client's request shape and replace its base URL and request authentication. AI Gateway model IDs remain provider/model strings even when using an OpenAI or Anthropic SDK.

Docs: https://vercel.com/docs/ai-gateway/sdks-and-apis

Migration

For an existing integration:

1. Inventory the SDK, model IDs, provider-specific request fields, provider credentials, streaming behavior, and error handling.
2. Choose the closest AI Gateway API shape. An existing OpenAI or Anthropic client can usually keep its SDK.
3. Change request authentication and the base URL.
4. Map model IDs to live AI Gateway slugs. Do not mechanically prepend a provider name.
5. Preserve provider-specific options that the selected API supports.
6. Remove direct-provider credentials only after the AI Gateway path passes a live request.
7. Verify usage, cost, and routing in Logs.

Migration guide: https://vercel.com/docs/ai-gateway/getting-started/migrate-to-ai-gateway

Common first-request errors