Intégrer l'IA via API : un guide pratique

Tu as une app. Tu veux qu'elle parle à l'IA. Peut-être que tu veux des chat completions, peut-être de la génération d'images, peut-être les deux. La bonne nouvelle : si tu as déjà utilisé l'API OpenAI, tu sais déjà utiliser la nôtre. La meilleure nouvelle : tu obtiens accès à 367 modèles de 61 fournisseurs à travers un seul endpoint.

Pas de nouveau SDK à apprendre. Pas de protocole propriétaire. Change juste l'URL de base et ta clé API.

Étape 1 : Obtenir ta clé API

Inscris-toi sur zubnet.com et navigue vers les paramètres de ton espace de travail. Ta clé API vit là. Elle commence par un préfixe reconnaissable :

zub_live_a1b2c3d4e5f6...

Garde-la secrète. Traite-la comme un mot de passe. Si elle fuit, fais-la tourner immédiatement depuis les paramètres de ton espace de travail — l'ancienne clé arrête de fonctionner dès que tu en génères une nouvelle.

Étape 2 : Définir ton URL de base

Chaque requête va à :

https://api.zubnet.ai/v1

C'est tout. Le préfixe /v1 correspond à la convention OpenAI, donc toute bibliothèque, outil ou framework qui supporte OpenAI fonctionnera en changeant juste l'URL.

Étape 3 : Faire ta première requête

Utiliser curl

Le test le plus simple possible — un chat completion avec un message :

curl https://api.zubnet.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer zub_live_YOUR_KEY" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "messages": [
      {"role": "user", "content": "What is the capital of France?"}
    ]
  }'

Tu récupéreras une réponse JSON avec la réponse du modèle dans choices[0].message.content. Exactement la même forme que la réponse OpenAI.

Utiliser Python avec le SDK OpenAI

Installe le SDK si ce n'est pas déjà fait :

pip install openai

Puis utilise-le avec notre URL de base :

from openai import OpenAI

client = OpenAI(
    api_key="zub_live_YOUR_KEY",
    base_url="https://api.zubnet.ai/v1"
)

response = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain quantum computing in three sentences."}
    ],
    max_tokens=500,
    temperature=0.7
)

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

C'est un exemple complet et fonctionnel. Copie-le, colle-le, remplace la clé API, exécute-le.

Le paramètre modèle

Le champ model est où ça devient intéressant. Au lieu d'être verrouillé à un fournisseur, tu choisis parmi 367 modèles de 61 fournisseurs. Quelques exemples :

La liste complète est sur notre page des modèles, filtrable par type (LLM, image, vidéo, audio, 3D, code) et fournisseur. L'ID de modèle que tu vois là est exactement ce qui va dans le champ model.

Génération d'images

Les modèles d'images utilisent le même patron d'endpoint. Voici FLUX via Python :

response = client.images.generate(
    model="flux-1.1-pro",
    prompt="A serene Japanese garden at dawn, soft morning light",
    n=1,
    size="1024x1024"
)

image_url = response.data[0].url
print(image_url)

La réponse inclut une URL vers l'image générée hébergée sur notre CDN. Télécharge-la, affiche-la, intègre-la — l'URL est valide pour 24 heures.

Réponses en streaming

Pour les modèles de chat, le streaming envoie les tokens au fur et à mesure qu'ils sont générés au lieu d'attendre la réponse complète. C'est essentiel pour toute interface de chat utilisateur — personne ne veut fixer un écran vide pendant 10 secondes.

stream = client.chat.completions.create(
    model="claude-sonnet-4-20250514",
    messages=[
        {"role": "user", "content": "Write a short poem about code."}
    ],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Sous le capot, ça utilise Server-Sent Events (SSE). Chaque chunk arrive comme une ligne data: dans la réponse HTTP. Le SDK OpenAI gère le parsing pour toi, mais si tu utilises du HTTP brut, tu verras des lignes comme :

data: {"choices":[{"delta":{"content":"Once"},"index":0}]}
data: {"choices":[{"delta":{"content":" upon"},"index":0}]}
data: {"choices":[{"delta":{"content":" a"},"index":0}]}
...
data: [DONE]

Le flux se termine avec data: [DONE]. Parse chaque ligne, extrais delta.content, ajoute au tampon de sortie. C'est tout le protocole.

Gestion d'erreurs

L'API utilise les codes de statut HTTP standard. Voici ceux que tu rencontreras vraiment :

400 Bad Request — ton corps de requête est mal formé. Vérifie la structure JSON, assure-toi que messages est un tableau, assure-toi que model est un ID de modèle valide.

401 Unauthorized — ta clé API est manquante, invalide ou expirée. Vérifie l'en-tête Authorization: Bearer.

403 Forbidden — ton compte n'a pas accès à ce modèle ou à cette fonction. Vérifie le niveau d'abonnement de ton espace de travail.

429 Too Many Requests — tu as atteint la limite de débit. La réponse inclut un en-tête Retry-After te disant combien de secondes attendre. Implémente un backoff exponentiel :

import time
from openai import RateLimitError

max_retries = 3
for attempt in range(max_retries):
    try:
        response = client.chat.completions.create(
            model="claude-sonnet-4-20250514",
            messages=[{"role": "user", "content": "Hello"}]
        )
        break
    except RateLimitError:
        wait = 2 ** attempt
        print(f"Rate limited. Waiting {wait}s...")
        time.sleep(wait)

500 / 502 / 503 — problèmes côté serveur. Ils sont rares mais ça arrive. Réessaie avec backoff. Si persistants, vérifie notre page de statut Pulse.

Détails d'authentification

Chaque requête a besoin d'un en-tête Authorization :

Authorization: Bearer zub_live_YOUR_KEY

La clé est attachée à ton espace de travail. Tous les membres d'équipe dans le même espace de travail partagent la même clé et le même pool d'usage. Si tu as besoin d'un suivi séparé par membre d'équipe, crée des espaces de travail séparés.

Limites de débit

Les limites de débit dépendent de ton niveau de plan. Les défauts sont généreux pour la plupart des cas d'usage :

• Requêtes par minute : varie par plan (60 à 600 RPM)
• Tokens par minute : varie par modèle et plan
• Requêtes concurrentes : pas de limite dure, mais des 429 se déclencheront si tu burst trop agressivement

Les en-têtes de limite de débit sont inclus dans chaque réponse :

x-ratelimit-limit-requests: 120
x-ratelimit-remaining-requests: 119
x-ratelimit-reset-requests: 0.5s

Lis ces en-têtes. Construis ton client pour les respecter. Tes utilisateurs te remercieront quand leurs requêtes n'échoueront pas aléatoirement.

Mettre tout ensemble

Voici une fonction Python prête pour la production qui gère les erreurs, les retries et le streaming :

import os
from openai import OpenAI, APIError, RateLimitError
import time

client = OpenAI(
    api_key=os.environ["ZUBNET_API_KEY"],
    base_url="https://api.zubnet.ai/v1"
)

def ask(prompt, model="claude-sonnet-4-20250514", stream=False):
    for attempt in range(3):
        try:
            response = client.chat.completions.create(
                model=model,
                messages=[{"role": "user", "content": prompt}],
                stream=stream
            )
            if stream:
                return response  # iterate over chunks
            return response.choices[0].message.content
        except RateLimitError:
            time.sleep(2 ** attempt)
        except APIError as e:
            if attempt == 2:
                raise
            time.sleep(1)

# Usage
print(ask("Summarize the latest in quantum computing"))
print(ask("Same question, different model", model="gpt-4.1"))

Change de modèle en changeant une chaîne. Pas de refactoring de code, pas de nouvelles dépendances, pas de format de réponse différent. C'est tout le but de la compatibilité OpenAI.

---

Tous les exemples de code dans ce guide sont testés et fonctionnels en date de mars 2026. Copie-les, exécute-les, construis dessus. C'est à ça qu'ils servent.

Prêt à commencer ? Obtiens ta clé API sur zubnet.com