The Anthropic Messages API supports the same authentication methods as the main AI Gateway:

API key: Use your AI Gateway API key with the x-api-key header or Authorization: Bearer header

OIDC token: Use your Vercel OIDC token with the Authorization: Bearer header

You only need to use one of these forms of authentication. If an API key is specified it will take precedence over any OIDC token, even if the API key is invalid.

Supported endpoints

The AI Gateway supports the following Anthropic Messages API endpoints:

• POST /v1/messages - Create messages, with support for streaming, tool calling, extended thinking, structured outputs, and images
• POST /v1/messages/count_tokens - Count tokens in a message before sending it to Claude, for managing context windows and costs

• POST /v1/messages/batches - Create a message batch
• GET /v1/messages/batches - List message batches
• GET /v1/messages/batches/{batch_id} - Retrieve a message batch
• GET /v1/messages/batches/{batch_id}/results - Read message batch results

For advanced features, see:

• Extended thinking - Configure how much Claude thinks before answering
• Advanced features - Web search, provider timeouts, and automatic caching
• Structured outputs - JSON Schema-constrained responses

Configuring Claude Code

Claude Code is Anthropic's agentic coding tool. You can configure it to use Vercel AI Gateway, enabling you to:

• Route requests through multiple AI providers
• Monitor traffic and spend in your AI Gateway Overview
• View detailed traces in Vercel Observability under AI
• Use any model available through the gateway

1. Configure environment variablesConfigure Claude Code to use the AI Gateway by setting these environment variables: Variable Value ANTHROPIC_BASE_URL https://ai-gateway.vercel.sh Your AI Gateway API key ANTHROPIC_AUTH_TOKEN "" (empty string) ANTHROPIC_API_KEY

   

   Option 1: Shell alias (simplest)Add this alias to your ~/.zshrc (or ~/.bashrc):

   aliasclaude-vercel='ANTHROPIC_BASE_URL="https://ai-gateway.vercel.sh" ANTHROPIC_AUTH_TOKEN="your-api-key-here" ANTHROPIC_API_KEY="" claude'

   Then reload your shell:

   source~/.zshrc

   Option 2: Wrapper scriptFor more flexibility (e.g., adding additional logic), create a wrapper script at ~/bin/claude-vercel:

   

   #!/usr/bin/env bash # Routes Claude Code through Vercel AI Gateway ANTHROPIC_BASE_URL="https://ai-gateway.vercel.sh" \ ANTHROPIC_AUTH_TOKEN="your-api-key-here" \ ANTHROPIC_API_KEY="" \ claude "$@"Make it executable and ensure ~/bin is in your PATH:

   mkdir -p~/bin

   chmod +x~/bin/claude-vercel

   echo'export PATH="$HOME/bin:$PATH"'>>~/.zshrc

   source~/.zshrc

2. Run Claude CodeRun claude-vercel to start Claude Code with AI Gateway: claude-vercelYour requests will now be routed through Vercel AI Gateway.

Save the printed batch ID to resume polling with client.messages.batches.retrieve later. The batch keeps processing after the example stops waiting.

When processing ends, a non-null results_url indicates that results are available. The SDK uses this URL when you call results. Individual requests can still fail. Match each result to its request by custom_id, regardless of result order. Successful results include result.message; other results report errored, canceled, or expired.

List batches

Use await client.messages.batches.list({ limit: 20 }) in TypeScript or JavaScript, or client.messages.batches.list(limit=20) in Python. The default page size is 20, with a maximum of 100. Pass either after_id or before_id to paginate, never both.

Batch requirements

• stream (boolean): Whether to stream the response. Defaults to false
• temperature (number): Controls randomness in the output. Range: 0-1
• top_p (number): Nucleus sampling parameter. Range: 0-1
• top_k (integer): Top-k sampling parameter
• stop_sequences (array): Stop sequences for the generation
• tools (array): Array of tool definitions for function calling
• tool_choice (object): Controls which tools are called
• thinking (object): Extended thinking configuration
• system (string or array): System prompt

Where to place cache breakpoints

Add cache_control: { type: 'ephemeral' } to mark content that should be cached. You can place cache breakpoints on system messages, user message content, tool definitions, tool results, and assistant message content. Anthropic also supports automatic caching, where a single top-level cache_control field automatically applies to the last cacheable block.

For the full list of cacheable locations and automatic caching details, see the Anthropic prompt caching docs.

Cache behavior

• First request: Content up to the breakpoint is cached ( cache_creation_input_tokens)
• Subsequent requests: Matching prefixes are read from cache ( cache_read_input_tokens)
• TTL: Cached content expires after 5 minutes, refreshed on each cache hit

Configuring the Claude Agent SDK

The Claude Agent SDK ( @anthropic-ai/claude-agent-sdk) lets you build agents with the same tools and agentic loop that power Claude Code. Because the SDK spawns Claude Code as a subprocess, it inherits the same ANTHROPIC_* environment variables described above, so your agent code needs no gateway-specific configuration:

import { query } from'@anthropic-ai/claude-agent-sdk';

forawait (constmessageofquery({

prompt:'Find and fix the bug in auth.ts',

options: { allowedTools: ['Read','Edit','Bash'] },

})) {

console.log(message);

}

Refer to the Claude Agent SDK documentation for more details.

Passing AI Gateway options

The Agent SDK respects any environment variable the Claude Code CLI reads, including these two for working with AI Gateway:

Common error codes

• 400 Bad Request: Invalid request parameters
• 401 Unauthorized: Invalid or missing authentication
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Model or endpoint not found
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

Error response format

{

"type":"error",

"error": {

"type":"invalid_request_error",

"message":"Invalid request: missing required parameter 'max_tokens'"

}

}