Migrating from OpenAI

Switch from the OpenAI API to The Grid by changing three values in your existing code, base URL, API key, and model string. Your SDK, request body, and response shape stay the same.

Most teams switch to The Grid in three lines of code. Our Consumption API is OpenAI-compatible, so the SDK, request body, response shape, and streaming behavior you already know all work. The model name becomes an instrument string like text-prime and the rest of your code stays put.

This section covers how to make the switch cleanly, how to route workloads across our nine instruments, and what to do when something goes wrong.

Two things change for integrators: base URL and model name

If your code calls the OpenAI API today, switching to The Grid takes three changes:

1. Base URL. Point at https://api.thegrid.ai/v1 instead of https://api.openai.com/v1.

2. API key. Use a Grid API key from app.thegrid.ai/profile/api-keys.

3. Model string. Replace the OpenAI model name with a Grid instrument like Text Prime, Code Max, or Agent Prime.

That's the entire migration. The SDK stays the same. chat.completions.create() stays the same. Streaming, tool calling, structured outputs, and standard generation parameters (temperature, top_p, max_tokens, stop) all behave the same way.

Code examples

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
    base_url="https://api.thegrid.ai/v1",   # was: https://api.openai.com/v1
    api_key="your-grid-api-key",             # from app.thegrid.ai/profile/api-keys
)

response = client.chat.completions.create(
    model="text-prime",                       # was: gpt-5.2
    messages=[{"role": "user", "content": "Hello"}],
)

TypeScript (OpenAI SDK)

curl

Model mapping

These are starting points. The model parameter is just a string, so you can mix instruments freely within the same application. Use text-standard for classification, text-max for analysis, and code-prime for code review, all in the same codebase. The full list lives in Current instruments.

General text and reasoning

What you use today	Recommended Grid instrument	Typical use cases
GPT-5.4, o3, o1	text-max	Deep reasoning, extended thinking, complex multi-step prompts, math and logic
GPT-5.2, GPT-4.1	text-prime	Everyday workhorse: writing, summarization, Q&A, analysis
GPT-4.1-mini, GPT-4.1-nano	text-standard	High-throughput, classification, extraction, simple generation

Code generation (preview)

What you use today	Recommended Grid instrument	Typical use cases
GPT-5.2-Codex, GPT-5.4 (for code)	code-max	Complex architecture, multi-file refactors, deep debugging
GPT-4.1, GPT-5.2 (for code)	code-prime	Daily coding: completion, review, standard debugging
GPT-4.1-mini (for code)	code-standard	Autocomplete, linting, fast inline suggestions

Agent tool calling (preview)

What you use today	Recommended Grid instrument	Typical use cases
GPT-5.4 (agent use)	agent-max	Autonomous multi-step tasks, deep tool chains, long-horizon agents
GPT-4.1, GPT-5.2 (agent use)	agent-prime	Reliable multi-step tool use, standard agent loops
GPT-4.1-mini (agent use)	agent-standard	Fast tool calls, simple loops, high-throughput orchestration

If you're not sure where to start, default to Text Prime. It covers most everyday work. You can switch tiers per-request as evidence accumulates. See Routing patterns for how to allocate workloads honestly.

Three things stay the same: SDK, request shape, response shape

• The SDK. Keep openai (Python) or openai (Node). No new dependency.

• The request shape. Messages array, temperature, top_p, max_tokens, stop, stream, tools, tool_choice, response_format. All the same.

• The response shape. chat.completion and chat.completion.chunk objects with the same fields.

• Streaming. Server-sent events with the same chunk format.

• Tool calling. Function definitions and tool_calls work the same way.

• Structured outputs. JSON mode and JSON schema work the same way.

Four real differences from OpenAI

• Instrument strings, not model names. The model parameter takes one of our nine instruments: text-prime, code-max, and so on. Passing gpt-5.2 returns a 404.

• Pricing is market-driven. Prices come from a real order book, per million tokens, and move with supply and demand. Live pricing is in the app at thegrid.ai/pricing.

• Balance management. If your USD balance hits zero mid-request, you get a 402 error. Set up Auto-Reload in the dashboard to keep your credits topped up automatically.

• What's not on The Grid. The Assistants API, file uploads, DALL-E, Whisper, TTS, embeddings, fine-tuning, and the Batch API are OpenAI products, not part of the inference contract. We cover chat completions with tool calling and structured outputs. If you use those OpenAI-only features, leave those calls pointed at OpenAI and route chat completions through The Grid.

After the switch, route honestly and handle retries

Once requests are flowing, two things matter:

1. Route honestly. Don't run everything on Max. The bulk of the savings comes from putting throughput-heavy and structured workloads on Standard, daily work on Prime, and reserving Max for tasks where getting it wrong has real consequences. See Routing patterns.

2. Handle retryable errors. 429, 500, 503, and 402 are retryable with exponential backoff. See Troubleshooting and Best practices.

If you hit a wall, the Troubleshooting page has the common errors and fixes.

Anthropic SDK as an alternative path

If you maintain code that uses the Anthropic SDK alongside OpenAI, you don't need to consolidate on a single SDK to use The Grid. The Messages API beta endpoint at https://messages-beta.api.thegrid.ai/v1 accepts Anthropic-format requests against the same instruments and the same balance. See Migrating from Anthropic for the details.