Vercel AI Gateway11 min readUpdated 2026-04-09

Migrating from Vercel AI Gateway to Phaseo Gateway

Replace Vercel AI Gateway routing with Phaseo Gateway while preserving app behavior, with examples for AI SDK/OpenAI-style integrations and rollout validation.

Prerequisites

Current Vercel AI Gateway base URL and key configuration.
`PHASEO_API_KEY` added to local/dev/staging/prod environments.
A short list of critical prompts or endpoints for parity tests.

1) Document your current gateway boundary

Find the single place where your app creates model providers or API clients. That is the preferred migration point.

Capture existing retry, timeout, and fallback behavior so migration stays behaviorally equivalent.

Checklist

Locate provider/client factory.
List model IDs currently used in production.
Record retry and timeout defaults.

2) Swap gateway endpoint and key

For OpenAI-compatible client paths, this is usually a base URL + key replacement only.

If your app has both server and edge runtimes, update both env scopes.

Before (gateway endpoint)

import OpenAI from "openai";

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

After (Phaseo gateway endpoint)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.PHASEO_API_KEY,
  baseURL: "https://api.phaseo.app/v1",
});

Vercel AI SDK style provider switch

import { generateText } from "ai";
import { createPhaseo } from "@phaseo/ai-sdk-provider";

const phaseo = createPhaseo({
  apiKey: process.env.PHASEO_API_KEY,
  baseURL: "https://api.phaseo.app/v1",
});

const { text } = await generateText({
  model: phaseo("openai/gpt-4.1-mini"),
  prompt: "Generate a migration checklist.",
});

Screenshot checkpoints

Vercel project environment settings

Capture the Vercel environment variables panel showing the new key name.

Suggested asset path: /migrate/vercel-ai-gateway/01-vercel-env.png

3) Confirm behavior parity

Run the same prompt set against old and new paths, then compare latency, output format, and token usage.

Keep any gateway-specific metadata adaptation in one adapter so callers stay unchanged.

Checklist

Verify tool-calling paths if your app depends on them.
Verify streaming chunks are handled exactly as before.
Confirm application-level error mapping is unchanged.

4) Release plan for low risk

Ship behind a feature flag or traffic percentage to support rapid rollback.

Monitor live metrics and keep both configs available for one release window.

Screenshot checkpoints

Feature flag / canary control

Capture your rollout control surface (flag dashboard, config panel, or deployment variable).

Suggested asset path: /migrate/vercel-ai-gateway/02-rollout-flag.png

Validation Steps

curl -s "https://api.phaseo.app/v1/health"
Run your app's primary text generation integration test.
Run one app-level streaming test in staging.
Compare old/new outputs for your top 10 prompts before full rollout.

FAQ

Do I need to replace the AI SDK?

No. Most migrations keep the same SDK and only swap provider configuration to point at Phaseo.

What if my app uses edge runtimes and server runtimes?

Apply the env var/key update in both runtime scopes and validate both execution paths before promoting.

Need a custom migration diff?

Use the interactive assistant for before/after snippets tailored to your current SDK and language.

Open Migration Assistant

1) Document your current gateway boundary

Find the single place where your app creates model providers or API clients. That is the preferred migration point.

Capture existing retry, timeout, and fallback behavior so migration stays behaviorally equivalent.

Checklist

Locate provider/client factory.
List model IDs currently used in production.
Record retry and timeout defaults.

2) Swap gateway endpoint and key

For OpenAI-compatible client paths, this is usually a base URL + key replacement only.

If your app has both server and edge runtimes, update both env scopes.

Before (gateway endpoint)

import OpenAI from "openai";

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

After (Phaseo gateway endpoint)

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.PHASEO_API_KEY,
  baseURL: "https://api.phaseo.app/v1",
});

Vercel AI SDK style provider switch

import { generateText } from "ai";
import { createPhaseo } from "@phaseo/ai-sdk-provider";

const phaseo = createPhaseo({
  apiKey: process.env.PHASEO_API_KEY,
  baseURL: "https://api.phaseo.app/v1",
});

const { text } = await generateText({
  model: phaseo("openai/gpt-4.1-mini"),
  prompt: "Generate a migration checklist.",
});

Screenshot checkpoints

Vercel project environment settings

Capture the Vercel environment variables panel showing the new key name.

Suggested asset path: /migrate/vercel-ai-gateway/01-vercel-env.png

3) Confirm behavior parity

Run the same prompt set against old and new paths, then compare latency, output format, and token usage.

Keep any gateway-specific metadata adaptation in one adapter so callers stay unchanged.

Checklist

Verify tool-calling paths if your app depends on them.
Verify streaming chunks are handled exactly as before.
Confirm application-level error mapping is unchanged.

4) Release plan for low risk

Ship behind a feature flag or traffic percentage to support rapid rollback.

Monitor live metrics and keep both configs available for one release window.

Screenshot checkpoints

Feature flag / canary control

Capture your rollout control surface (flag dashboard, config panel, or deployment variable).

Suggested asset path: /migrate/vercel-ai-gateway/02-rollout-flag.png