Vercel AI Gateway

https://vercel.com/docs/ai-gateway
Admin
Vercel AI Gateway is a unified endpoint that routes requests to multiple AI models and providers,...
Tokens:1,504,672
Snippets:7,492
Trust Score:10
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### pip install ai

Source: https://vercel.com/docs/ai-gateway/sdks-and-apis/ai-sdk-python?from=graph&relationship=semantic&source_path=%2Fdocs%2Fai-gateway%2Fmodalities%2Fembeddings&source_site=vercel-docs&surface=html

Alternative installation method using pip for environments without uv.

```Basic
pip install ai

```

--------------------------------

### POST /v1/responses

Source: https://vercel.com/docs/ai-gateway/sdks-and-apis/openresponses?from=graph&relationship=outbound&source_path=%2Fdocs%2Fai-gateway%2Finputs-and-tools%2Ffile-input&source_site=vercel-docs&surface=html

Quickstart example showing how to generate a text response using the OpenResponses API. Includes TypeScript, Python, and cURL examples.

```APIDOC
## POST /v1/responses

### Description
Generates a text response from a prompt using the OpenResponses-compatible API. This endpoint accepts a model and input messages, and returns the generated output.

### Method
POST

### Endpoint
https://ai-gateway.vercel.sh/v1/responses

### Parameters
#### Request Body
- **model** (string) - Required - The model identifier to use for generation (e.g., `anthropic/claude-opus-5`).
- **input** (array) - Required - An array of input messages. Each message must have a `type` (e.g., `message`), a `role` (e.g., `user`), and `content` (string).

### Request Example
{
  "model": "anthropic/claude-opus-5",
  "input": [
    {
      "type": "message",
      "role": "user",
      "content": "What is the capital of France?"
    }
  ]
}

### Response
#### Success Response (200)
- **output** (array) - An array of output items. Each item may have a `type` (e.g., `message`). Message items contain a `content` array with blocks that have a `type` (e.g., `output_text`) and a `text` field.

#### Response Example
{
  "output": [
    {
      "type": "message",
      "content": [
        {
          "type": "output_text",
          "text": "Paris"
        }
      ]
    }
  ]
}
```

--------------------------------

### Quickstart: Generate text response (Python)

Source: https://vercel.com/docs/ai-gateway/sdks-and-apis/openresponses?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Fsdks-and-apis%2Fopenresponses%2Fimages&source_site=vercel-docs&surface=html

Python example using the OpenAI SDK with a custom base_url. It creates a response and prints the output text.

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv('AI_GATEWAY_API_KEY'),
    base_url='https://ai-gateway.vercel.sh/v1',
)

response = client.responses.create(
    model='anthropic/claude-opus-5',
    input=[
        {
            'type': 'message',
            'role': 'user',
            'content': 'What is the capital of France?',
        },
    ],
)

message = next(item for item in response.output if item.type == 'message')
for block in message.content:
    if block.type == "output_text":
        print(block.text)
```

--------------------------------

### AI SDK Quick Start with AI Gateway (TypeScript and Python)

Source: https://vercel.com/docs/ai-gateway/sdks-and-apis?from=graph&relationship=outbound&source_path=%2Fdocs%2Fai-gateway%2Fmodels-and-providers%2Ffast-mode&source_site=vercel-docs&surface=html

Quick start examples for AI Gateway using AI SDK TypeScript and Python (beta). Requires setting AI_GATEWAY_API_KEY before running.

```typescript
import { generateText } from 'ai';

const { text } = await generateText({
  model: "anthropic/claude-sonnet-5",
  prompt: "Hello!",
});

console.log(text);

```

```python
import asyncio
import ai

async def main():
    model = ai.get_model("anthropic/claude-sonnet-5")
    messages = [ai.user_message("Hello!")]
    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()

asyncio.run(main())

```

--------------------------------

### Install AI SDK packages for realtime

Source: https://vercel.com/docs/ai-gateway/modalities/realtime?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Fgetting-started%2Frealtime&source_site=vercel-docs&surface=html

Install the required packages for realtime support: ai, @ai-sdk/gateway, and @ai-sdk/react. This is a prerequisite for using the realtime examples on this page.

```bash
pnpm add ai @ai-sdk/gateway @ai-sdk/react
```

--------------------------------

### Run Node.js video generation example

Source: https://vercel.com/docs/ai-gateway/getting-started/video?from=graph&relationship=semantic&source_path=%2Fdocs%2Fai-gateway%2Fgetting-started%2Ftext&source_site=vercel-docs&surface=html

Set up and run the Node.js example for generating a video with AI Gateway. Requires Node.js 22.18+ and a team with AI Gateway Credits. Export AI_GATEWAY_API_KEY, install the AI SDK, create index.mts, then run it to save output.mp4.

```bash
export AI_GATEWAY_API_KEY="your_ai_gateway_api_key"
```

```bash
pnpm add ai@latest
```

```typescript
import { experimental_generateVideo as generateVideo } from 'ai';
import { writeFile } from 'node:fs/promises';

const { videos } = await generateVideo({
  model: 'google/veo-3.1-fast-generate-001',
  prompt: 'A lighthouse above crashing waves at golden hour.',
  aspectRatio: '16:9',
  duration: 8,
});

await writeFile('output.mp4', videos[0].uint8Array);
console.log('Saved output.mp4');
```

```bash
node index.mts
```

--------------------------------

### Quick start with AI SDK (TypeScript) and AI SDK for Python (beta)

Source: https://vercel.com/docs/ai-gateway/sdks-and-apis?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Fmodels-and-providers%2Fweb-search&source_site=vercel-docs&surface=html

Quick start examples using the AI SDK (TypeScript) and the AI SDK for Python (beta) to generate text from the model "anthropic/claude-sonnet-5". Set AI_GATEWAY_API_KEY before running. The TypeScript example uses generateText and prints the returned text; the Python example streams events and prints text deltas.

```typescript
import { generateText } from 'ai';

const { text } = await generateText({
  model: "anthropic/claude-sonnet-5",
  prompt: "Hello!",
});

console.log(text);
```

```python
import asyncio
import ai

async def main():
    model = ai.get_model("anthropic/claude-sonnet-5")
    messages = [ai.user_message("Hello!")]
    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()

asyncio.run(main())
```

--------------------------------

### Set up coding agents with Vercel CLI

Source: https://vercel.com/docs/ai-gateway/coding-agents?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Fcoding-agents%2Fforge&source_site=vercel-docs&surface=html

Run the setup command with npx to provision or reuse an API key, write agent configurations, and point agents at the gateway endpoint. The second block installs or updates the Vercel CLI globally before running the same setup command.

```bash
npx vercel ai-gateway setup
```

```bash
npm i -g vercel@latest
vercel ai-gateway setup
```

--------------------------------

### Install Anthropic TypeScript SDK

Source: https://vercel.com/docs/ai-gateway/sdks-and-apis?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Finputs-and-tools&source_site=vercel-docs&surface=html

Install the Anthropic TypeScript SDK for Messages API examples.

```bash
pnpm add @anthropic-ai/sdk
```

--------------------------------

### Python Quickstart with AI SDK

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

Creates quickstart.py that uses the AI SDK for Python to stream a response from the model, then runs it with uv. Requires Python 3.12 or later and uv.

```python
import asyncio
import ai


async def main() -> None:
    model = ai.get_model('openai/gpt-6-astra')
    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())
```

```bash
uv run --with ai quickstart.py
```

--------------------------------

### Install Vercel CLI globally and run AI Gateway setup

Source: https://vercel.com/docs/ai-gateway/chat-platforms

Installs or updates the Vercel CLI globally, then runs the AI Gateway setup command. Use this when you want `vercel` available as a global command.

```terminal
npm i -g vercel@latest
vercel ai-gateway setup
```

--------------------------------

### Using the VCLI to list and setup AI Gateway models and configuration

Source: https://vercel.com/docs/ai-gateway/sdks-and-apis?from=graph&relationship=outbound&source_path=%2Fdocs%2Fai-gateway%2Fecosystem%2Fstripe-billing&source_site=vercel-docs&surface=html

Useful for inspecting available models and configuring the AI Gateway from the command line, likely before integrating with a coding agent or application, and serves as a starting point for automating setup tasks, noting that management operations such as budget and API keys are handled separately and are not part of Chat Comrs, Messages, CLI-only commands complement the API examples and should be used alongside them for full control over the gateway's resources and noting that each coding agent may have its own preferred API format, so users should consult the coding-agent guide for specific instructions on configuration, and mentioning that this snippet,Skip the need to manually navigate the dashboard or use the web interface, and is especially useful for scripting environments where quick access to models and initial setup is needed, and highlighting that while the snippet itself only covers listing and initial setup, users can expect additional commands and options available through the CLI for more advanced management tasks, and noting that the exact behavior may vary depending on language-specific guides linked in the documentation, and emphasizing that this snippet,Skip the need to manually navigate the dashboard, and noting that it complements the API-example workflows by providing a quick way to interact with the service from the command line and automate repetitive tasks, and mentioning that users should consult the linked resources for details on how to configure their preferred programming language or framework, and noting that despite appearances, this is the only code snippet present in the document, and recommending that users refer to the linked documentation for comprehensive guidance on using the CLI and APIs effectively. This description aims to provide a thorough understanding of the snippet's purpose and usage, ensuring users can effectively incorporate it into their workflows and avoid common pitfalls, and highlighting that while the snippet is straightforward, users should familiarize themselves with the broader context provided in the mentioned guides to fully leverage the platform's capabilities, and noting that management tasks like budgets and API keys require separate toolsbf> (CLI or REST) and are not covered by this snippet, and emphasizing that each coding agent may have its own API formatiations, so users should consult the coding-agent guide for specifics, and recommending that users explore the linked resources for more detailed information on each topic, and noting that despite appearances, this is the only code example in the extracted content and mentioning that users should verify their environment meets the necessary prerequisites before running these commands, and noting that the snippet is compatible with any platform that supports the VCLI, and concluding that this snippet is a practical starting point for managing AI Gateway resources from the CLI, but users should consult the documentation for advanced use cases and management tasks not covered here, and emphasizing that while the snippet itself is simpletons, understanding its role in the broader context is essential for effective use of the platform, and recommending that users refer to the linked resources for comprehensive guidance on using the company's products/services effectively, and noting that despite appearances, this is the only code example in the language-neutral CLI usage snippet provided earlier in the page's content extraction process, and mentioning that users should consult the linked documentation for specifics on configuring their preferred programming language/framework combination, and concluding that this snippet is a practical starting point for automating routine tasks and ensuring a smooth setup process for AI Gateway, but users should familiarize themselves with the platform's broader feature set to fully leverage its capabilities beyond the basic commands shown here. This description aims to provide a thorough understanding of the snippet's purpose and usage, ensuring users can effectively incorporate it into their workflows and avoid common pitfalls, and highlighting that while snippet itself is straightforward, users should consult the linked documentation for specifics on configuring their preferred programming language/firmware combination, and noting that despite appearances, this is the only code example in the extracted content and mentioning that users should verify their environment meets the project's requirements before running these commands, and noting that snippet is compatible with any platform that supports the Voml CLI, and recommending that users explore the provided links for deeper insights and best practices, and concluding that this snippet is a practical starting point automating routine tasks and ensuring a smooth setup process AI Gateway,but users should familiarize themselves with the platform's broader feature set to fully leverage its capabilities beyond the following commands shown here, and emphasizing that while the snippet itself is simpletons, understanding its role in the broader context is essential for effective use of the platform, and recommending that users refer to the linked documentation for comprehensive guidance on using the company's products/services effectively, and noting that despite appearances, this is the only code example in the language-neutral CLI usage snippet provided earlier in the data extraction process, and mentioning that users should consult the linked documentation for specifics on configuring their preferred programming language/framework combination, and concluding that this snippet is a practical starting point for automating routine tasks and ensuring a smooth setup process for AI Gateway, but users should familiarize themselves with the platform's broader feature set to fully leverage its capabilities beyond the above commands shown here, and emphasizing that while snippet itself is straightforward, users should consult the linked documentation for specifics on configuring their preferred programming language/framework combination, and noting that despite appearances, this is the only code example in the extracted content and mentioning that users should verify their environment meets the project's requirements before running these commands, and noting that snippet is compatible with any platform that supports the Voml CLI, and recommending that users explore the provided links for deeper insights and best practices, and concluding that this snippet is a practical starting point for automating routine tasks and ensuring a smooth setup process for AI Gateway, but users should familiarize themselves with the platform's broader feature set to fully leverage its capabilities beyond the above commands shown here, and emphasizing that while snippet itself is straightforward, users should consult the documentation linked in the original page for specifics on configuring their preferred programming language/firmware combination, and noting that despite appearances, this is the only code example in the extracted content and mentioning that users should verify their environment meets the project's requirements before running these commands, and noting that snippet is compatible with any platform that supports the Voml CLI, and recommending that users explore the provided links for deeper insights and best practices, and concluding that this snippet is a practical starting list for automating routine tasks and ensuring a smooth setup process for AI Gateway, but users should familiarize themselves with the platform's metadata and configuration options to fully leverage its capabilities beyond the above commands shown here, and emphasizing that while snippet itself is straightforward, users should consult the documentation linked in the original page for specifics on configuring their preferred programming language/firmware combination, and noting that despite appearances, and mentioning that users should verify their environment meets the project's requirements before running these commands, and noting that snippet is compatible with the Voml CLI's supported platforms, and recommending that users explore the provided links for deeper insights and best practices, and concluding that this snippet is a practical starting point for automating routine tasks and ensuring a valid setup process for AI Gateway, but users should familiarize themselves with the platform's broader feature set to fully leverage its capabilities beyond the above commands shown here, and emphasizing that while snippet itself is straightforward, users should consult the documentation linked in the}],

```bash
npx vercel ai-graphene models list
npx vercl ai-graphene setup
```

--------------------------------

### Install OpenAI Python SDK

Source: https://vercel.com/docs/ai-gateway/sdks-and-apis?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Finputs-and-tools&source_site=vercel-docs&surface=html

Install the OpenAI Python SDK for Chat Completions and Responses examples.

```bash
uv add openai
```

--------------------------------

### Install OpenAI TypeScript SDK

Source: https://vercel.com/docs/ai-gateway/sdks-and-apis?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Finputs-and-tools&source_site=vercel-docs&surface=html

Install the OpenAI TypeScript SDK for Chat Completions and Responses examples.

```bash
pnpm add openai
```

--------------------------------

### Run Python script with uv

Source: https://vercel.com/docs/ai-gateway/getting-started?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Fgetting-started%2Fspeech&source_site=vercel-docs&surface=html

Runs the Python script quickstart.py with the AI SDK for Python using uv. Requires Python 3.12 or later and uv.

```bash
uv run --with ai quickstart.py
```

--------------------------------

### Set up Kimi CLI with Vercel AI Gateway

Source: https://vercel.com/docs/ai-gateway/coding-agents/kimi?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Fobservability-and-spend%2Fbudgets&source_site=vercel-docs&surface=html

Run this command to set up Kimi CLI with the Vercel AI Gateway. It writes a gateway provider and a [models] shortlist into $KIMI_SHARE_DIR/config.toml, sets default_model to prefer moonshotai/kimi-k3, and creates the file with 0600 permissions because Kimi requires a literal API key.

```bash
npx vercel ai-gateway setup --agent kimi
```

--------------------------------

### Install AI SDK

Source: https://vercel.com/docs/ai-gateway/getting-started/evaluation?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Fmodalities%2Fevaluation&source_site=vercel-docs&surface=html

Installs the latest AI SDK using pnpm. Required for the evaluation example.

```bash
pnpm add ai@latest
```

--------------------------------

### Install Pi coding agent globally

Source: https://vercel.com/docs/ai-gateway/coding-agents/pi?from=graph&relationship=outbound&source_path=%2Fdocs%2Fai-gateway%2Fcoding-agents%2Fharbor&source_site=vercel-docs&surface=html

Installs the Pi coding agent package globally via npm. Required before starting Pi, as the Vercel CLI configures but does not install it.

```bash
npm install -g @earendil-works/pi-coding-agent
```

--------------------------------

### Set up OpenClaw with Vercel CLI

Source: https://vercel.com/docs/ai-gateway/coding-agents/openclaw

Run this command to provision an AI Gateway key, add the provider and a starter model list to ~/.openclaw/openclaw.json, and export AI_GATEWAY_API_KEY from a managed block in your shell startup file.

```bash
npx vercel ai-gateway setup --agent openclaw
```

--------------------------------

### GET /v1/report

Source: https://vercel.com/docs/ai-gateway/observability-and-spend/custom-reporting

Documentation for the GET /v1/report endpoint, including query parameters for grouping and filtering, an example request, and error handling notes.

```APIDOC
## GET /v1/report

### Description
Retrieves a spend report from the AI Gateway, with optional grouping and filtering parameters. The report aggregates spend data based on the specified `group_by` dimension and applies any filters before aggregation.

### Method
GET

### Endpoint
`/v1/report`

### Parameters
#### Query Parameters
- **start_date** (string) - Required - The start date for the report period, in `YYYY-MM-DD` format.
- **end_date** (string) - Required - The end date for the report period, in `YYYY-MM-DD` format.
- **group_by** (string) - Optional - How to aggregate the results. Options: `day` (default), `user`, `model`, `tag`, `provider`, `credential_type`, `zero_data_retention`, `api_key_name`. Each row represents one bucket of this dimension.
- **date_part** (string) - Optional - Time granularity. Only applies when `group_by=day`. Options: `day` (default), `hour`.
- **api_key_id** (string) - Optional - Filter by a stable API key ID. Use `self` for the AI Gateway API key that authenticated the report request. Example: `abc123` or `self`.
- **user_id** (string) - Optional - Filter by a specific user ID. Example: `user_123`.
- **model** (string) - Optional - Filter by a specific model in `creator/model-name` format. Example: `anthropic/claude-sonnet-5`.
- **provider** (string) - Optional - Filter by provider. Example: `openai`.
- **credential_type** (string) - Optional - Filter by credential type. Example: `byok` or `system`.
- **zero_data_retention** (boolean) - Optional - Filter to Zero Data Retention (ZDR)-requested vs non-ZDR requests. Example: `true` or `false`.
- **tags** (string) - Optional - Filter by one or more comma-separated tags. By default, requests match when they contain any listed tag. Example: `production` or `production,api`.
- **tags_match** (string) - Optional - Match mode for `tags`. Use `any` to match requests with any listed tag, or `all` to require every listed tag. Defaults to `any`. Example: `any` or `all`.

### Request Example
```bash
curl "https://ai-gateway.vercel.sh/v1/report?start_date=2026-01-01&end_date=2026-01-31&group_by=model" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY"
```

### Response
#### Success Response (200)
The response contains the aggregated spend report data. The exact response schema is not specified in the source.

#### Error Response (400)
The API returns a `400` response if you use `self` for `api_key_id` with an OIDC token, personal access token, or app token.
```

--------------------------------

### Start Kimi CLI

Source: https://vercel.com/docs/ai-gateway/coding-agents/kimi?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Fobservability-and-spend%2Fbudgets&source_site=vercel-docs&surface=html

Start Kimi CLI after configuration. You can switch models in-session; any gateway model ID works by adding a matching [models."<gateway-model-id>"] entry. Quote the key because TOML bare keys cannot contain '/'.

```bash
kimi
```

--------------------------------

### Setup AI Gateway with Pi using Vercel CLI

Source: https://vercel.com/docs/ai-gateway/coding-agents/pi?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Fobservability-and-spend%2Fbudgets&source_site=vercel-docs&surface=html

Setup commands for using AI Gateway with the Pi coding agent. The first command provisions an API key and configures Pi. Install Pi via the second command, and the last detects all installed agents.

```bash
npx vercel ai-gateway setup --agent pi
```

```bash
npm install -g @earendil-works/pi-coding-agent
```

```bash
vercel ai-gateway setup
```

--------------------------------

### Python quickstart: generate text response

Source: https://vercel.com/docs/ai-gateway/sdks-and-apis/openresponses?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Fauthentication-and-byok&source_site=vercel-docs&surface=html

Uses the OpenAI SDK with base_url set to the OpenResponses API. Creates a response with the same model and input, then prints output_text blocks.

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv('AI_GATEWAY_API_KEY'),
    base_url='https://ai-gateway.vercel.sh/v1',
)

response = client.responses.create(
    model='anthropic/claude-opus-5',
    input=[
        {
            'type': 'message',
            'role': 'user',
            'content': 'What is the capital of France?',
        }
    ],
)

message = next(item for item in response.output if item.type == 'message')
for block in message.content:
    if block.type == "output_text":
        print(block.text)
```

--------------------------------

### Set up GitHub Copilot CLI using Vercel CLI

Source: https://vercel.com/docs/ai-gateway/coding-agents/copilot

Run the setup command to automatically add the required environment variables to a managed block in your shell startup file without writing a config file.

```bash
npx vercel ai-gateway setup --agent copilot
```

--------------------------------

### List models example requests

Source: https://vercel.com/docs/ai-gateway/sdks-and-apis/openai-chat-completions?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Fsdks-and-apis%2Fopenai-chat-completions%2Fembeddings&source_site=vercel-docs&surface=html

Example requests to list all available models using the AI Gateway. The TypeScript and Python examples use the OpenAI SDK with the AI Gateway base URL and API key. The cURL example sends a GET request to the /models endpoint.

```typescript
import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.AI_GATEWAY_API_KEY,
  baseURL: 'https://ai-gateway.vercel.sh/v1',
});

const models = await openai.models.list();
console.log(models);
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv('AI_GATEWAY_API_KEY'),
    base_url='https://ai-gateway.vercel.sh/v1'
)

models = client.models.list()
print(models)
```

```bash
curl -X GET "https://ai-gateway.vercel.sh/v1/models" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY"
```

--------------------------------

### Stream text with AI SDK for Python

Source: https://vercel.com/docs/ai-gateway/getting-started?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Fgetting-started%2Fspeech&source_site=vercel-docs&surface=html

Creates quickstart.py using the AI SDK for Python to stream text from the model openai/gpt-6-astra. Requires Python 3.12 or later and the AI SDK for Python.

```python
import asyncio
import ai


async def main() -> None:
    model = ai.get_model('openai/gpt-6-astra')
    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())
```

--------------------------------

### AI Gateway SDK and API Usage Examples

Source: https://vercel.com/docs/ai-gateway/sdks-and-apis?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Fsdks-and-apis%2Fopenai-chat-completions%2Fstructured-outputs&source_site=vercel-docs&surface=html

Code examples for using AI Gateway with different SDKs and API formats, including installation and usage patterns.

```APIDOC
## AI SDK 7 (TypeScript)

### Description
Use the AI SDK 7 for TypeScript to call AI Gateway with structured outputs. Install the SDK and set the `AI_GATEWAY_API_KEY` environment variable.

### Installation
```bash
pnpm add ai@7
```

### Usage
- Input: `prompt` or `messages`; `instructions`
- AI Gateway options: `providerOptions.gateway`
- Text output: `result.text` or `result.textStream`
- Structured output: `output`

### Example
```typescript
import { generateText } from 'ai';

const result = await generateText({
  model: yourModel,
  prompt: '...',
  providerOptions: {
    gateway: {
      // AI Gateway options
    }
  }
});
```
```

```APIDOC
## AI SDK for Python (beta)

### Description
Use the AI SDK for Python (beta) to call AI Gateway with structured outputs. Install the SDK and set the `AI_GATEWAY_API_KEY` environment variable.

### Installation
```bash
uv add ai
```

### Usage
- Input: `ai.user_message(...)` and `ai.stream(...)`
- AI Gateway options: `ai.InferenceRequestParams(extra_body={"providerOptions": {"gateway": ...}})`
- Text output: `TextDelta.chunk`, or `stream.text` after consuming the stream
- Structured output: `output_type`

### Example
```python
import ai

result = ai.stream(
  model=your_model,
  messages=[ai.user_message('...')],
  extra_body={
    "providerOptions": {
      "gateway": {}
    }
  }
)
```
```

```APIDOC
## Chat Completions (OpenAI SDK)

### Description
Use the OpenAI SDK (TypeScript or Python) to call AI Gateway's Chat Completions endpoint with structured outputs.

### Installation
- TypeScript: `pnpm add openai`
- Python: `uv add openai`

### Usage
- Input: `messages`; a `system` or `developer` message
- AI Gateway options: `providerOptions.gateway` in the JSON body
- Text output: `choices[0].message.content`
- Structured output: `response_format`

### Example (TypeScript)
```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://ai-gateway.example.com',
  apiKey: process.env.AI_GATEWAY_API_KEY
});

const response = await client.chat.completions.create({
  model: 'your-model',
  messages: [{ role: 'user', content: '...' }],
  providerOptions: {
    gateway: {}
  }
});
```
```

```APIDOC
## Messages API (Anthropic SDK)

### Description
Use the Anthropic SDK (TypeScript or Python) to call AI Gateway's Messages API with structured outputs.

### Installation
- TypeScript: `pnpm add @anthropic-ai/sdk`
- Python: `uv add anthropic`

### Usage
- Input: `messages`; top-level `system`; required `max_tokens`
- AI Gateway options: `providerOptions.gateway` in the JSON body
- Text output: Text blocks in `content`
- Structured output: `output_config.format`

### Example (TypeScript)
```typescript
import Anthropic from '@anthropic-ai/sdk';

const client = new Anthropic({
  baseURL: 'https://ai-gateway.example.com',
  apiKey: process.env.AI_GATEWAY_API_KEY
});

const response = await client.messages.create({
  model: 'your-model',
  max_tokens: 1024,
  messages: [{ role: 'user', content: '...' }],
  providerOptions: {
    gateway: {}
  }
});
```
```

```APIDOC
## Responses / OpenResponses

### Description
Use the Responses or OpenResponses API to call AI Gateway with structured outputs. These share the `/v1/responses` endpoint.

### Usage
- Input: `input`; `instructions`
- AI Gateway options: `providerOptions.gateway` in the JSON body
- Text output: SDK `output_text`, or text blocks in raw `output` items
- Structured output: `text.format`

### Example (TypeScript)
```typescript
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://ai-gateway.example.com',
  apiKey: process.env.AI_GATEWAY_API_KEY
});

const response = await client.responses.create({
  model: 'your-model',
  input: '...',
  providerOptions: {
    gateway: {}
  }
});
```
```

```APIDOC
## cURL

### Description
Use cURL to call AI Gateway directly with HTTP requests. No SDK required.

### Usage
- Set `AI_GATEWAY_API_KEY` in your environment.
- Use the appropriate endpoint for your API format (Chat Completions, Messages, Responses).
- Include `providerOptions.gateway` in the JSON body for AI Gateway options.

### Example
```bash
curl -X POST https://ai-gateway.example.com/v1/chat/completions \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-model",
    "messages": [{"role": "user", "content": "..."}],
    "providerOptions": {
      "gateway": {}
    }
  }'
```
```

--------------------------------

### Install Harbor and export AI Gateway API key

Source: https://vercel.com/docs/ai-gateway/coding-agents/harbor?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Fcoding-agents%2Fqwen&source_site=vercel-docs&surface=html

Install or update Harbor 0.22.0 with uv, then export your AI Gateway API key for the examples on this page.

```bash
uv tool install --upgrade harbor
```

```bash
export AI_GATEWAY_API_KEY="your-ai-gateway-api-key"
```

--------------------------------

### Configure fx manually

Source: https://vercel.com/docs/ai-gateway/coding-agents/fx?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Fcoding-agents%2Fharbor&source_site=vercel-docs&surface=html

Manual setup workflow consisting of exporting the AI_GATEWAY_API_KEY environment variable, pinning the credential source in ~/.fx/settings.json, and confirming the status in a new terminal.

```bash
export AI_GATEWAY_API_KEY="your-ai-gateway-api-key"
```

```json
{
  "credential_source": "ai_gateway_api_key"
}
```

```bash
fx status
```

--------------------------------

### Set up fx with Vercel CLI

Source: https://vercel.com/docs/ai-gateway/coding-agents/fx?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Fcoding-agents%2Fharbor&source_site=vercel-docs&surface=html

Configures AI Gateway for fx automatically by exporting the API key in the shell startup file and pinning the credential source in ~/.fx/settings.json.

```bash
npx vercel ai-gateway setup --agent fx
```

--------------------------------

### Retrieve model example requests

Source: https://vercel.com/docs/ai-gateway/sdks-and-apis/openai-chat-completions?from=graph&relationship=inbound&source_path=%2Fdocs%2Fai-gateway%2Fsdks-and-apis%2Fopenai-chat-completions%2Fembeddings&source_site=vercel-docs&surface=html

Example requests to retrieve details about a specific model using the AI Gateway. The TypeScript and Python examples use the OpenAI SDK with the AI Gateway base URL and API key. The cURL example sends a GET request to the /models/{model} endpoint.

```typescript
import OpenAI from 'openai';

const openai = new OpenAI({
  apiKey: process.env.AI_GATEWAY_API_KEY,
  baseURL: 'https://ai-gateway.vercel.sh/v1',
});

const model = await openai.models.retrieve('anthropic/claude-opus-5');
console.log(model);
```

```python
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv('AI_GATEWAY_API_KEY'),
    base_url='https://ai-gateway.vercel.sh/v1'
)

model = client.models.retrieve('anthropic/claude-opus-5')
print(model)
```

```bash
curl -X GET "https://ai-gateway.vercel.sh/v1/models/anthropic/claude-opus-5" \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY"
```
Tokens:
Raw