Migrating from OpenAI to RouteAPI

This guide helps you migrate your existing OpenAI applications to RouteAPI. In most cases, you only need to modify the Base URL and API Key, keeping the rest of your code unchanged.

Why Migrate to RouteAPI

RouteAPI provides enhanced capabilities while maintaining OpenAI compatibility:

• Unified Multi-Provider Access - Use Claude, Gemini, Azure, AWS Bedrock, and more models alongside OpenAI without code changes
• Cost Management & Budget Control - Centralized usage and quota management across multiple models to prevent overspending
• Enhanced Observability - Unified request logs, usage statistics, and performance monitoring
• High Availability & Load Balancing - Automatic failover and multi-channel load distribution
• Flexible Permissions & Quotas - Create independent tokens and limits for different teams, projects, or environments

Migration Difficulty Assessment

Scenario	Changes Required	Estimated Time
Using OpenAI SDK (Python/Node.js)	Only modify initialization config (2 lines)	< 5 minutes
Using LangChain/LiteLLM frameworks	Modify configuration parameters	< 10 minutes
Using Cursor/Claude Code clients	Update Base URL and Key in settings	< 5 minutes
Direct HTTP requests	Modify request URL and auth header	< 10 minutes

Basic Configuration Changes

The core migration steps involve modifying two configuration items:

1. Modify Base URL

Replace OpenAI’s Base URL with RouteAPI:

# Original OpenAI URL
https://api.openai.com/v1

# RouteAPI URL
https://api.routeapi.ai/v1

2. Replace API Key

Use a RouteAPI Token instead of your OpenAI API Key:

1. Log in to the RouteAPI Console
2. Create a new token on the API Keys page
3. Copy and save the token (format: sk-...)

3. Environment Variable Management

It’s recommended to manage credentials using environment variables:

# .env file
ROUTEAPI_KEY=sk-your-routeapi-token

Security Tip: Don’t commit tokens to version control. Use .gitignore to exclude .env files.

Python SDK Migration

OpenAI SDK

Only modify the base_url and api_key parameters:

# Before Migration - OpenAI
from openai import OpenAI

client = OpenAI(
    api_key="sk-proj-...",  # OpenAI Key
)

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

# After Migration - RouteAPI
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],  # Use RouteAPI Token
    base_url="https://api.routeapi.ai/v1",  # Point to RouteAPI
)

response = client.chat.completions.create(
    model="gpt-4",  # Or use other models like claude-3-5-sonnet-20241022
    messages=[{"role": "user", "content": "Hello"}],
)

Changes:

• Add base_url parameter
• Replace api_key, preferably read from environment variable
• Optional: Switch model to other RouteAPI-supported models

LangChain Configuration

# Before Migration
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model="gpt-4",
    openai_api_key="sk-proj-...",
)

# After Migration
from langchain_openai import ChatOpenAI
import os

llm = ChatOpenAI(
    model="gpt-4",
    openai_api_key=os.environ["ROUTEAPI_KEY"],
    openai_api_base="https://api.routeapi.ai/v1",
)

LiteLLM Configuration

# Before Migration
import litellm

response = litellm.completion(
    model="gpt-4",
    api_key="sk-proj-...",
    messages=[{"role": "user", "content": "Hello"}],
)

# After Migration
import litellm
import os

response = litellm.completion(
    model="gpt-4",
    api_key=os.environ["ROUTEAPI_KEY"],
    api_base="https://api.routeapi.ai/v1",
    messages=[{"role": "user", "content": "Hello"}],
)

Node.js SDK Migration

OpenAI SDK

Only modify the initialization configuration:

// Before Migration - OpenAI
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'sk-proj-...',  // OpenAI Key
});

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

// After Migration - RouteAPI
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ROUTEAPI_KEY,  // Use RouteAPI Token
  baseURL: 'https://api.routeapi.ai/v1',  // Point to RouteAPI
});

const response = await client.chat.completions.create({
  model: 'gpt-4',  // Or use other models like claude-3-5-sonnet-20241022
  messages: [{ role: 'user', content: 'Hello' }],
});

Changes:

• Add baseURL parameter
• Replace apiKey, preferably read from environment variable
• Optional: Switch model to other RouteAPI-supported models

Client Tools Migration

If you’re using IDE clients or coding agents, simply update the configuration in the settings panel:

Client	Configuration Guide
Cursor	Cursor Configuration
Claude Code	Claude Code Configuration
OpenCode	OpenCode Configuration
Codex (oh-my-codex)	Codex Configuration

Typically, you only need to modify two items:

1. Base URL / API Endpoint → https://api.routeapi.ai/v1
2. API Key → Your RouteAPI Token

Parameter Compatibility Check

Parameters That Remain Unchanged

The following parameters behave identically in RouteAPI as in OpenAI:

• model - Model ID
• messages - Conversation message array
• temperature - Randomness control (0-2)
• max_tokens - Maximum tokens to generate
• top_p - Nucleus sampling parameter
• frequency_penalty - Frequency penalty
• presence_penalty - Presence penalty
• stop - Stop sequences
• stream - Whether to enable streaming response
• user - End-user identifier
• n - Number of completions to return

Parameters to Note

Support for certain parameters depends on the selected model’s capabilities:

Parameter	Description	Dependency
tools / tool_choice	Tool calling (Function Calling)	Model must support tool calling
response_format	Structured output (JSON mode)	Model must support JSON output
seed	Deterministic sampling seed	Supported by some models
logprobs / top_logprobs	Return token probabilities	Supported by some models

Recommendation: For advanced parameters, test in a development environment first to verify model support.

Explicit Zero Value Handling

RouteAPI follows Rule 5 convention:

• If the client explicitly passes temperature=0, top_p=0, or max_tokens=0, these values are forwarded as-is to the upstream model
• They are not treated as “unset” and discarded

This means you can confidently use temperature=0 to get deterministic output.

Model Names

Query Available Models

After migration, you can access more models beyond OpenAI. Use the /v1/models endpoint to query:

curl https://api.routeapi.ai/v1/models \
  -H "Authorization: Bearer $ROUTEAPI_KEY"

Example response:

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4",
      "object": "model",
      "created": 1677610602,
      "owned_by": "openai"
    },
    {
      "id": "claude-3-5-sonnet-20241022",
      "object": "model",
      "created": 1677610602,
      "owned_by": "anthropic"
    },
    {
      "id": "gemini-2.0-flash-exp",
      "object": "model",
      "created": 1677610602,
      "owned_by": "google"
    }
    // ...more models
  ]
}

Use Model IDs

Important: Use the model’s id field (e.g., claude-3-5-sonnet-20241022) in requests, not display names (e.g., “Claude 3.5 Sonnet”).

# ✅ Correct - Use model ID
response = client.chat.completions.create(
    model="claude-3-5-sonnet-20241022",
    messages=[...],
)

# ❌ Wrong - Use display name
response = client.chat.completions.create(
    model="Claude 3.5 Sonnet",  # Will error
    messages=[...],
)

Cross-Provider Model Switching

After migrating to RouteAPI, you can easily try models from different providers:

# OpenAI models
model="gpt-4"
model="gpt-4o"

# Anthropic Claude models
model="claude-3-5-sonnet-20241022"
model="claude-3-5-haiku-20241022"

# Google Gemini models
model="gemini-2.0-flash-exp"
model="gemini-1.5-pro-002"

# AWS Bedrock models (via RouteAPI)
model="anthropic.claude-3-5-sonnet-20241022-v2:0"

Just modify the model parameter; no other code changes needed.

Testing and Validation

Testing Checklist

After migration, validate using the following checklist:

• Authentication Test - Confirm token is valid and can successfully call /v1/models
• Basic Calls - Test that chat.completions.create returns normally
• Streaming Response - If using stream=True, verify streaming output works
• Tool Calling - If using Function Calling, verify tool calling flow
• Error Handling - Test error scenarios like insufficient balance, rate limiting, invalid parameters
• Usage Statistics - Check usage logs in RouteAPI console for correct recording

Common Troubleshooting

Error Code	Common Causes	Solution
401 Unauthorized	Invalid or missing token	Check Authorization header format: Bearer sk-...
402 Payment Required	Insufficient balance or quota exhausted	Log into console to recharge or increase token quota
404 Not Found	Wrong Base URL or path typo	Confirm Base URL is https://api.routeapi.ai/v1
429 Too Many Requests	Rate limit triggered	Reduce request frequency or contact admin to increase limit
500 Internal Server Error	Upstream model service issue	Retry request or switch to backup model

Debugging Tips:

• Use cURL to test the API directly, eliminating SDK configuration issues
• Check RouteAPI console usage logs for specific error messages
• Compare parameter differences between original OpenAI and RouteAPI requests

Example: Testing with cURL

curl https://api.routeapi.ai/v1/chat/completions \
  -H "Authorization: Bearer $ROUTEAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

If the cURL request succeeds, the token and Base URL configuration are correct, and the issue may be at the SDK layer.

Staged Migration Recommendations

For production environments, a progressive migration strategy is recommended:

1. Validate in Test Environment First

• Fully test migrated code in development or test environment
• Verify core functionality, edge cases, and error handling
• Compare response content and performance between OpenAI and RouteAPI

2. Gradual Rollout

• Use feature flags to control Base URL switching
• Enable RouteAPI for a small percentage of traffic first
• Monitor error rates, latency, and user feedback

Example: Control with environment variables

import os

# Control whether to use RouteAPI via environment variable
USE_ROUTEAPI = os.getenv("USE_ROUTEAPI", "false").lower() == "true"

if USE_ROUTEAPI:
    base_url = "https://api.routeapi.ai/v1"
    api_key = os.environ["ROUTEAPI_KEY"]
else:
    base_url = "https://api.openai.com/v1"
    api_key = os.environ["OPENAI_API_KEY"]

client = OpenAI(api_key=api_key, base_url=base_url)

3. Monitor Usage Logs and Error Rates

After migration, closely monitor:

• Request Success Rate - Check for abnormal 4xx/5xx errors
• Response Latency - P50, P95, P99 latency distribution
• Token Usage - Verify billing matches expectations
• Model Availability - Success rates and latency for different models

Detailed records are available on the “Usage Logs” page in the RouteAPI console.

4. Rollback Plan

Prepare a quick rollback plan to OpenAI:

• Keep original OpenAI API Key, don’t delete immediately
• Use configuration center or environment variables to manage Base URL for quick switching
• Set alert thresholds in monitoring to automatically trigger rollback

# Rollback example: Switch by modifying environment variable
# USE_ROUTEAPI=false -> Use OpenAI
# USE_ROUTEAPI=true -> Use RouteAPI

Post-Migration Optimization Recommendations

1. Leverage Multi-Model Capabilities

RouteAPI supports models from multiple providers. Choose the most suitable model for each scenario:

• Latency-Sensitive Scenarios - Use gemini-2.0-flash-exp or gpt-4o-mini
• Complex Reasoning Tasks - Use claude-3-5-sonnet-20241022 or gpt-4
• Cost Optimization - Compare cost-effectiveness of different models and choose the optimal solution

2. Set Up Independent Tokens

Create separate tokens for different projects, environments, or teams:

• Development Environment - Low-quota token to avoid excessive testing costs
• Production Environment - High-quota token with alerts configured
• Different Teams - Independent tokens for cost attribution and auditing

3. Enable Request Logging

View detailed request logs in the RouteAPI console:

• Model, token usage, and latency for each request
• Error request causes and stack traces
• Usage trends and cost analysis

These logs help optimize costs and troubleshoot issues.

Getting Help

If you encounter issues during migration:

• Review the API Reference Documentation
• Visit the RouteAPI Console to check usage logs
• Contact technical support for assistance

---

Related Documentation:

• API Overview
• Authentication
• Chat Completions API
• OpenAI SDK Integration