Passerelle d’IA

Utilisez les comptes d’IA connectés à votre instance AirCode Ø depuis vos applications personnelles. Fournissez l’URL de base de l’instance, un token d’application distinct et l’identifiant exact du modèle. L’instance appelle la CLI du fournisseur connecté et renvoie la réponse par une partie de l’API Chat Completions pour le texte, ou Images pour les images.

Your application's backend
  → your instance URL + application token
    → a connected native provider account
      → validated answer + available usage counters

Ce site héberge uniquement la documentation. Les requêtes API vont directement à votre instance : aircodezero.com ne reçoit ni son adresse, ni le token, ni les demandes envoyées aux modèles. Réservez cette passerelle à vos propres applications et comptes. Les conditions, les abonnements et les quotas des fournisseurs continuent de s’appliquer.

Configurer l’instance

1. Connectez un compte de fournisseur compatible dans Consommation IA. La passerelle affiche les modèles de ce compte pris en charge par votre instance. Les connexions par clé API et les crédits gérés en sont exclus.
2. Ouvrez Paramètres → Passerelle IA sur le web ou dans l’application de bureau, ou Plus → Passerelle IA sur mobile. Sous Créer un accès, activez Autoriser les connexions privées.
3. Copiez l’URL de base affichée. Elle se termine par /api/ai-gateway/v1.
4. Dans Créer un token, choisissez Une application, saisissez son nom, puis choisissez Créer un token. Copiez-le avant de fermer son affichage unique. Ce choix donne accès à l’API IA pour le texte et les images, mais pas aux sessions d’une autre instance.
5. Définissez ces variables d’environnement sur le serveur de votre application :

Conservez les tokens dans la configuration secrète de votre serveur. Ne les placez ni dans le code du navigateur, ni dans une application mobile, un dépôt, une URL ou une conversation partagée. Les exemples utilisent des variables d’environnement au lieu d’inscrire les identifiants dans le code. N’utilisez jamais le mot de passe de l’instance ou le token de connexion du propriétaire comme clé API.

L’instance doit rester en marche et accessible depuis le serveur de votre application. localhost désigne la machine qui exécute ce serveur. Pour un accès distant, utilisez l’adresse HTTPS de l’instance ou une connexion de confiance sur votre réseau local ou privé. La passerelle ne crée aucune adresse publique. Vous ne pouvez pas sélectionner un fournisseur absent de /models en inventant un identifiant.

Authentification et découverte des modèles

Envoyez Authorization: Bearer YOUR_APPLICATION_TOKEN à chaque appel, avec du JSON et Content-Type: application/json. L’authentification par paramètre d’URL ou par cookie n’est pas prise en charge. Les appels directs depuis un navigateur sur une autre origine ne le sont pas non plus : passez par votre serveur.

GET {BASE_URL}/models renvoie un objet contenant object: "list" et un tableau data. Chaque modèle fournit un id, un label visible, engine, engineLabel, provider, connectionLabel, efforts et capabilities. Les capacités possibles sont chat.completions pour le texte, images.generations et images.edits pour les images. Réutilisez l’id retourné sans le modifier : il peut déjà contenir des caractères encodés. La liste peut changer si les comptes, les droits du fournisseur ou les modèles installés changent.

Dans une application compatible avec l’API OpenAI, choisissez Chat Completions, saisissez l’URL de base complète, placez le token d’application dans le champ Clé API et copiez l’un des identifiants de modèle retournés. Les images utilisent la partie de l’API décrite plus bas. Les applications qui exigent l’API Responses, l’appel d’outils ou des paramètres de génération non pris en charge ne sont pas compatibles avec cette passerelle.

Générer une réponse

POST {BASE_URL}/chat/completions accepte les champs suivants. Tout champ inconnu est refusé.

Chaque message ne contient que role et content. Les blocs de texte sont joints par des retours à la ligne. Les caractères nuls sont refusés. Le tableau de messages normalisé est limité à 64 KiB de JSON en UTF-8 ; le corps HTTP complet, à 80 KiB. La réponse validée est limitée à 49 152 unités de code de chaîne JavaScript. Ce sont les limites de la passerelle, sans garantie sur la fenêtre de contexte ou la longueur de réponse du fournisseur.

Envoyez le contexte utile de la conversation à chaque appel. Pour la poursuivre, ajoutez la réponse précédente de l’assistant et le nouveau message de l’utilisateur. La passerelle ne crée ni ne conserve de conversation, de session ou d’historique de réponses. Un token ne donne accès ni aux projets, fichiers, terminaux et sessions de l’instance, ni aux paramètres du propriétaire.

Une réponse normale contient object: "chat.completion". Son texte se trouve dans choices[0].message.content. Elle comporte aussi id, created, le model demandé et finish_reason: "stop". Les compteurs du fournisseur figurent dans usage lorsqu’ils sont assez complets. L’extension aircode_usage conserve les détails et les estimations incomplètes. Un compteur ou un prix absent reste inconnu : il ne vaut jamais zéro. Une estimation au tarif API ne constitue pas une facturation supplémentaire de l’abonnement.

Réponses en flux

Définissez stream: true pour recevoir Content-Type: text/event-stream. La passerelle utilise actuellement un flux mis en mémoire tampon : elle envoie un premier commentaire d’attente, puis des commentaires de maintien de connexion pendant le travail du fournisseur. Elle n’envoie la réponse complète qu’après validation. Les mots et les tokens ne sont pas transmis au fur et à mesure de leur génération.

Un flux réussi contient :

1. Des commentaires SSE commençant par : pendant l’attente ; ignorez-les.
2. Un événement data: JSON de type chat.completion.chunk, avec le rôle de l’assistant et le texte complet dans choices[0].delta.content.
3. Un fragment dont le delta est vide et dont finish_reason: "stop" indique la fin de la réponse.
4. Éventuellement, un fragment avec choices: [], usage (qui peut valoir null) et aircode_usage si stream_options.include_usage est vrai.
5. data: [DONE].

Après le début du flux, une erreur arrive dans un événement SSE data: contenant error : un statut HTTP 200 ne suffit donc pas à confirmer la réussite. Un flux en échec se ferme sans marqueur de succès. Les trames SSE peuvent être réparties sur plusieurs morceaux réseau ; utilisez un SDK ou un analyseur SSE plutôt que de traiter chaque morceau comme un document JSON.

La fermeture de la connexion annule la requête en cours. La révocation du token, la désactivation de la passerelle ou l’arrêt de l’instance annulent aussi le travail correspondant. Il n’y a ni renvoi ni reprise automatique. Les requêtes longues nécessitent un client et un délai de proxy adaptés ; les messages de maintien de connexion ne prolongent pas la durée maximale imposée par le réseau.

Générer une image

Le modèle d’image apparaît si le compte Codex connecté à l’instance peut utiliser son outil de génération d’images. Cela nécessite un abonnement ChatGPT donnant accès à cette fonction. Son id est codex/image-generation. Codex choisit lui-même le modèle d’image ; la passerelle ne le choisit pas.

• POST {BASE_URL}/images/generations accepte du JSON avec model, prompt (jusqu’à 32 000 caractères) et, facultativement, size, n: 1 et response_format: "b64_json".
• POST {BASE_URL}/images/edits accepte du multipart/form-data avec les mêmes champs et de 1 à 4 images de référence dans image ou image[]. Chaque image doit être un PNG ou un JPEG de 4 MiB au maximum. Les autres champs de fichier, comme mask, sont refusés.

size vaut auto ou WIDTHxHEIGHT, entre 64 et 4096 pixels. Cette taille sert d’indication au modèle ; la réponse donne la taille réelle. Tout autre champ est refusé.

curl -sS "$AIRCODE_AI_BASE_URL/images/edits" \
  -H "Authorization: Bearer $AIRCODE_AI_TOKEN" \
  -F model=codex/image-generation \
  -F "prompt=Place this product in a premium studio shot on a stone pedestal." \
  -F size=1024x1536 \
  -F image=@product.png

La réponse contient created, un data[0].b64_json, output_format (png, jpeg ou webp), la taille réelle size et aircode_usage. Les compteurs couvrent l’agent qui a appelé l’outil d’image. Le fournisseur ne signale pas le coût propre de cet outil : costComplete vaut donc toujours false. Une génération prend généralement une à trois minutes et partage les limites ci-dessous avec les appels texte. Elle est annulée si le client se déconnecte. Si le modèle répond sans image, l’appel échoue avec 422 et AI_GATEWAY_NO_IMAGE, accompagnés de sa réponse textuelle si elle existe.

Connecter automatiquement une application AirCode Ø enregistrée

Une application enregistrée dans Apps et dotée de son propre serveur peut recevoir cet accès sans que vous copiiez de token. Sur sa page, ouvrez Paramètres → Accès → Comptes IA et activez l’option. AirCode Ø :

1. active la passerelle d’IA privée si elle était désactivée ;
2. redémarre l’application et fournit à son serveur, à chaque démarrage, un nouveau token qui révoque celui du démarrage précédent ;
3. définit AIRCODE_AI_BASE_URL sur l’adresse de la passerelle accessible à l’instance, AIRCODE_AI_TOKEN et, si disponibles, AIRCODE_AI_MODEL pour le texte et AIRCODE_AI_IMAGE_MODEL pour les images.

Une version publiée de l’application reçoit son propre token de la même manière. La désactivation des comptes d’IA révoque immédiatement les tokens de l’application. Appelez la passerelle depuis le serveur de l’application et gardez le token sur ce serveur : toute personne qui peut ouvrir l’application peut utiliser vos comptes par son intermédiaire, et cette utilisation compte dans vos abonnements.

Quotas, durée de vie des tokens et erreurs

La passerelle autorise deux appels actifs par instance, un appel actif par token et 30 requêtes de génération admises par token et par minute. Les appels ne sont pas mis en file d’attente. Ces limites locales ne remplacent pas celles du fournisseur. Les tokens expirent après 90 jours : créez-en un nouveau, mettez à jour votre application, puis révoquez l’ancien. La désactivation de la passerelle conserve les tokens, mais suspend leur utilisation. Une restauration de l’état de l’instance désactive la passerelle et efface les autorisations des tokens : créez-en de nouveaux.

Les erreurs fournissent error.message, error.type, error.code et error.param. Lisez le code en plus du statut HTTP. Ne relancez pas automatiquement une génération dont le résultat est inconnu : elle a peut-être déjà consommé du quota. Les exemples désactivent les nouvelles tentatives automatiques des SDK.

Si le fournisseur ne donne pas d’heure de rétablissement, elle reste inconnue. Ne la déduisez ni du nom du modèle, ni du calendrier d’un autre fournisseur.

Utiliser une autre instance depuis l’application

Une application externe peut appeler une autre instance que vous possédez avec sa Base URL et un token créé sur cette instance. Chaque token appartient à l’instance qui l’a émis. Pour qu’un agent sur B travaille sur un projet de A, choisissez Une autre instance lors de la création du token sur B et suivez le guide des sessions distantes. Par défaut, les fichiers et les commandes restent sur A. Enregistrez la connexion sur A, choisissez B sous Nouvelle session → Exécuter sur et gardez Emplacement du projet → Cette instance. Pour travailler sur un projet de B, choisissez Cette instance et ce projet lors de la création du token sur B, puis Emplacement du projet → Instance distante sur A. Les deux modes transmettent les événements en direct. Les tokens ordinaires couvrent le texte et les images ; aucun ne connecte le client comme propriétaire distant. Les appels d’outils via Responses, Anthropic Messages et Chat Completions restent hors du sous-ensemble de l’API texte pris en charge.

Pour intégrer la passerelle avec l’aide d’une IA, consultez la documentation pour l’IA, le guide Markdown brut, le schéma OpenAPI et le skill d’intégration.

Exemples de code

Définissez les trois variables d’environnement ci-dessus avant d’exécuter un exemple. Ces extraits figurent aussi dans les paramètres et dans le guide Markdown brut.

set -euo pipefail
# The token is read from standard input, not a command-line argument.
curl --fail-with-body --silent --show-error --location --max-redirs 0 \
  "$AIRCODE_AI_BASE_URL/models" --header @- <<EOF
Authorization: Bearer $AIRCODE_AI_TOKEN
EOF

body=$(jq -n --arg model "$AIRCODE_AI_MODEL" \
  '{model: $model, messages: [{role: "user", content: "Hello!"}]}')
curl --fail-with-body --silent --show-error --location --max-redirs 0 \
  "$AIRCODE_AI_BASE_URL/chat/completions" \
  --header 'Content-Type: application/json' \
  --header @- --data "$body" <<EOF
Authorization: Bearer $AIRCODE_AI_TOKEN
EOF

import os
from openai import OpenAI, DefaultHttpx2Client

client = OpenAI(
    base_url=os.environ["AIRCODE_AI_BASE_URL"],
    api_key=os.environ["AIRCODE_AI_TOKEN"],
    max_retries=0,
    http_client=DefaultHttpx2Client(follow_redirects=False),
)

for model in client.models.list():
    print(model.id)

response = client.chat.completions.create(
    model=os.environ["AIRCODE_AI_MODEL"],
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

import OpenAI from "openai";

function required(name) {
  if (!process.env[name]) throw new Error("Set " + name + " first.");
  return process.env[name];
}

const client = new OpenAI({
  baseURL: required("AIRCODE_AI_BASE_URL"),
  apiKey: required("AIRCODE_AI_TOKEN"),
  maxRetries: 0,
  fetchOptions: { redirect: "error" },
});

const stream = await client.chat.completions.create({
  model: required("AIRCODE_AI_MODEL"),
  messages: [{ role: "user", content: "Hello!" }],
  stream: true,
  stream_options: { include_usage: true },
});

try {
  for await (const chunk of stream) {
    process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
    if (chunk.usage) console.error("Tokens:", chunk.usage.total_tokens);
  }
  process.stdout.write("\n");
} finally {
  stream.controller.abort();
}

Références de configuration SDK :SDK Python d’OpenAIet SDK JavaScript d’OpenAI. Cette passerelle prend en charge le sous-ensemble documenté ci-dessus.