Conventions communes

Cette page décrit les règles d’appel communes aux endpoints AGTCloud. Les champs, états et structures de réponse propres à chaque interface restent définis dans sa page de référence API.

Adresse API et Base URL

Cette page utilise l’adresse API https://api.agtcloud.cn. Les SDK compatibles OpenAI utilisent la Base URL https://api.agtcloud.cn/v1.

Authentification

La plupart des API protégées utilisent une clé API Bearer :

Authorization: Bearer your-api-key

Anthropic Messages utilise des Headers d’authentification spécifiques et exige une version d’API :

x-api-key: your-api-key
anthropic-version: 2023-06-01

Consultez la page de l’Endpoint pour les Headers facultatifs, tels que anthropic-beta, et les exigences d’authentification des autres protocoles.

Créez et gérez vos jetons dans API Keys. Envoyez uniquement la clé API lors des appels, et non un mot de passe de console, un Cookie, un jeton administrateur ou une clé du fournisseur.

Voici une requête Chat Completions minimale :

curl 'https://api.agtcloud.cn/v1/chat/completions' \
  --request POST \
  --header 'Authorization: Bearer your-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "model": "MODEL_ID",
    "messages": [
      {
        "role": "user",
        "content": "Bonjour"
      }
    ]
  }'

Consultez Clé API, Base URL et authentification pour la création, la rotation et le stockage des clés en production.

Emplacement des paramètres de requête

Les pages d’endpoint présentent les champs selon leur emplacement :

Encodez les paramètres de Path pour les URL. Omettez les paramètres facultatifs inutilisés plutôt que de remplacer toutes leurs valeurs par des chaînes vides.

Content-Type et formats de données

Ne définissez pas boundary en dur pour Multipart. Laissez le navigateur, le SDK ou le client HTTP générer le Content-Type complet selon le contenu du formulaire.

Identifiant du modèle

MODEL_ID est un espace réservé dans les exemples ; remplacez-le par un identifiant disponible pour votre clé API. Consultez le catalogue de modèles ou renseignez votre clé dans Try It pour obtenir la liste renvoyée pour cette clé.

Le modèle, le protocole et le fournisseur sont des notions distinctes :

• L’identifiant du modèle détermine le modèle cible de la requête.
• L’Endpoint détermine le protocole et la structure des messages utilisés par le client.
• Un modèle peut proposer plusieurs protocoles ou ne prendre en charge qu’une partie des champs.

Analyser les réponses

Traitez les réponses dans l’ordre suivant :

Réponses en streaming

Les interfaces SSE transmettent plusieurs événements ou blocs de données dans une même réponse HTTP. Lisez le contenu progressivement ; n’attendez pas la fermeture de la connexion pour analyser toute la réponse comme un seul objet JSON.

• Identifiez l’événement ou le marqueur de fin décrit par l’endpoint.
• Traitez séparément les fragments de contenu, appels d’outils, Usage et événements d’erreur.
• En cas d’interruption réseau, ne considérez pas automatiquement le contenu reçu comme un résultat complet.
• Les structures d’événements varient selon le protocole ; utilisez les définitions de l’endpoint actuel.

Tâches asynchrones

Les interfaces vidéo, Midjourney et similaires renvoient généralement un identifiant de tâche, puis une interface de consultation permet d’obtenir la progression et le résultat final :

Soumettre la tâche → Conserver son identifiant → Consulter son état → Vérifier l’état terminal → Lire le résultat

Les noms des champs d’identifiant, les états possibles et les chemins de consultation dépendent du protocole. Ne mélangez pas id, task_id, video_id ou les valeurs d’état entre interfaces.

Définissez un intervalle d’interrogation et un délai total, puis arrêtez les consultations en cas de succès, d’échec ou d’annulation. Si la soumission expire mais que la tâche a pu être créée, vérifiez d’abord son état pour éviter de créer plusieurs tâches payantes.

Statuts HTTP et nouvelles tentatives

Voici les orientations générales ; la structure réelle des erreurs dépend de la réponse de l’endpoint :

Ne réessayez pas indéfiniment pour toutes les erreurs. Corrigez d’abord les problèmes de paramètres, d’authentification ou de droits. Pour les requêtes pouvant avoir des effets de bord, comme la création d’une tâche, vérifiez d’abord si la soumission a réussi.

Consultez le dépannage pour une procédure de diagnostic plus complète.

Usage, temps et champs supplémentaires

• La présence et les noms des champs Usage dépendent du protocole et du modèle ; le client doit accepter des valeurs nulles ou des champs absents.
• Les champs temporels peuvent utiliser des secondes Unix, des millisecondes Unix ou des chaînes de date ; analysez-les selon le Schema de l’endpoint.
• Les extensions fournisseur ne s’appliquent généralement qu’à certains modèles et ne constituent pas des capacités communes à tous.
• Tolérez l’ajout de champs non essentiels dans les réponses pour éviter qu’une extension compatible de la plateforme fasse échouer toute l’analyse.

Sécurité et journaux

• Stockez les clés API durables sur un serveur de confiance ou dans un gestionnaire de secrets ; ne les intégrez pas aux frontends, applications de bureau ou applications mobiles de production.
• Try It sert uniquement aux tests temporaires initiés par l’utilisateur dans le navigateur. N’utilisez pas de clé de production durable sur un appareil partagé.
• N’inscrivez pas de clé dans un dépôt public, une capture d’écran, un journal ou un ticket d’assistance.
• Expurgez les prompts, adresses de fichiers, informations de compte et données sensibles des requêtes et réponses dans les éléments de dépannage.
• Désactivez ou supprimez rapidement les clés inutilisées ou potentiellement compromises et mettez à jour les services qui les utilisent.

Pour continuer : API Reference · Démarrage rapide · Dépannage