GLM-5 est la nouvelle génération de modèle généraliste de la famille GLM de Zhipu. Trois questions reviennent souvent : où trouver la clé, quelle Base URL utiliser, et peut-on réutiliser le SDK OpenAI existant. La réponse : la famille GLM fournit depuis longtemps une interface compatible OpenAI ; dans la grande majorité des cas, il suffit de modifier la Base URL, la clé et le nom du modèle.

Cet article suit l'ordre d'intégration : présentation de l'API GLM-5, obtention de la clé et premier appel réussi, puis diagnostic des erreurs et liste de maîtrise des coûts.

Remarque : Zhipu et GLM sont des marques de leurs détenteurs respectifs ; cet article ne fournit qu'une explication d'intégration technique. Les noms de modèles, longueurs de contexte et règles de facturation sont ceux de la documentation officielle et de la page Tarifs des modèles ; vérifiez les noms de modèles des exemples dans la console avant usage.

1. Qu'est-ce que l'API GLM-5

L'API GLM-5 est l'interface d'appel mise à disposition des développeurs par la plateforme ouverte Zhipu. Ses capacités courantes comprennent :

  • le dialogue multi-tours et le suivi d'instructions ;
  • le résumé, la réécriture et la traduction de longs textes ;
  • l'extraction structurée et la sortie JSON ;
  • la génération et l'explication de code ;
  • les nœuds de raisonnement dans les agents et les workflows.

Elle ne se confond pas avec le produit web : le web fonctionne par abonnement de compte, l'API facture au token ou au volume d'appels, et la clé n'est qu'un justificatif d'appel, pas un droit d'abonnement. Avant d'intégrer, clarifiez l'usage, la concurrence et le budget, puis choisissez entre l'accès officiel et une passerelle agrégatrice.

2. Les deux voies pour obtenir une clé API GLM

Voie 1 : plateforme ouverte Zhipu

  1. Inscrivez-vous et connectez-vous à la plateforme ouverte Zhipu, puis effectuez la vérification d'identité ou d'entreprise selon les exigences de la plateforme.
  2. Créez une clé API dans la console, nommée selon le projet ou l'environnement.
  3. Consultez le solde et les modèles disponibles, et rechargez si nécessaire.
  4. Placez la clé dans une variable d'environnement côté serveur, jamais dans le frontend.

La Base URL officielle est généralement https://open.bigmodel.cn/api/paas/v4 ; la version courante de la documentation officielle fait foi.

Voie 2 : ZSQH AI Gateway

Si vous utilisez déjà plusieurs modèles, ou souhaitez unifier la facturation et la gestion des clés, inscrivez-vous sur ZSQH AI Gateway, créez une clé, puis vérifiez sur la page Tarifs des modèles si la famille GLM est ouverte et comment écrire le nom du modèle.

Les deux voies n'ont pas de supériorité absolue : avec un seul modèle et un accès officiel fluide, la connexion directe est plus simple ; avec plusieurs modèles, un quota unifié et un point d'entrée stable en Chine, la passerelle est plus pratique.

3. Configuration compatible OpenAI

L'interface GLM est proche de Chat Completions d'OpenAI ; lors d'une migration, trois éléments changent principalement :

Élément Connexion officielle Passerelle ZSQH
Base URL https://open.bigmodel.cn/api/paas/v4 https://ai.zhongshangqihang.com/v1
Clé API Créée sur la plateforme Zhipu Créée dans la console de la passerelle
Nom du modèle Selon la documentation officielle Selon la page de tarifs du site
SDK SDK OpenAI utilisable SDK OpenAI utilisable

Attention à la fin de la Base URL : certains SDK ajoutent automatiquement /chat/completions, d'autres exigent le chemin complet. Mélanger adresse officielle et adresse de passerelle produit le plus souvent un 401 ou un 404.

4. Appel avec curl

export ZSQH_API_KEY="sk-votre-clé"

curl "https://ai.zhongshangqihang.com/v1/chat/completions" \
  -H "Authorization: Bearer $ZSQH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5",
    "messages": [
      {"role": "system", "content": "Tu es un rédacteur technique francophone, réponds de façon concrète."},
      {"role": "user", "content": "Explique en trois points à quelles équipes convient une passerelle API"}
    ],
    "temperature": 0.6,
    "max_tokens": 800
  }'

Remplacez model par l'identifiant GLM-5 réellement disponible sur la page de tarifs ; si vous recevez model not found, vérifiez d'abord la casse et le suffixe de version.

5. Appel avec Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ZSQH_API_KEY"],
    base_url="https://ai.zhongshangqihang.com/v1",
)

resp = client.chat.completions.create(
    model="glm-5",  # selon la page de tarifs du site
    messages=[
        {"role": "system", "content": "Tu es un assistant de contrôle qualité, tu ne produis que du JSON."},
        {"role": "user", "content": "Évalue le sentiment de cette phrase : livraison trop lente, mais le service client est agréable."},
    ],
    temperature=0.2,
    response_format={"type": "json_object"},
)

print(resp.choices[0].message.content)

Avec un SDK ancien, response_format peut ne pas être pris en charge : mettez à jour le paquet openai ; si la passerelle ne prend pas en charge le mode JSON, contraignez le format dans le prompt et prévoyez un parsing de secours dans le code.

6. Comment choisir le nom du modèle

La famille GLM comporte généralement des branches généraliste, légère et orientée raisonnement, avec des noms portant version et date. Conseils de sélection :

Scénario Approche Remarque
Service client, résumé, réécriture Modèle de dialogue généraliste Commencer avec une température basse
Raisonnement complexe, mathématiques Modèle renforcé pour le raisonnement Plus lent, consommation de tokens plus élevée
Classification à forte concurrence Modèle léger Tester la précision avant d'augmenter le volume
Tâches de code Version la plus performante en code Attention à la troncature en contexte long

Quel nom exact est disponible, quelle longueur de contexte et quel prix unitaire : la page de tarifs du site fait foi. Ne recopiez pas les anciens noms de modèles trouvés dans des tutoriels en ligne, car les versions GLM évoluent vite.

7. Erreurs courantes

Erreur Cause fréquente Traitement
401 Unauthorized Clé erronée, Bearer absent, clé supprimée Recopier la clé, vérifier l'en-tête
404 Not Found Base URL avec /v1 en trop ou manquant Unifier l'adresse selon la documentation
model not found Nom de modèle inexistant ou non autorisé Copier le nom depuis la page de tarifs
429 Too Many Requests Concurrence ou fréquence dépassée Réduire la concurrence, backoff exponentiel
insufficient balance Solde insuffisant Recharger ou changer de clé
Réponse interrompue Timeout, réseau, sortie longue Augmenter le timeout, activer le streaming

Commencez le diagnostic par l'authentification : validez la clé avec une requête minimale, puis le nom du modèle, et seulement ensuite le réseau. Vous éviterez de modifier le code dans la mauvaise direction.

8. Maîtrise des coûts

  1. Fixez max_tokens pour éviter une sortie sans fin.
  2. Allégez le prompt système ; pour les longues instructions répétées, envisagez un cache ou un modèle de prompt.
  3. Utilisez un modèle léger pour les traitements par lots et montez en gamme pour les cas difficiles.
  4. Enregistrez la consommation de tokens de chaque requête et ventilez la facture par ligne métier.
  5. Plafonnez le quota de chaque clé pour arrêter automatiquement les appels anormaux.
  6. Faites un test de charge en pointe avant la mise en ligne pour connaître le seuil de limitation.

Le coût ne se résume pas au prix unitaire : retries, contexte long et sorties inutiles amplifient la facture. Réduisez d'abord le taux d'échec et le nombre moyen de tokens, puis discutez du prix unitaire.

9. Sécurité et travail en équipe

  • Séparez les clés par environnement : test, préproduction et production, sans réutilisation.
  • Séparez les clés par projet pour suivre tokens et coûts par activité.
  • Stockez la clé dans une variable d'environnement serveur ou un gestionnaire de secrets, jamais dans Git ni dans un bundle frontend.
  • N'imprimez pas la clé complète ni le texte utilisateur dans les journaux ; anonymisez si nécessaire.
  • Configurez une alerte de quota et prévenez le responsable lorsque le solde passe sous un seuil.
  • En cas de départ d'un collaborateur ou de fuite de clé, désactivez et faites tourner immédiatement.

Le risque le plus fréquent en équipe n'est pas le modèle, mais une clé copiée dans une messagerie, un document ou le code frontend. Ajouter une étape « la clé n'existe que côté serveur » au processus d'intégration évite bien des recherches après coup.

Questions fréquentes

L'API GLM-5 fonctionne-t-elle directement avec le SDK OpenAI ?

Dans la plupart des cas, oui : modifiez base_url, api_key et model. Quelques paramètres (certains commutateurs de raisonnement, champs multimodaux) peuvent être incompatibles ; la documentation officielle ou celle du site fait foi.

La clé API GLM et l'abonnement web sont-ils interchangeables ?

Non. L'abonnement web est un produit par souscription ; la clé API est un justificatif développeur. Facturation et droits sont gérés séparément.

Une clé peut-elle appeler d'autres modèles ?

Dans ZSQH AI Gateway, une clé peut appeler plusieurs modèles ouverts, le modèle étant précisé dans la requête ; le périmètre exact figure sur la page de tarifs et dans la console.

Une configuration supplémentaire est-elle nécessaire depuis la Chine ?

Cela dépend de l'environnement réseau et des conditions de service. En production, prévoyez timeouts, retries et canal de secours, sans concentrer toutes les requêtes sur un seul point d'entrée.

Pour aller plus loin

Commencez par vous inscrire sur ZSQH AI Gateway, créez une clé de test, validez une requête minimale avec curl, puis intégrez le code métier. Noms de modèles et prix sont ceux de la page Tarifs des modèles.

Articles liés :