Intégrer l'API OpenAI ne demande que quatre choses : un compte avec lequel se connecter, une clé API utilisable, un projet avec la facturation activée, et une Base URL correcte accompagnée d'un premier appel réussi. Cela semble simple, mais ce qui bloque réellement les nouvelles équipes n'est pas le code : c'est le système de comptes, le moyen de paiement et l'assemblage des adresses.

Cet article suit l'ordre réel des opérations : compte et projet, création de la clé, recharge, installation du SDK, premier appel avec Responses API, lecture de l'usage, diagnostic des erreurs 401 et 429, puis bascule de la Base URL vers une passerelle compatible OpenAI. Les exemples privilégient Responses API ; les outils anciens qui ne prennent en charge que Chat Completions peuvent remplacer l'interface en suivant la même logique.

Note : OpenAI, ChatGPT et GPT sont des marques d'OpenAI. Cet article s'appuie sur le comportement public des interfaces en octobre 2026 ; les noms de modèles, les quotas et les prix sont régis par les prix des modèles et la documentation officielle.

1. Compte, organisation et projet : trois niveaux à distinguer

La plateforme OpenAI comporte au moins trois niveaux, et les confondre est la première source d'erreurs :

  • le compte : l'identifiant de connexion, qui détermine qui peut accéder à la console ;
  • l'organisation : l'unité de rattachement pour la facturation et l'usage ; la collaboration en équipe passe généralement par elle ;
  • le projet : l'unité d'isolation des clés, de l'usage et des permissions. Il est conseillé de séparer les environnements ou les activités.

Une confusion fréquente consiste à prendre un abonnement ChatGPT pour un solde API. Les deux sont distincts : l'abonnement donne accès au produit de chat, tandis que l'API est facturée séparément à chaque appel. Avant d'intégrer une équipe, déterminez qui possède le compte, qui paie et qui détient les droits d'administration, afin d'éviter de perdre la trace des clés lors d'un changement de personnel.

2. L'ordre de création d'une clé API

Suivez les étapes ci-dessous sans en sauter :

  1. Connectez-vous à la console API avec un compte administrateur et vérifiez que l'organisation sélectionnée est la bonne.
  2. Créez ou sélectionnez un projet au sein de l'organisation, en séparant « développement », « test » et « production ».
  3. Ouvrez la page API Keys du projet et créez une nouvelle clé.
  4. Donnez à la clé un nom qui indique son usage, par exemple « production-chatbot-support ».
  5. Copiez immédiatement la clé complète et stockez-la dans un gestionnaire de mots de passe ou dans le coffre de secrets de la plateforme de déploiement.
  6. Configurez si besoin les permissions, le budget ou le plafond du projet, puis enregistrez.

La clé complète n'est généralement affichée qu'une seule fois, à la création. Il est normal de ne plus voir que les premiers et derniers caractères ensuite : ne comptez pas pouvoir la recopier plus tard. En cas de perte, créez une nouvelle clé et désactivez l'ancienne ; ne cherchez pas à la récupérer.

3. Recharge, facturation et quotas

Le mode prépayé ou postpayé dépend du type de compte et de la région ; référez-vous à ce qu'affiche la console. Avant l'activation, vérifiez trois points :

  1. le moyen de paiement accepte-t-il votre carte ou votre canal de règlement ;
  2. comment obtenir le cycle de facturation et les factures ;
  3. peut-on définir des alertes de budget et un plafond strict par projet.

Les échecs de paiement sont fréquents au moment de l'intégration. Si la carte est refusée, vérifiez d'abord l'adresse de facturation, le nom du titulaire et le mode de vérification, puis contactez la banque émettrice ; n'envoyez pas plusieurs tentatives coup sur coup, car certains systèmes antifraude bloquent alors la carte. Les équipes qui passent par une passerelle peuvent généralement recharger en yuans ; les tarifs et règles de crédit figurent sur la page des prix, les prix étant susceptibles d'évoluer : la page fait foi au moment de la commande.

4. Installer le SDK et lancer un premier curl

Installez d'abord le SDK Python officiel :

python3 -m pip install --upgrade openai
export OPENAI_API_KEY="sk-votre-cle"
export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_MODEL="nom-du-modele-copie-depuis-la-page-des-prix"

Testez Responses API avec curl pour confirmer que l'adresse, la clé et le réseau fonctionnent :

curl -sS "$OPENAI_BASE_URL/responses" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$OPENAI_MODEL"'",
    "input": "Explique en une phrase ce qu'\''est une passerelle API."
  }'

N'écrivez pas le nom du modèle de mémoire : copiez le nom actuellement disponible depuis la page des prix ou la documentation officielle, puis stockez-le dans la variable OPENAI_MODEL. Un code 200 avec une sortie dans le corps de la réponse indique que la chaîne fonctionne ; un 401 pointe d'abord vers la clé, un 404 vers la Base URL ou le nom du modèle.

5. Premier appel en Python

Voici une requête minimale avec Responses API, qui affiche le texte obtenu :

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENAI_API_KEY"],
    base_url=os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1"),
)

resp = client.responses.create(
    model=os.environ["OPENAI_MODEL"],
    input="Décris en trois phrases les limites de tes capacités.",
)

print(resp.output_text)

Si votre framework ne prend en charge que Chat Completions, remplacez l'appel par client.chat.completions.create(...) et placez les messages dans messages. Les deux interfaces utilisent des chemins différents : les mélanger produit très souvent un 404.

6. Comprendre l'usage et la facture

La page Usage de la console présente généralement la consommation par projet, par modèle et par période, en distinguant entrée et sortie. Au début, consultez-la une fois par jour et vérifiez surtout :

  • quel projet consomme ;
  • quelle part revient à l'entrée et quelle part à la sortie ;
  • si des échecs ou des nouvelles tentatives anormales apparaissent ;
  • si les alertes de budget fonctionnent.

Conservez l'identifiant de requête renvoyé dans les journaux. En cas de litige de facturation ou d'incident, cet identifiant est la première pièce permettant au fournisseur de localiser le problème. L'équipe doit aussi associer, côté application, l'utilisateur, le module fonctionnel et l'identifiant de requête ; sinon la facture ne montre qu'un total impossible à imputer.

7. Diagnostiquer les erreurs 401 et 429

Un 401 signifie que l'identité n'est pas reconnue. Vérifiez dans l'ordre : la présence de Bearer dans l'en-tête ; les espaces ou retours à la ligne ajoutés à la clé ; une clé supprimée ou un projet désactivé ; l'envoi d'une clé de passerelle vers l'adresse officielle. Avant de changer de clé, confirmez où la requête est réellement envoyée, sinon vous risquez de chercher au mauvais endroit.

Un 429 a deux significations : limitation de débit et solde insuffisant. Lisez le code d'erreur et les en-têtes de réponse, ne vous contentez pas de ralentir. insufficient_quota renvoie généralement au solde ou au quota : il faut recharger ou ajuster le plafond du projet. Seules les erreurs de débit justifient une temporisation exponentielle. Réessayer n'a de sens que pour les 429, les 5xx et les erreurs réseau ; réessayer un 400, 401, 403 ou 404 ne fait que consommer du quota. Pour un ordre de diagnostic plus complet, consultez les prix des modèles et la documentation officielle.

8. Accès direct ou passerelle compatible : comment choisir

Critère Accès direct officiel Passerelle compatible OpenAI
Adresse d'accès https://api.openai.com/v1 Base URL fournie par la passerelle, généralement terminée par /v1
Compte et paiement Compte officiel, moyens de paiement acceptés par la plateforme Compte sur le site de la passerelle, recharge en yuans et factures
Réseau Dépend du réseau local et des liaisons transfrontalières Point d'accès généralement accessible depuis le pays
Catalogue de modèles Modèles propres à OpenAI Plusieurs fournisseurs possibles, selon la page des prix
Facturation Facture officielle Solde et historique d'usage sur le site
Gestion des incidents Canaux de support officiels La passerelle diagnostique l'amont ; conservez les identifiants de requête
Cas adaptés Usage exclusif d'OpenAI avec un canal de paiement conforme Équipes locales, multi-modèles, facturation unifiée

Ne comparez pas seulement le prix unitaire. La fluidité du paiement, la prise en charge des incidents et la possibilité de changer de modèle à tout moment pèsent aussi sur le coût à long terme. Les prix évoluent : la page des prix fait foi.

9. Passer à une passerelle compatible : seule la Base URL change

La migration coûte généralement moins cher que prévu, car une passerelle compatible conserve le même format de requête. Procédez ainsi :

  1. Inscrivez-vous sur la passerelle et créez une clé depuis la page d'inscription.
  2. Remplacez OPENAI_BASE_URL par l'adresse de la passerelle en conservant /v1.
  3. Remplacez la clé par celle de la passerelle ; ne mélangez pas les deux jeux de clés.
  4. Copiez le nom du modèle depuis la page des prix de la passerelle, sans réutiliser le nom officiel au hasard.
  5. Appelez d'abord /v1/models et une requête minimale, puis basculez le trafic de production.
  6. Conservez l'accès officiel ou une ligne de secours comme solution de repli.

« Compatible OpenAI » signifie que les formats de requête et de réponse sont compatibles, pas que toutes les extensions le sont. La prise en charge des fichiers, du traitement par lots ou de l'appel d'outils doit être vérifiée point par point dans la documentation de la passerelle. Pour les détails, reportez-vous à la page des prix et aux documents officiels.

10. Sécurité des clés et checklist avant mise en production

Une clé divulguée génère directement des coûts. Exigences minimales :

  • stocker la clé uniquement dans des variables d'environnement côté serveur ou dans un gestionnaire de secrets, jamais dans le code frontend ni dans Git ;
  • séparer les clés par environnement, sans partage entre test et production ;
  • indiquer pour chaque clé un responsable et un usage, et la désactiver au départ d'une personne ou à la fin d'un projet ;
  • ne jamais journaliser la clé complète, seulement les quatre derniers caractères ;
  • effectuer une rotation régulière et révoquer immédiatement en cas d'appels anormaux.

Checklist avant mise en ligne :

  • [ ] compte, organisation et projet clairement attribués ;
  • [ ] moyen de paiement opérationnel et alertes de budget configurées ;
  • [ ] clé stockée dans les variables d'environnement ou un gestionnaire de secrets ;
  • [ ] Base URL avec un seul /v1 ;
  • [ ] requête minimale renvoyant 200 avec un contenu normal ;
  • [ ] temporisation pour les 429 et nouvelles tentatives pour les 5xx configurées ;
  • [ ] journaux d'usage contenant identifiant de requête, modèle et durée ;
  • [ ] procédure de bascule vers une ligne de secours et de révocation testée.

11. Questions fréquentes

La clé API et l'abonnement ChatGPT sont-ils la même chose ?

Non. L'abonnement et l'API sont facturés séparément, et la clé API se crée et se gère uniquement sur la plateforme API. Les équipes doivent distinguer les deux dépenses lors des remboursements.

Pourquoi la clé complète n'apparaît-elle plus après la création ?

La clé complète n'est généralement affichée qu'une fois, à la création ; la plateforme n'en conserve qu'une partie pour l'identification. En cas de perte, créez une nouvelle clé et désactivez l'ancienne.

Que faut-il mettre exactement dans la Base URL ?

Le domaine suivi de /v1, sans /chat/completions ni /responses. Le chemin est ajouté par le SDK ou la requête ; un segment en trop provoque un 404.

Une clé peut-elle servir à plusieurs projets ?

Techniquement oui, mais ce n'est pas recommandé. Séparer les clés par projet ou environnement permet de contrôler les permissions, d'imputer l'usage et de limiter l'impact en cas de fuite.

Une équipe locale doit-elle forcément passer par une passerelle ?

Pas nécessairement. Tout dépend du canal de paiement, de la qualité du réseau, des exigences de conformité et du besoin de plusieurs modèles. Une équipe qui n'utilise qu'OpenAI avec un paiement et un réseau stables peut se connecter directement ; celles qui ont besoin d'un règlement en yuans et d'un point d'entrée unifié peuvent évaluer une migration via la page des prix.

Étape suivante

Faites d'abord fonctionner la requête minimale, puis connectez votre activité. Pour une recharge en yuans et un point d'entrée unifié multi-modèles, commencez par vous inscrire à ZSQH AI Gateway ; les modèles et les prix sont régis par les prix des modèles.

Lectures associées :