# Migrating from OpenAI

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](/docs/instrument-specifications/current-instruments.md), 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](https://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

{% tabs %}
{% tab title="Python (OpenAI SDK)" %}

```python
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"}],
)
```

{% endtab %}

{% tab title="TypeScript (OpenAI SDK)" %}

```typescript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.thegrid.ai/v1",      // was: https://api.openai.com/v1
  apiKey: "your-grid-api-key",
});

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

{% endtab %}

{% tab title="curl" %}

```bash
curl https://api.thegrid.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_GRID_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-prime",
    "messages": [{"role": "user", "content": "Explain supply and demand in one paragraph."}],
    "stream": true
  }'
```

{% endtab %}
{% endtabs %}

## 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](/docs/instrument-specifications/current-instruments.md).

### 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](/docs/integrations-and-best-practices/routing-patterns.md) 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](/docs/instrument-specifications/current-instruments.md): `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](https://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](/docs/integrations-and-best-practices/routing-patterns.md).
2. **Handle retryable errors.** `429`, `500`, `503`, and `402` are retryable with exponential backoff. See [Troubleshooting](/docs/integrations-and-best-practices/troubleshooting.md) and [Best practices](/docs/integrations-and-best-practices/best-practices.md).

If you hit a wall, the [Troubleshooting](/docs/integrations-and-best-practices/troubleshooting.md) 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](/docs/integrations-and-best-practices/migrating-from-anthropic.md) for the details.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://thegrid.ai/docs/integrations-and-best-practices/migrating-from-openai.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.