OpenAI SDK

Les SDK officiels OpenAI pour Python et TypeScript acceptent une Base URL personnalisée. En pointant le client vers https://api.agtcloud.cn/v1, vous pouvez utiliser les mêmes méthodes SDK pour appeler les endpoints compatibles Chat Completions et Responses d’AGTCloud.

Cette page concerne les applications côté serveur. Le code exécuté dans un navigateur, un package d’application de bureau ou une application mobile ne peut pas protéger une API Key durable : n’y créez pas directement de client OpenAI contenant de véritables identifiants.

Choisir Chat ou Responses

Les deux endpoints utilisent la même API Key AGTCloud, mais les modèles pris en charge peuvent différer. Vérifiez les protocoles dans le catalogue de modèles et remplacez MODEL_ID par l’ID complet du modèle.

Prérequis

Avant de commencer, vérifiez que vous avez :

• Créé une API Key AGTCloud dans API Keys ;
• Préparé l’ID d’un modèle prenant en charge Chat Completions ou Responses ;
• Préparé un environnement serveur fiable avec Python 3.10+ ou Node.js 22+ ;
• Activé un fichier de verrouillage des dépendances, sans mise à niveau automatique incontrôlée du SDK en production.

Les exigences du runtime évoluent avec les versions du SDK. Avant une mise à niveau, vérifiez à la fois les environnements officiellement pris en charge et votre environnement de déploiement.

Installer le SDK

python -m pip install openai

Après l’installation, figez la version effectivement résolue dans le fichier de verrouillage du projet. Lors d’une mise à niveau, vérifiez de nouveau l’initialisation du client, les types de réponse et le traitement du streaming.

Configurer l’API Key

Fournissez de préférence l’API Key via une variable d’environnement côté serveur. Les paramètres ci-dessous sont uniquement des exemples avec identifiants fictifs ; vous pouvez utiliser un service de gestion des secrets cloud lors du déploiement.

export AGTCLOUD_API_KEY="your-api-key"

Créer le client OpenAI

La Base URL du client doit être https://api.agtcloud.cn/v1. Ne saisissez pas seulement l’API Origin et n’ajoutez pas /chat/completions ou /responses : le SDK ajoute le chemin correspondant à la méthode appelée.

import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["AGTCLOUD_API_KEY"],
    base_url="https://api.agtcloud.cn/v1",
)

Utiliser Responses

Responses exprime le texte ou les Typed Items via input. Une réponse réussie contient un état, des Output Items et la consommation de Token. Le SDK propose output_text pour agréger le texte de la réponse.

response = client.responses.create(
    model="MODEL_ID",
    instructions="Veuillez répondre en français de manière concise et précise.",
    input="Expliquez en trois points quels problèmes un service d’agrégation d’API permet de résoudre.",
)

print(response.output_text)

output_text convient aux résultats textuels ordinaires. Pour traiter les appels de fonctions, les résultats de recherche, les éléments de raisonnement ou d’autres types, parcourez response.output dans l’ordre, sans conserver seulement les Message. Consultez OpenAI Responses Reference pour la structure complète.

Utiliser Chat Completions

Chat Completions utilise une liste ordonnée de messages. Le texte ordinaire se trouve généralement dans l’Assistant Message du premier Choice.

completion = client.chat.completions.create(
    model="MODEL_ID",
    messages=[
        {
            "role": "developer",
            "content": "Veuillez répondre en français de manière concise et précise.",
        },
        {
            "role": "user",
            "content": "Expliquez en trois points quels problèmes un service d’agrégation d’API permet de résoudre.",
        },
    ],
)

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

Lors d’un appel d’outils, message.content peut être vide : vérifiez alors message.tool_calls. Les champs sont décrits dans Chat Completions Reference.

Recevoir une réponse en streaming

Le SDK OpenAI expose la réponse SSE sous forme de flux d’événements itérable. Les événements Responses ont un type explicite. L’exemple imprime uniquement les fragments de texte ; votre code doit aussi traiter la fin, l’échec et l’interruption.

stream = client.responses.create(
    model="MODEL_ID",
    input="Présentez-vous en une phrase.",
    stream=True,
)

for event in stream:
    if event.type == "response.output_text.delta":
        print(event.delta, end="", flush=True)

Continuation avec état (si la plateforme le prend en charge)

Si le modèle, le compte et le canal amont prennent en charge le stockage et la continuation des réponses, vous pouvez enregistrer la première réponse et transmettre son ID comme previous_response_id à la requête suivante :

first = client.responses.create(
    model="MODEL_ID",
    store=True,
    input="Retenez que le nom de code du projet est Aurora.",
)

second = client.responses.create(
    model="MODEL_ID",
    previous_response_id=first.id,
    input="Quel est le nom de code du projet ?",
)

print(second.output_text)

Avec previous_response_id, les instructions du tour précédent ne deviennent pas automatiquement celles du tour actuel. Retransmettez les contraintes de comportement qui doivent continuer à s’appliquer.

Si la chaîne d’appel ne prend pas en charge le stockage ou la continuation, maintenez l’historique dans l’application et transmettez les Input et Output Items nécessaires dans le prochain input. Un historique complet ne se limite pas au texte : conservez aussi les relations entre messages, raisonnement et appels d’outils requises par votre application.

Délais, nouvelles tentatives et erreurs

Le SDK OpenAI transforme les erreurs HTTP en exceptions correspondantes et réessaie un nombre limité de fois certaines erreurs de connexion, de délai, de débit et de serveur. En production, configurez explicitement les délais et le nombre maximal de tentatives selon la requête afin d’éviter une attente excessive ou une consommation répétée.

Ne consignez pas d’API Key complète, de corps de requête sensible ou de contenu utilisateur non traité. Si la réponse fournit un Request ID, conservez-le dans le journal d’erreur pour retrouver la requête.

Vérifications finales

• La Base URL est https://api.agtcloud.cn/v1, sans doublon /v1 ni chemin d’endpoint spécifique.
• L’API Key est lue depuis un environnement serveur fiable et n’apparaît ni dans le frontend ni dans le contrôle de version.
• MODEL_ID désigne un modèle accessible à l’API Key et prenant en charge l’endpoint cible.
• Les requêtes ordinaires permettent de lire correctement le texte, l’état et la consommation.
• Le code de streaming distingue les fragments de texte, les événements de fin et les erreurs.
• Les requêtes d’outils ou multimodales ciblent uniquement les modèles qui prennent explicitement ces capacités en charge.

Pour remplacer systématiquement la configuration d’un fournisseur dans un projet existant, lisez Migration depuis les SDK officiels. Pour convertir une structure Chat en Responses, consultez Chat → Responses.