Migrate from OpenAI SDK to TheRouter

Moving from the OpenAI API to TheRouter takes two changes: the base URL and the API key. Your existing OpenAI SDK code — Python, TypeScript, cURL — keeps working because TheRouter exposes an OpenAI-compatible /v1/chat/completions endpoint. This guide walks through the exact diff, model ID mapping, fallback configuration, streaming behavior, rollback path, and cost considerations.

We route OpenAI-compatible requests through configured providers and support provider/model routing and fallback where the live product path supports it. We provide unified billing and accounting surfaces where implemented. We do not claim zero downtime, universal model support, or guaranteed cheapest pricing.

Before/after code diff

The migration is a base URL and API key swap. Everything else — message format, streaming, function calling — stays the same.

Python (OpenAI SDK)

# Before: direct OpenAI
from openai import OpenAI

client = OpenAI(
    api_key="sk-your-openai-key",
    # base_url defaults to https://api.openai.com/v1
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
)

# After: through TheRouter
from openai import OpenAI

client = OpenAI(
    base_url="https://api.therouter.ai/v1",
    api_key="<THEROUTER_API_KEY>",
)

response = client.chat.completions.create(
    model="openai/gpt-4o",  # provider/model format
    messages=[{"role": "user", "content": "Hello"}],
)

TypeScript (OpenAI SDK)

// Before: direct OpenAI
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-your-openai-key',
});

// After: through TheRouter
import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://api.therouter.ai/v1',
  apiKey: '<THEROUTER_API_KEY>',
});

Environment variables

If your application reads OPENAI_BASE_URL and OPENAI_API_KEY from the environment, the migration is zero code changes:

# Before
export OPENAI_API_KEY="sk-your-openai-key"
# OPENAI_BASE_URL defaults to https://api.openai.com/v1

# After
export OPENAI_BASE_URL="https://api.therouter.ai/v1"
export OPENAI_API_KEY="<THEROUTER_API_KEY>"

The OpenAI Python SDK reads OPENAI_BASE_URL automatically when no base_url is passed to the constructor. Source: OpenAI Python SDK, OpenAI API reference, retrieved 2026-06-09.

cURL

# Before
curl https://api.openai.com/v1/chat/completions \
  -H "Authorization: Bearer sk-your-openai-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

# After
curl https://api.therouter.ai/v1/chat/completions \
  -H "Authorization: Bearer <THEROUTER_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

Model ID mapping

TheRouter uses provider/model-name format. When migrating from OpenAI, prefix model IDs with openai/. If you want to route to a different provider's model, use that provider's prefix instead.

Browse all available models on the Models page. For provider-specific setup details, see our guides to SiliconFlow, DeepSeek, and Alibaba Cloud Model Studio.

The key point: you are not locked into OpenAI models after migrating. The same base_url and api_key give you access to models from multiple providers through a single endpoint.

Add fallback without claiming zero downtime

TheRouter supports model fallback chains. Pass a models array instead of a single model to define the failover order. TheRouter tries the first model, then automatically retries the next when the route fails because of downtime, rate limits, or moderation refusal. Source: TheRouter Model Fallbacks, retrieved 2026-06-09.

import requests

response = requests.post(
    "https://api.therouter.ai/v1/chat/completions",
    headers={
        "Authorization": "Bearer <THEROUTER_API_KEY>",
        "Content-Type": "application/json",
    },
    json={
        "models": [
            "openai/gpt-4o",
            "anthropic/claude-sonnet-4.5",
            "deepseek/deepseek-v4-flash",
        ],
        "messages": [{"role": "user", "content": "Summarize this document."}],
    },
)

With the OpenAI SDK, keep your primary model and pass fallback candidates through extra_body:

const completion = await client.chat.completions.create({
  model: 'openai/gpt-4o',
  extra_body: {
    models: ['anthropic/claude-sonnet-4.5', 'deepseek/deepseek-v4-flash'],
  },
  messages: [{ role: 'user', content: 'Summarize this document.' }],
});

Fallback does not guarantee zero downtime. If all models in your chain are unavailable, the request fails. Build your error handling accordingly. For a deeper treatment of fallback patterns, retries, and cost guardrails, see our LLM API Fallback Routing Guide.

Streaming and response field behavior

Streaming works identically. Add stream: true (or stream=True in Python) — TheRouter forwards Server-Sent Events from the upstream provider.

stream = client.chat.completions.create(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Tell me a story"}],
    stream=True,
)
for chunk in stream:
    content = chunk.choices[0].delta.content or ""
    print(content, end="")

Response field gotchas to watch for:

• The model field in the response shows which model actually served the request. If a fallback fired, this differs from your requested model.
• Provider-specific response fields (such as system_fingerprint from OpenAI) are preserved only when verified in the provider's response. Do not rely on provider-specific fields being present across all routed models.
• Token usage fields (usage.prompt_tokens, usage.completion_tokens) are passed through from the upstream provider. Different providers may count tokens differently for the same input.

Rollback path

Rolling back to direct OpenAI is the reverse of the migration: restore the original base_url (or remove it to use the default) and restore your OpenAI API key.

Rollback checklist

1. Revert environment variables:

   export OPENAI_BASE_URL="https://api.openai.com/v1"  # or unset
   export OPENAI_API_KEY="sk-your-openai-key"
   

2. Revert model IDs: Change openai/gpt-4o back to gpt-4o. Remove provider prefixes.

3. Remove fallback arrays: Replace models: [...] with a single model field. Remove any extra_body.models.

4. Check for TheRouter-specific fields: If you added provider.order, provider.allow_fallbacks, or other TheRouter-specific request fields, remove them — OpenAI will reject unknown fields.

5. Verify your OpenAI API key is still active. If you rotated or revoked it during migration, generate a new one at platform.openai.com/api-keys.

6. Run your test suite. Confirm responses match expected format and latency.

The rollback is safe because the migration only changes the transport layer. Your prompts, message history, and application logic are untouched.

Cost considerations

TheRouter applies its own pricing on top of upstream provider costs. The total cost per request depends on which provider and model ultimately serves the request.

What changes:

• You pay TheRouter's rate instead of the direct provider rate. Check TheRouter pricing for current rates.
• Fallback chains may route to more expensive models. A request that falls back from a cheaper model to a more expensive one costs more than a direct call to the cheaper model.
• Unified billing means one invoice instead of separate accounts with each provider.

What does not change:

• Token counting is determined by the upstream model, not the routing layer.
• Prompt and completion lengths are unchanged.

We do not claim to be guaranteed cheapest. Compare TheRouter's rates against your current direct-provider costs before committing production traffic. Run both paths in parallel during a trial period if cost sensitivity is high.

Migration checklist

Use this checklist to track your migration:

• Get a TheRouter API key from therouter.ai
• Update base_url to https://api.therouter.ai/v1
• Update api_key to your TheRouter key
• Prefix model IDs with provider/ (e.g., openai/gpt-4o)
• Test a single request manually (cURL or SDK)
• Test streaming if your application uses it
• Add fallback models if you want multi-provider resilience
• Verify response fields your application depends on
• Run your existing test suite against TheRouter
• Monitor error rates and latency for the first 24 hours
• Keep your direct OpenAI API key active for rollback

FAQ

Do I need to change my OpenAI SDK version?

No. TheRouter works with the standard OpenAI SDK. You only change base_url and api_key. Source: TheRouter Quickstart, retrieved 2026-06-09.

Can I use TheRouter with tools that accept a custom base URL?

Yes. Coding tools like Cursor, Claude Code, and OpenCode that support a custom OpenAI-compatible base URL can point to TheRouter. See the Coding Tools Setup for specific configuration guides.

What happens if TheRouter is down?

Your requests fail. TheRouter does not claim zero downtime. Keep your direct provider credentials ready for rollback. Consider running a health check against TheRouter's endpoint before routing production traffic.

Can I migrate gradually?

Yes. Route a percentage of traffic through TheRouter while keeping the rest on direct OpenAI. Compare error rates, latency, and costs side by side. Increase the percentage when you are confident in the routing layer.

Does TheRouter support all OpenAI models?

TheRouter supports the models listed on its Models page. Not every OpenAI model may be available. Check the models page for current availability before migrating workloads that depend on specific models.

Where can I learn more about available providers?

See our provider guides: OpenAI-compatible API providers, Chinese OpenAI-compatible APIs, SiliconFlow guide, DeepSeek guide, and Alibaba Cloud Bailian guide.