Vercel AI Gateway

Migrate from Vercel AI Gateway to NexLLM: update clients, authentication, model IDs, routing configuration, and observability.

Move your Vercel AI Gateway integration to NexLLM while keeping your application’s existing AI SDK, OpenAI-compatible, or Claude-native request format. This guide separates the connection changes from the gateway-specific behavior you need to review before production rollout.

You can continue using the Vercel AI SDK and hosting your application on Vercel. This migration changes the inference gateway, not necessarily your application framework or deployment platform.

Migration Overview

Integration	NexLLM configuration
OpenAI SDK	Set the base URL to `https://www.nexllm.ai/v1` and authenticate with a NexLLM key.
Vercel AI SDK	Create an explicit provider with `@ai-sdk/openai`; use `.chat()` for Chat Completions.
Chat Completions over HTTP	Send requests to `POST https://www.nexllm.ai/v1/chat/completions`.
Claude-native HTTP	Send requests to `POST https://www.nexllm.ai/v1/messages` with native authentication headers.
Responses API	Use `POST https://www.nexllm.ai/v1/responses` after verifying model compatibility.
Model selection	Use an exact model ID available to your NexLLM key.
Gateway-specific routing	Review and migrate the behavior separately; do not copy gateway options unchanged.

See API Reference and Authentication.

Prerequisites

Create a NexLLM API key

Create a dedicated key for the migration and store it in your application’s server-side secrets.Review its expiration, quota, model restrictions, IP allowlist, and group.See API Keys.

Confirm model access and endpoint compatibility

List the models available to your key. Check the selected model’s details for the endpoint and capabilities your application needs.See Models API and Model Details.

Inventory your existing integration

Identify client initialization, gateway credentials, model strings, provider options, custom headers, response metadata, and telemetry.Include background jobs, server routes, scheduled tasks, and local scripts.

Prepare acceptance tests and rollback

Preserve your current configuration until the migrated integration passes representative tests. Define rollback criteria before changing production traffic.

Quick Start for Claude Code Users

You can give Claude Code the following prompt from your repository. This is a suggested migration prompt, not an installable NexLLM migration skill.

Migrate this project's Vercel AI Gateway integration to NexLLM.

Use https://docs.nexllm.ai/ as the source of truth for NexLLM API
details. Start with https://docs.nexllm.ai/llms.txt.

1. Find @ai-sdk/gateway, gateway model strings, AI_GATEWAY_API_KEY,
   VERCEL_OIDC_TOKEN used for inference, ai-gateway.vercel.sh,
   providerOptions.gateway, and gateway response metadata.
2. Inventory required routing, fallback, caching, privacy, BYOK,
   service-tier, reasoning, and observability behavior before editing.
3. Use NEXLLM_API_KEY for the migrated requests.
4. For OpenAI-compatible clients, use:
   https://www.nexllm.ai/v1
5. For AI SDK Chat Completions, create an explicit @ai-sdk/openai
   provider and use its .chat(modelId) method.
6. For Claude-native requests, target:
   https://www.nexllm.ai/v1/messages
   Follow NexLLM's native authentication documentation and check
   how the installed SDK joins its base URL and request path.
7. Discover exact model IDs using GET /v1/models.
8. Do not assume Vercel gateway options or another platform's
   routing fields have a NexLLM equivalent.
9. Add model-discovery and inference smoke tests.
10. Report unresolved behavior gaps and rollback instructions.

Do not print or commit secrets. Ask before making billable requests,
changing production configuration, or deleting old credentials.

Migrating application API calls does not automatically configure Claude Code itself to use NexLLM. Treat the coding agent’s connection settings as a separate integration.

Step 1: Update Your Environment Variables

Replace the credential used by the migrated inference calls:

# Before
export AI_GATEWAY_API_KEY="YOUR_VERCEL_GATEWAY_KEY"

# After
export NEXLLM_API_KEY="YOUR_NEXLLM_API_KEY"

For the examples below, choose a model available to your key:

# Example only: confirm availability before running requests.
export NEXLLM_MODEL="gpt-4o"

# For Claude-native examples:
export NEXLLM_CLAUDE_MODEL="aws/claude-haiku-4-5"

NEXLLM_MODEL and NEXLLM_CLAUDE_MODEL are application configuration variables used in this guide, not special API parameters.

Replace the Gateway Authentication Fallback

Change application logic such as:

// Before
const apiKey =
  process.env.AI_GATEWAY_API_KEY ||
  process.env.VERCEL_OIDC_TOKEN;

to:

// After
const apiKey = process.env.NEXLLM_API_KEY;

if (!apiKey) {
  throw new Error("NEXLLM_API_KEY is required");
}

Use the NexLLM key for NexLLM requests rather than forwarding a Vercel gateway key or OIDC token. For OpenAI-compatible requests, authentication uses:

Authorization: Bearer YOUR_NEXLLM_API_KEY

See Authentication.

Do not remove VERCEL_OIDC_TOKEN, cloud credentials, or provider keys globally without checking their other uses. They may still be required by unrelated services or your rollback path.Keep NexLLM credentials server-side. Do not expose them through public environment variables or browser bundles.

Review the new key’s configured expiration rather than assuming it never expires. See API Keys.

Step 2: Update Your Client

Choose the example that matches your current request format. The examples use environment variables for model selection so that your application can use the exact ID verified in Step 5.

Vercel AI SDK

Keep the AI SDK, but replace implicit gateway model resolution with an explicit NexLLM-backed provider. Install a version of @ai-sdk/openai compatible with your project’s ai package. Avoid combining the gateway migration with an unrelated SDK major-version upgrade.

npm install @ai-sdk/openai

Before:

import { generateText } from "ai";

const { text } = await generateText({
  model: "openai/gpt-4o",
  prompt: "Write a short greeting.",
});

After:

import { createOpenAI } from "@ai-sdk/openai";
import { generateText } from "ai";

const apiKey = process.env.NEXLLM_API_KEY;
const modelId = process.env.NEXLLM_MODEL;

if (!apiKey || !modelId) {
  throw new Error("NEXLLM_API_KEY and NEXLLM_MODEL are required");
}

const nexllm = createOpenAI({
  baseURL: "https://www.nexllm.ai/v1",
  apiKey,
});

const { text } = await generateText({
  model: nexllm.chat(modelId),
  prompt: "Write a short greeting.",
});

console.log(text);

Use nexllm.chat(modelId) when targeting Chat Completions.The OpenAI provider’s default model factory can select the Responses API. Do not replace .chat(modelId) with nexllm(modelId) without deliberately reviewing the endpoint change.

Check the AI SDK OpenAI provider documentation for client-library behavior and NexLLM’s Chat Completions reference for the gateway endpoint. Search all call sites, including streamText, shared provider factories, and provider registries. Updating one client does not migrate independently configured clients.

OpenAI SDK and HTTP Clients

For an existing OpenAI client, replace:

https://ai-gateway.vercel.sh/v1

with:

https://www.nexllm.ai/v1

Then update the key and model ID.

Python
JavaScript
cURL

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://www.nexllm.ai/v1",
    api_key=os.environ["NEXLLM_API_KEY"],
)

response = client.chat.completions.create(
    model=os.environ["NEXLLM_MODEL"],
    messages=[
        {"role": "user", "content": "Write a short greeting."}
    ],
    max_tokens=64,
)

print(response.choices[0].message.content)

import OpenAI from "openai";

const apiKey = process.env.NEXLLM_API_KEY;
const model = process.env.NEXLLM_MODEL;

if (!apiKey || !model) {
  throw new Error("NEXLLM_API_KEY and NEXLLM_MODEL are required");
}

const client = new OpenAI({
  baseURL: "https://www.nexllm.ai/v1",
  apiKey,
});

const response = await client.chat.completions.create({
  model,
  messages: [
    { role: "user", content: "Write a short greeting." },
  ],
  max_tokens: 64,
});

console.log(response.choices[0]?.message?.content);

curl https://www.nexllm.ai/v1/chat/completions \
  -H "Authorization: Bearer $NEXLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": "Write a short greeting."}
    ],
    "max_tokens": 64
  }'

Replace gpt-4o if your selected model differs.

See Quickstart.

Anthropic SDK and Claude-Native Requests

You do not need to convert a Claude-native integration to Chat Completions solely to use NexLLM. NexLLM documents:

POST https://www.nexllm.ai/v1/messages

with these headers:

x-api-key: YOUR_NEXLLM_API_KEY
anthropic-version: 2023-06-01
Content-Type: application/json

See Native Authentication.

Python — Anthropic SDK
cURL

import os
from anthropic import Anthropic

client = Anthropic(
    # The SDK appends /v1/messages.
    base_url="https://www.nexllm.ai",
    api_key=os.environ["NEXLLM_API_KEY"],
)

message = client.messages.create(
    model=os.environ["NEXLLM_CLAUDE_MODEL"],
    max_tokens=64,
    messages=[
        {"role": "user", "content": "Write a short greeting."}
    ],
)

for block in message.content:
    if block.type == "text":
        print(block.text)

curl https://www.nexllm.ai/v1/messages \
  -H "x-api-key: $NEXLLM_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "aws/claude-haiku-4-5",
    "max_tokens": 64,
    "messages": [
      {"role": "user", "content": "Write a short greeting."}
    ]
  }'

An SDK base URL and a complete HTTP endpoint are not interchangeable.The Anthropic SDK example uses https://www.nexllm.ai because its Messages method supplies /v1/messages. The OpenAI SDK examples use https://www.nexllm.ai/v1.Confirm that the final request path contains exactly one /v1 segment.

Preserve your native content-block handling when keeping the Messages API. If you deliberately switch to Chat Completions, translate system instructions, tools, content blocks, streaming events, and response parsing separately.

Step 3: Review Vercel-Specific Headers and Metadata

Remove gateway-specific configuration from the NexLLM client after deciding how to preserve any behavior that depended on it. Do not indiscriminately delete application tracing headers or Vercel deployment configuration used elsewhere.

Request headers and authentication

Existing configuration	NexLLM migration action
Vercel key or OIDC token in `Authorization`	Replace with the NexLLM key for OpenAI-compatible requests.
`x-api-key` on Claude-native requests	Keep the native header, but replace its value with the NexLLM key.
`anthropic-version`	Retain the documented version header for Claude-native requests.
`http-referer` or `x-title`, if present	Remove assumptions that these populate NexLLM attribution. Preserve required app identity in your telemetry.
Gateway-specific project or deployment attribution	Keep required deployment context in application logs; verify any server-side header handling separately.

See Authentication.

Response metadata and headers

Existing dependency	Migration action
`providerMetadata.gateway`	Refactor consumers rather than expecting the same metadata object from another provider adapter.
Inline gateway cost fields	Review NexLLM Usage Logs for reported cost; update code that expects gateway-specific billing fields.
Gateway request or trace IDs	Retain application correlation IDs and record the Chat Completions response `id`.
Gateway rate-limit headers	Inspect actual NexLLM responses before retaining header-dependent scheduling logic.
Provider selection metadata	Verify what your selected endpoint returns; do not assume an identical field or routing trace exists.

See Chat Completions and Usage & Logs.

Step 4: Decompose Your Gateway Options

Review providerOptions.gateway and any related request fields before removing them. A connection change alone does not establish equivalent routing, caching, privacy, or timeout behavior.

The table below describes migration actions, not guaranteed one-to-one API replacements.“Verify separately” means this guide does not establish an equivalent NexLLM control from the referenced documentation. It does not necessarily mean the capability is unavailable.

Existing option or behavior	Recommended migration action
`order` — provider preference or fallback order	Preserve the required policy in application logic or verify a suitable NexLLM configuration.
`only` — allowed providers	Confirm that the selected model and channel configuration satisfy the restriction before sending traffic.
`sort: "cost"`	Select models and channel groups using applicable pricing; do not assume automatic cost optimization.
`sort: "ttft"`	Benchmark first-token latency and implement your selection policy explicitly.
`sort: "tps"`	Benchmark output throughput separately from first-token latency.
`models` — model fallback chain	Maintain an explicit, tested fallback policy if required.
`byok`	Verify a supported credential arrangement before migration. Do not forward provider secrets as arbitrary request fields.
`providerTimeouts`	Configure client deadlines and review retry behavior. A client timeout is not equivalent to per-provider failover.
`caching: "auto"`	Revalidate cache behavior for the target model and request format.
`zeroDataRetention`	Verify retention requirements before moving affected traffic. Do not treat removing the flag as preserving the policy.
`disallowPromptTraining`	Obtain confirmation of the required data-use policy rather than assuming equivalence.
`reasoning`	Translate only controls documented for the target model and endpoint.
`serviceTier`	Verify tier support and parameter semantics before sending a replacement field.

For NexLLM-specific access and pricing configuration, see Channel Groups and Pricing.

Use Channel Groups Deliberately

Each NexLLM key belongs to one channel group. The group controls model access and the pricing ratio applied to usage. Treat this as a key-level configuration decision, not a direct replacement for every per-request routing rule. If separate workloads need different configurations, consider dedicated keys and select the appropriate key in trusted server-side code. See Channel Groups.

Preserve Required Constraints

Before migrating a request that has provider or privacy restrictions:

Record the original requirement.
Identify how it will be enforced after migration.
Add a test or operational check.
Keep the old route until the replacement is verified.

Do not silently relax provider allowlists, output schemas, or privacy constraints to make requests succeed.

Do not copy routing.model.fallbacks, routing.provider.fallbacks, routing.model.sort, or model: "auto" from another gateway’s migration guide unless NexLLM separately documents and supports that configuration for your use case.

Test Fallbacks Without Duplicating Work

If your application implements fallback:

Distinguish retryable failures from invalid requests or credentials.
Limit attempts and overall elapsed time.
Avoid restarting after partial streamed output without an explicit policy.
Prevent duplicate tool execution.
Record which model was attempted and which one produced the accepted result.

Step 5: Update Model Identifiers

Retrieve the model IDs available to the key that will serve production traffic:

curl https://www.nexllm.ai/v1/models \
  -H "Authorization: Bearer $NEXLLM_API_KEY"

Use the exact data[].id value in inference requests. See Models API.

Example Model Mapping

These are candidates to verify, not unconditional replacements.

Existing Vercel model string	NexLLM candidate
`openai/gpt-4o`	`gpt-4o`
`google/gemini-2.5-flash`	`gemini-2.5-flash`
`anthropic/claude-haiku-4-5`	`aws/claude-haiku-4-5`, if the AWS-backed option meets your requirements
Any other model or version	Look up the exact available ID; do not invent a mapping.

Do not apply a universal “remove the provider prefix” rule.NexLLM documents both unprefixed and prefixed IDs. A mapping can also change the hosting provider, so matching the model family alone is insufficient.

Keep model-version changes separate from the gateway migration where practical. If the original model is unavailable, evaluate the substitute explicitly. The Models API establishes availability to your key. Check model details separately for endpoint compatibility and required capabilities. See Model Details.

Step 6: Reconnect Observability

NexLLM Usage Logs include request time, key name, model, timing, token consumption, and cost or quota deducted. See Usage & Logs.

Existing requirement	Migration approach
Request-level consumption and timing	Review NexLLM Usage Logs.
Application or environment attribution	Use descriptive key names and retain application metadata in your own logs.
Deployment-level tracing	Keep your existing tracing system connected to the migrated client.
Routing decisions and retry history	Record application-managed choices and attempts yourself.
Spend and access controls	Review NexLLM wallet usage and API key quota settings.
Gateway-specific provider metadata	Update dashboards and parsers to the fields actually available after migration.

See API Keys and Wallet.

Keep Application Correlation IDs

For each inference operation, consider recording:

Your application request ID.
Environment and application version.
Requested model.
Returned completion ID, where applicable.
Duration and outcome.
Retry or fallback attempt.
Token usage when returned.

Do not log credentials. Apply your existing controls to prompt and response content.

Preserve Your AI Gateway History

Before reducing access to the previous gateway:

Identify historical records required for operations or audits.
Check the export or retention mechanisms available to your account.
Preserve available logs, billing records, and routing configuration.
Verify that archived records remain readable.
Document the cutover time.

Do not assume historical Vercel records will automatically appear in NexLLM.

Step 7 (Optional): Evaluate the Responses API

NexLLM lists an OpenAI Responses-compatible endpoint:

POST https://www.nexllm.ai/v1/responses

See API Reference. If your application already uses Responses, evaluate that endpoint before converting the workflow to Chat Completions. Select a model whose details show Responses compatibility. The model browser supports filtering by endpoint type. See Model Details.

Minimal Compatibility Test

The following is a minimal Responses-format request pattern. Replace the placeholder with a compatible model available to your key:

curl https://www.nexllm.ai/v1/responses \
  -H "Authorization: Bearer $NEXLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "REPLACE_WITH_RESPONSES_COMPATIBLE_MODEL_ID",
    "input": "Write a short greeting."
  }'

The documented endpoint does not, by itself, establish feature parity with every gateway or provider.Verify response chaining, storage, reasoning, tools, structured output, multimodal inputs, and streaming for your selected model. Do not assume previous_response_id or provider-specific tools work identically.

For the AI SDK, select .responses(modelId) only as a deliberate endpoint choice. Retest response parsing and streaming behavior.

Why Migrate to NexLLM

Keep an OpenAI-Compatible Integration

Use the documented Chat Completions interface while accessing GPT, Claude, and Gemini models. See Quickstart.

Choose Model Access and Pricing Through Channel Groups

Select a group appropriate for your workload rather than assuming the previous gateway’s routing policy transfers unchanged. See Channel Groups.

Configure Purpose-Specific Credentials

Separate development, production, or workload credentials using NexLLM’s key controls. See API Keys.

Review Usage in One Dashboard

Use request logs and consumption statistics to evaluate the migration. See Usage & Logs.

Validate the benefits against your own acceptance criteria. This guide does not promise identical routing, automatic fallback, BYOK terms, retention policies, service tiers, or latency.

Troubleshooting

The model is not found

Call GET /v1/models using the application’s actual key.Check the exact identifier, the assigned channel group, and any model restrictions. Do not assume the previous gateway’s prefix is accepted.See Models API.

Authentication fails

Confirm the application sends a NexLLM key rather than an AI Gateway key, OIDC token, or upstream provider credential.Check secret availability in the running process, configured expiration, IP restrictions, and accidental whitespace.Use bearer authentication for the OpenAI-compatible examples and native headers for the Claude Messages example.See Authentication.

AI SDK requests still go through Vercel AI Gateway

Inspect every model construction site.Replace implicit gateway strings and gateway(...) instances with the configured NexLLM provider where migration is intended.Check shared registries, background jobs, streaming routes, and default provider configuration. Preserve intentional gateway usage elsewhere.

The AI SDK calls /responses unexpectedly

For Chat Completions, use:

model: nexllm.chat(modelId)

Do not rely on the default OpenAI provider factory to select your intended endpoint.

Claude-native requests return 404

Inspect the final URL.The complete Messages endpoint is:

https://www.nexllm.ai/v1/messages

For the Anthropic SDK example in this guide, use the host-only base URL:

https://www.nexllm.ai

Check for duplicated /v1 segments, missing path segments, or a client still pointing to the previous gateway.

Requests succeed but do not appear in NexLLM logs

Verify the actual destination, credential, account, and log time range.Check independently initialized clients and background workers. Avoid printing authorization headers while debugging.See Usage & Logs.

Provider routing or fallback no longer applies

Review the removed gateway options and the requirements behind them.A channel-group selection is not proof that a per-request provider allowlist, ordering rule, or fallback chain has been reproduced.Restore affected traffic to the previous route until required constraints are verified.

Cache behavior or cost changed

Compare model IDs, request formats, prompt structure, cache behavior, token accounting, and the applicable group ratio.Do not assume the original gateway’s automatic cache configuration transfers to NexLLM.See Pricing.

Connection checks fail

Test the documented Models endpoint first:

curl -i https://www.nexllm.ai/v1/models \
  -H "Authorization: Bearer $NEXLLM_API_KEY"

Then run a small inference request.A successful model-list request does not validate every inference feature. Do not invent a /health endpoint based on another gateway’s documentation.

Verification Checklist

Before completing the cutover:

Next Steps

API Reference

Review supported endpoint formats.

Available Models

Discover model IDs available to your key.

Channel Groups

Review access and pricing configuration.

Usage & Logs

Inspect requests after migration.

Feedback

When reporting migration issues, include:

The client package and version.
The endpoint and model ID.
The behavior expected from the previous integration.
A sanitized request example.
The HTTP status and error body.
The approximate request time.
A completion or request identifier, if available.

Remove credentials, private prompts, and personal data before sharing diagnostics.

​Migrate from Vercel AI Gateway to NexLLM: update clients, authentication, model IDs, routing configuration, and observability.

​Migration Overview

​Prerequisites

​Quick Start for Claude Code Users

​Step 1: Update Your Environment Variables

​Replace the Gateway Authentication Fallback

​Step 2: Update Your Client

​Vercel AI SDK

​OpenAI SDK and HTTP Clients

​Anthropic SDK and Claude-Native Requests

​Step 3: Review Vercel-Specific Headers and Metadata

​Step 4: Decompose Your Gateway Options

​Use Channel Groups Deliberately

​Preserve Required Constraints

​Test Fallbacks Without Duplicating Work

​Step 5: Update Model Identifiers

​Example Model Mapping

​Step 6: Reconnect Observability

​Keep Application Correlation IDs

​Preserve Your AI Gateway History

​Step 7 (Optional): Evaluate the Responses API

​Minimal Compatibility Test

​Why Migrate to NexLLM

​Keep an OpenAI-Compatible Integration

​Choose Model Access and Pricing Through Channel Groups

​Configure Purpose-Specific Credentials

​Review Usage in One Dashboard

​Troubleshooting

​Verification Checklist

​Next Steps

API Reference

Available Models

Channel Groups

Usage & Logs

​Feedback

Migrate from Vercel AI Gateway to NexLLM: update clients, authentication, model IDs, routing configuration, and observability.

Migration Overview

Prerequisites

Quick Start for Claude Code Users

Step 1: Update Your Environment Variables

Replace the Gateway Authentication Fallback

Step 2: Update Your Client

Vercel AI SDK

OpenAI SDK and HTTP Clients

Anthropic SDK and Claude-Native Requests

Step 3: Review Vercel-Specific Headers and Metadata

Step 4: Decompose Your Gateway Options

Use Channel Groups Deliberately

Preserve Required Constraints

Test Fallbacks Without Duplicating Work

Step 5: Update Model Identifiers

Example Model Mapping

Step 6: Reconnect Observability

Keep Application Correlation IDs

Preserve Your AI Gateway History

Step 7 (Optional): Evaluate the Responses API

Minimal Compatibility Test

Why Migrate to NexLLM

Keep an OpenAI-Compatible Integration

Choose Model Access and Pricing Through Channel Groups

Configure Purpose-Specific Credentials

Review Usage in One Dashboard

Troubleshooting

Verification Checklist

Next Steps

Feedback