---
title: "Migrate from OpenAI SDK"
description: "Compare the existing OpenAI SDK integration with an AI SDK version of the same request, including native model strings and Gateway response metadata."
canonical_url: "https://vercel.com/academy/ai-gateway/migrate-from-openai-sdk"
md_url: "https://vercel.com/academy/ai-gateway/migrate-from-openai-sdk.md"
docset_id: "vercel-academy"
doc_version: "1.0"
last_updated: "2026-08-08T23:27:13.271Z"
content_type: "lesson"
course: "ai-gateway"
course_title: "Using AI Gateway in Production"
prerequisites:  []
---

<agent-instructions>
Vercel Academy — structured learning, not reference docs.
Lessons are sequenced.
Adapt commands to the human's actual environment (OS, package manager, shell, editor) — detect from project context or ask, don't assume.
The lesson shows one path; if the human's project diverges, adapt concepts to their setup.
Preserve the learning goal over literal steps.
Quizzes are pedagogical — engage, don't spoil.
Quiz answers are included for your reference.
</agent-instructions>

# Migrate from OpenAI SDK

# How Do I Migrate Off the Raw OpenAI SDK?

You can migrate in two independent stages. First, point the existing OpenAI client at AI Gateway. That change is production-ready on its own.

Later, migrate individual calls to the AI SDK when its typed Gateway options and metadata access are useful to your application.

\*\*Note: Quick Answer\*\*

Start by pointing the existing OpenAI client at `https://ai-gateway.vercel.sh/v1` with a Gateway key and creator-prefixed model names. Migrate individual calls to AI SDK helpers such as `generateText` when you want typed Gateway options and direct access to routing or cost metadata. The second step is optional.

## Outcome

Run the same feature with the OpenAI SDK and the AI SDK, then compare the request code and available metadata.

## Fast Track

1. Start with lesson 1.2's `scripts/existing-stack.ts`: base URL, key, and model prefix
2. Write the AI SDK twin: `scripts/migrated-stack.ts`
3. Run both; compare the same feature behavior and what the code *around* each answer looks like

## Hands-on exercise

Lesson 1.2 configured the existing client with `baseURL`, `apiKey`, and creator-prefixed model names. That version can remain in production.

Now build the AI SDK version beside it:

- A `scripts/migrated-stack.ts` that does exactly what `existing-stack.ts` does, in the AI SDK
- Same two models, same order prompt
- Print the request cost from `providerMetadata.gateway.cost`

Put the files side by side and compare them. Both versions have a similarly short basic request path. The AI SDK becomes more useful when you add Gateway features: fallbacks and other options are first-class typed fields under `providerOptions.gateway`, and response metadata is directly available.

## Try It

```bash
pnpm existing-stack && pnpm migrated-stack
```

```
[openai/gpt-5.4-mini via OpenAI SDK]
Order up: two Al Pastor Meteors, one Agua Fresca. That'll be $12.00.

[openai/gpt-5.4-mini via AI SDK]
Order up: two Al Pastor Meteors, one Agua Fresca. That'll be $12.00.
Cost: $0.0000714
```

Both scripts perform the same feature. The AI SDK version also exposes the Gateway cost metadata directly.

Two issues you may encounter:

**Your codebase wraps the OpenAI SDK in a service layer.** A service wrapper makes incremental migration straightforward. Update one method at a time without changing its callers.

**You use an OpenAI feature and aren't sure it survives the move.** Streaming, tool calls, structured outputs, and embeddings all pass through the compat endpoint, and all have AI SDK equivalents. Check the compatibility documentation for that feature before migrating it.

## Commit

```bash
git commit -m "feat(migration): add AI SDK twin of the legacy order flow"
```

## Done-When

- [ ] Both scripts produce the same feature behavior
- [ ] You can name the two things move two buys (native gateway options, metadata access) without expecting separate model calls to produce identical wording
- [ ] You know which of your own code moves first (the wrapper insides, if you have one)

## Solution

```ts filename="scripts/migrated-stack.ts"
import { generateText } from "ai";

const order =
  "Take this order and confirm it back with a total: two Al Pastor Meteors " +
  "($4.50 each) and one agua fresca ($3.00).";

for (const model of ["openai/gpt-5.4-mini", "anthropic/claude-sonnet-4.6"]) {
  const result = await generateText({ model, prompt: order });
  const cost = result.finalStep.providerMetadata?.gateway?.cost;

  console.log(`[${model} via AI SDK]`);
  console.log(result.text.trim());
  console.log(`Cost: $${cost}`);
  console.log();
}
```

Compared with `existing-stack.ts`, this version removes client construction and reads Gateway metadata from the result. Migrate the remaining calls when those options improve the application.

## Related Questions

- [Will AI Gateway work with my existing AI stack?](/ai-gateway/stay-reliable/existing-ai-stack)
- [Why use AI Gateway instead of calling providers directly?](/ai-gateway/stay-reliable/why-ai-gateway)
- [How do I switch models without rewriting my app?](/ai-gateway/stay-reliable/switch-models)


---

[Full course index](/academy/llms.txt) · [Sitemap](/academy/sitemap.md)