Migrer d'OpenAI vers GLM : le guide pratique en 10 minutes

Vous avez une application branchée sur l'API OpenAI et l'envie d'essayer les modèles GLM — pour le prix, le contexte de 1 M de jetons, ou juste pour voir. Bonne nouvelle : Z.ai a bâti son API pour être compatible avec le SDK OpenAI. Pas de nouveau SDK, pas de réécriture : on change l'URL de base, la clé, le nom du modèle, et on teste. Ce guide condense l'essentiel en dix minutes de lecture ; pour la version exhaustive — Claude Code, Cline, CI/CD, checklist de production — notre guide de migration PDF de 19 pages est gratuit et sans inscription.

Pourquoi c'est (vraiment) deux lignes — et ce que ça ne couvre pas

La compatibilité OpenAI de Z.ai n'est pas un slogan : le format des messages (system/user/assistant), le streaming, les appels d'outils au schéma OpenAI et les réponses structurées fonctionnent tels quels. Vos prompts voyagent sans modification. Concrètement, dans 90 % des applications, la migration technique tient dans le constructeur du client : base_url et api_key, plus le nom du modèle dans chaque appel.

Ce que « deux lignes » ne couvre pas, et qu'il faut planifier quand même : le banc d'essai (rejouez 20 à 50 requêtes représentatives avant de basculer — les modèles gratuits comme glm-4.7-flash rendent l'exercice gratuit), les paramètres exclusifs de votre ancien fournisseur qui ne se transposent pas automatiquement, et la gestion des erreurs propre à Z.ai (section 1302/1305 plus bas). Une migration sérieuse, c'est deux lignes de code et une journée de rigueur.

Les trois endpoints — et lequel est le vôtre

La source de confusion numéro un chez Z.ai : il existe trois URL de base, et elles ne sont pas interchangeables. Frapper la mauvaise porte donne des erreurs d'autorisation ou une facturation inattendue, avec une clé pourtant valide.

La règle en une phrase : application → endpoint général ; outil de codage sous forfait → endpoint coding ; outil pensé pour Claude → endpoint anthropic. Et si une requête échoue avec une clé pourtant bonne, vérifiez d'abord que votre compte Z.ai a bien activé ce que cette porte exige (crédit prépayé pour la générale, abonnement pour la coding).

Python et Node.js : l'avant/après complet

Python

from openai import OpenAI

client = OpenAI(
  api_key=os.environ["OPENAI_API_KEY"]
)
r = client.chat.completions.create(
  model="gpt-5.6-terra",
  messages=[{"role":"user",
    "content":"Bonjour!"}]
)
print(r.choices[0].message.content)

from openai import OpenAI

client = OpenAI(
  api_key=os.environ["ZAI_API_KEY"],
  base_url="https://api.z.ai/api/paas/v4/"
)
r = client.chat.completions.create(
  model="glm-5.3",
  messages=[{"role":"user",
    "content":"Bonjour!"}]
)
print(r.choices[0].message.content)

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});
const r = await client.chat
  .completions.create({
    model: "gpt-5.6-terra",
    messages: [{ role: "user",
      content: "Bonjour!" }]
  });

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ZAI_API_KEY,
  baseURL: "https://api.z.ai/api/paas/v4/"
});
const r = await client.chat
  .completions.create({
    model: "glm-5.3",
    messages: [{ role: "user",
      content: "Bonjour!" }]
  });

Le streaming (stream=True / stream: true), les rôles système et les appels d'outils gardent exactement la même syntaxe. Côté noms de modèles : glm-5.3 pour le muscle, glm-4.7 pour le volume économique, glm-4.7-flash gratuit pour les tests — la gamme complète avec les prix est dans le guide. Si vous passez par LangChain, LlamaIndex ou le Vercel AI SDK, utilisez leur fournisseur « OpenAI compatible » avec cette URL de base — et lisez la section pièges ci-dessous, elle vous concerne doublement.

Le test de fumée cURL : validez avant de coder

Avant de modifier une seule ligne de votre application, validez la clé et l'endpoint depuis votre terminal (pas encore de clé ? l'inscription à Z.ai prend deux minutes). Si cet appel répond, votre code répondra ; s'il échoue, vous venez d'économiser une heure de débogage au mauvais endroit.

curl -X POST "https://api.z.ai/api/paas/v4/chat/completions" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -d '{
    "model": "glm-5.3",
    "messages": [
      {"role": "user", "content": "Réponds simplement : OK"}
    ]
  }'

Réponse attendue : un JSON avec choices[0].message.content contenant « OK » et un bloc usage avec le décompte de jetons — gardez ce bloc en tête, c'est lui qui alimentera votre suivi de coûts. Une erreur d'authentification ici signifie clé invalide ou mauvaise porte (revoyez la section endpoints) ; une erreur 404 signifie presque toujours le piège n°1 ci-dessous.

Les cinq pièges qui font perdre une heure

Compilés à partir des rapports publics et de nos propres migrations — si « ça ne marche pas », c'est presque toujours ici. 1. Le /v1 fantôme : beaucoup de clients « OpenAI compatibles » ajoutent d'office /v1/chat/completions à l'URL de base, ce qui donne …/paas/v4/v1/… → 404. Vérifiez l'URL réellement appelée dans vos journaux réseau. 2. La mauvaise porte : endpoint coding avec un compte sans forfait, ou l'inverse — relisez le tableau plus haut. 3. Les variables d'environnement figées : elles sont lues au démarrage du processus, une seule fois ; modifiez, puis redémarrez tout.

4. Le timeout trop court : les longues générations dépassent les timeouts par défaut de bien des clients HTTP — montez-le explicitement (120 s est un bon départ), sinon vous verrez des coupures « aléatoires » sur les grosses réponses seulement. 5. Le nom de modèle approximatif : c'est glm-5.3 exactement — minuscules, trait d'union, point. GLM-5.3 ou glm-5-3 ne passent pas. Les deux pièges bonus — paramètres exclusifs en clandestins et conclusions tirées d'un test unique — sont détaillés dans le chapitre migration du guide complet et dans le PDF.

Erreurs 1302, 1305 et 429 : le code de reprise à copier-coller

Z.ai ne publie pas de chiffres officiels de limites de débit : les plafonds s'ajustent dynamiquement selon la charge. Trois signaux à reconnaître : HTTP 429 (trop de requêtes), le code 1302 (« rate limit reached ») et le code 1305 (« service temporarily overloaded »). Les trois se traitent pareil : recul exponentiel, puis nouvel essai — jamais de martèlement en boucle serrée, qui empire votre cas.

import time, random
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI(api_key=CLE, base_url="https://api.z.ai/api/paas/v4/")

def appel_robuste(messages, modele="glm-5.3", essais=5):
    for tentative in range(essais):
        try:
            return client.chat.completions.create(
                model=modele, messages=messages, timeout=120)
        except (RateLimitError, APIStatusError) as e:
            code = getattr(e, "status_code", None)
            if code in (429, 500, 502, 503) or "1302" in str(e) or "1305" in str(e):
                time.sleep((2 ** (tentative + 1)) + random.uniform(0, 1))
                continue
            raise
    raise RuntimeError("Échec après plusieurs tentatives — prévoir un repli.")

Pour les chemins critiques, ajoutez un repli : un second modèle GLM moins demandé, ou votre ancien fournisseur en dernier recours — la compatibilité OpenAI rend ce filet trivial à écrire, puisque le même code parle aux deux. Et avant la mise en production, faites une heure de test à votre débit réel : ça vous en dira plus que n'importe quelle page de documentation, la nôtre comprise.

Foire aux questions

Sources : docs.z.ai (démarrage rapide, endpoints et codes d'erreur officiels). Prix vérifiés le 21 août 2026, endpoints revérifiés le 22 août 2026, en $US, sujets à changement sans préavis. Cet article contient des liens de parrainage Z.ai.