Migration de OpenAI vers RouteAPI

Ce guide vous aide à migrer vos applications OpenAI existantes vers RouteAPI. Dans la plupart des cas, vous n’avez qu’à modifier l’URL de base et la clé API, le reste du code restant inchangé.

Pourquoi migrer vers RouteAPI

RouteAPI offre des capacités supplémentaires tout en maintenant la compatibilité avec OpenAI :

Accès unifié multi-fournisseurs - Utilisez Claude, Gemini, Azure, AWS Bedrock et d’autres modèles en plus d’OpenAI sans modifier le code
Gestion des coûts et contrôle budgétaire - Gestion centralisée de l’utilisation et des quotas pour plusieurs modèles afin d’éviter les dépassements
Observabilité améliorée - Journaux de requêtes unifiés, statistiques d’utilisation et surveillance des performances
Haute disponibilité et équilibrage de charge - Basculement automatique et distribution de charge multi-canaux
Autorisations et quotas flexibles - Créez des jetons et des limites indépendants pour différentes équipes, projets ou environnements

Évaluation de la difficulté de migration

Scénario	Modifications requises	Temps estimé
Utilisation du SDK OpenAI (Python/Node.js)	Modification de la configuration d’initialisation uniquement (2 lignes)	< 5 minutes
Utilisation de frameworks comme LangChain/LiteLLM	Modification des paramètres de configuration	< 10 minutes
Utilisation de clients comme Cursor/Claude Code	Mise à jour de l’URL de base et de la clé dans les paramètres	< 5 minutes
Requêtes HTTP directes	Modification de l’URL de la requête et de l’en-tête d’authentification	< 10 minutes

Modifications de configuration de base

Les étapes principales de la migration consistent à modifier deux éléments de configuration :

1. Modifier l’URL de base

Remplacez l’URL de base d’OpenAI par celle de RouteAPI :

# URL OpenAI d'origine
https://api.openai.com/v1

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

2. Remplacer la clé API

Utilisez un jeton RouteAPI au lieu de votre clé API OpenAI :

Connectez-vous à la console RouteAPI
Créez un nouveau jeton sur la page API Keys
Copiez et enregistrez le jeton (format : sk-...)

3. Gestion des variables d’environnement

Il est recommandé de gérer les identifiants à l’aide de variables d’environnement :

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

Conseil de sécurité : Ne commitez pas les jetons dans le contrôle de version. Utilisez .gitignore pour exclure les fichiers .env.

Migration du SDK Python

SDK OpenAI

Modifiez uniquement les paramètres base_url et api_key :

# Avant la migration - OpenAI
from openai import OpenAI

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

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

# Après la migration - RouteAPI
from openai import OpenAI
import os

client = OpenAI(
    api_key=os.environ["ROUTEAPI_KEY"],  # Utiliser le jeton RouteAPI
    base_url="https://api.routeapi.ai/v1",  # Pointer vers RouteAPI
)

response = client.chat.completions.create(
    model="gpt-4",  # Ou utiliser d'autres modèles comme claude-3-5-sonnet-20241022
    messages=[{"role": "user", "content": "Hello"}],
)

Modifications :

Ajout du paramètre base_url
Remplacement de api_key, de préférence à partir d’une variable d’environnement
Optionnel : changer model pour d’autres modèles supportés par RouteAPI

Configuration LangChain

# Avant la migration
from langchain_openai import ChatOpenAI

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

# Après la 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",
)

Configuration LiteLLM

# Avant la migration
import litellm

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

# Après la 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"}],
)

Migration du SDK Node.js

SDK OpenAI

Modifiez uniquement la configuration d’initialisation :

// Avant la migration - OpenAI
import OpenAI from 'openai';

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

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

// Après la migration - RouteAPI
import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: process.env.ROUTEAPI_KEY,  // Utiliser le jeton RouteAPI
  baseURL: 'https://api.routeapi.ai/v1',  // Pointer vers RouteAPI
});

const response = await client.chat.completions.create({
  model: 'gpt-4',  // Ou utiliser d'autres modèles comme claude-3-5-sonnet-20241022
  messages: [{ role: 'user', content: 'Hello' }],
});

Modifications :

Ajout du paramètre baseURL
Remplacement de apiKey, de préférence à partir d’une variable d’environnement
Optionnel : changer model pour d’autres modèles supportés par RouteAPI

Migration des outils clients

Si vous utilisez des clients IDE ou des agents de codage, mettez simplement à jour la configuration dans le panneau de paramètres :

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

Généralement, vous ne devez modifier que deux éléments :

Base URL / API Endpoint → https://api.routeapi.ai/v1
API Key → Votre jeton RouteAPI

Vérification de la compatibilité des paramètres

Paramètres inchangés

Les paramètres suivants se comportent de manière identique dans RouteAPI et OpenAI :

model - ID du modèle
messages - Tableau de messages de conversation
temperature - Contrôle de l’aléatoire (0-2)
max_tokens - Nombre maximum de jetons à générer
top_p - Paramètre d’échantillonnage nucleus
frequency_penalty - Pénalité de fréquence
presence_penalty - Pénalité de présence
stop - Séquences d’arrêt
stream - Activer ou non la réponse en streaming
user - Identifiant de l’utilisateur final
n - Nombre de complétions à retourner

Paramètres à noter

Le support de certains paramètres dépend des capacités du modèle sélectionné :

Paramètre	Description	Dépendance
`tools` / `tool_choice`	Appel d’outils (Function Calling)	Le modèle doit supporter l’appel d’outils
`response_format`	Sortie structurée (mode JSON)	Le modèle doit supporter la sortie JSON
`seed`	Graine d’échantillonnage déterministe	Supporté par certains modèles
`logprobs` / `top_logprobs`	Retourner les probabilités des jetons	Supporté par certains modèles

Recommandation : Pour les paramètres avancés, testez d’abord dans un environnement de test pour vérifier le support du modèle.

Gestion des valeurs zéro explicites

RouteAPI suit la convention Rule 5 :

Si le client transmet explicitement temperature=0, top_p=0 ou max_tokens=0, ces valeurs sont transmises telles quelles au modèle en amont
Elles ne sont pas traitées comme “non définies” et ignorées

Cela signifie que vous pouvez utiliser temperature=0 en toute confiance pour obtenir une sortie déterministe.

Noms de modèles

Interroger les modèles disponibles

Après la migration, vous pouvez accéder à davantage de modèles au-delà d’OpenAI. Utilisez l’endpoint /v1/models pour interroger :

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

Exemple de réponse :

{
  "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"
    }
    // ...plus de modèles
  ]
}

Utiliser les ID de modèles

Important : Utilisez le champ id du modèle dans les requêtes (par exemple, claude-3-5-sonnet-20241022), pas les noms d’affichage (par exemple, “Claude 3.5 Sonnet”).

# ✅ Correct - Utiliser l'ID du modèle
response = client.chat.completions.create(
    model="claude-3-5-sonnet-20241022",
    messages=[...],
)

# ❌ Incorrect - Utiliser le nom d'affichage
response = client.chat.completions.create(
    model="Claude 3.5 Sonnet",  # Provoquera une erreur
    messages=[...],
)

Changement de modèles inter-fournisseurs

Après la migration vers RouteAPI, vous pouvez facilement essayer des modèles de différents fournisseurs :

# Modèles OpenAI
model="gpt-4"
model="gpt-4o"

# Modèles Anthropic Claude
model="claude-3-5-sonnet-20241022"
model="claude-3-5-haiku-20241022"

# Modèles Google Gemini
model="gemini-2.0-flash-exp"
model="gemini-1.5-pro-002"

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

Il suffit de modifier le paramètre model, aucune autre modification de code n’est nécessaire.

Tests et validation

Liste de contrôle des tests

Après la migration, validez en utilisant la liste de contrôle suivante :

Test d’authentification - Confirmer que le jeton est valide et peut appeler /v1/models avec succès
Appels de base - Tester que chat.completions.create retourne normalement
Réponse en streaming - Si vous utilisez stream=True, vérifier que la sortie en streaming fonctionne
Appel d’outils - Si vous utilisez Function Calling, vérifier le flux d’appel d’outils
Gestion des erreurs - Tester les scénarios d’erreur comme le solde insuffisant, la limitation de débit, les paramètres invalides
Statistiques d’utilisation - Vérifier dans la console RouteAPI que les journaux d’utilisation sont correctement enregistrés

Dépannage courant

Code d’erreur	Causes courantes	Solution
401 Unauthorized	Jeton invalide ou manquant	Vérifier le format de l’en-tête `Authorization` : `Bearer sk-...`
402 Payment Required	Solde insuffisant ou quota épuisé	Se connecter à la console pour recharger ou augmenter le quota du jeton
404 Not Found	URL de base incorrecte ou faute de frappe dans le chemin	Confirmer que l’URL de base est `https://api.routeapi.ai/v1`
429 Too Many Requests	Limite de débit atteinte	Réduire la fréquence des requêtes ou contacter l’administrateur pour augmenter la limite
500 Internal Server Error	Problème avec le service du modèle en amont	Réessayer la requête ou basculer vers un modèle de secours

Conseils de débogage :

Utiliser cURL pour tester directement l’API, éliminant les problèmes de configuration du SDK
Vérifier les journaux d’utilisation de la console RouteAPI pour les messages d’erreur spécifiques
Comparer les différences de paramètres entre les requêtes OpenAI d’origine et RouteAPI

Exemple : Test avec 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"}]
  }'

Si la requête cURL réussit, la configuration du jeton et de l’URL de base est correcte, et le problème peut être au niveau du SDK.

Recommandations de migration progressive

Pour les environnements de production, une stratégie de migration progressive est recommandée :

1. Valider d’abord dans l’environnement de test

Tester complètement le code migré dans un environnement de développement ou de test
Vérifier les fonctionnalités principales, les cas limites et la gestion des erreurs
Comparer le contenu des réponses et les performances entre OpenAI et RouteAPI

2. Déploiement progressif

Utiliser des feature flags pour contrôler le changement d’URL de base
Activer RouteAPI pour un petit pourcentage de trafic d’abord
Observer les taux d’erreur, la latence et les retours utilisateurs

Exemple : Contrôler avec des variables d’environnement

import os

# Contrôler l'utilisation de RouteAPI via une variable d'environnement
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. Surveiller les journaux d’utilisation et les taux d’erreur

Après la migration, surveillez attentivement :

Taux de réussite des requêtes - Vérifier les erreurs 4xx/5xx anormales
Latence des réponses - Distribution de latence P50, P95, P99
Utilisation des jetons - Vérifier que la facturation correspond aux attentes
Disponibilité des modèles - Taux de réussite et latence pour différents modèles

Les enregistrements détaillés sont disponibles sur la page “Journaux d’utilisation” de la console RouteAPI.

4. Plan de rollback

Préparez un plan de rollback rapide vers OpenAI :

Conservez la clé API OpenAI d’origine, ne la supprimez pas immédiatement
Utilisez un centre de configuration ou des variables d’environnement pour gérer l’URL de base pour un changement rapide
Définissez des seuils d’alerte dans la surveillance pour déclencher automatiquement le rollback

# Exemple de rollback : Changer en modifiant simplement la variable d'environnement
# USE_ROUTEAPI=false -> Utiliser OpenAI
# USE_ROUTEAPI=true -> Utiliser RouteAPI

Recommandations d’optimisation post-migration

1. Tirer parti des capacités multi-modèles

RouteAPI supporte les modèles de plusieurs fournisseurs. Choisissez le modèle le plus adapté pour chaque scénario :

Scénarios sensibles à la latence - Utiliser gemini-2.0-flash-exp ou gpt-4o-mini
Tâches de raisonnement complexes - Utiliser claude-3-5-sonnet-20241022 ou gpt-4
Optimisation des coûts - Comparer le rapport coût-efficacité des différents modèles et choisir la solution optimale

2. Configurer des jetons indépendants

Créez des jetons séparés pour différents projets, environnements ou équipes :

Environnement de développement - Jeton à faible quota pour éviter les coûts excessifs lors des tests
Environnement de production - Jeton à quota élevé avec alertes configurées
Différentes équipes - Jetons indépendants pour l’attribution des coûts et l’audit

3. Activer les journaux de requêtes

Consultez les journaux de requêtes détaillés dans la console RouteAPI :

Modèle, utilisation des jetons et latence pour chaque requête
Causes d’erreur et traces de pile pour les requêtes échouées
Tendances d’utilisation et analyse des coûts

Ces journaux aident à optimiser les coûts et à résoudre les problèmes.

Obtenir de l’aide

Si vous rencontrez des problèmes pendant la migration :

Consultez la documentation de référence de l’API
Visitez la console RouteAPI pour vérifier les journaux d’utilisation
Contactez le support technique pour obtenir de l’aide

Documentation connexe :