API GPT Image 2.5 en Python : un exemple fonctionnel

Pour appeler l’API GPT Image 2.5 en Python, envoyez une requête POST à https://api.seedrouter.ai/v1/images/generations avec un ID de modèle comme gpt-image-2.5-flare et un prompt, conservez l’id de tâche renvoyé dans la réponse, puis interrogez GET /v1/tasks/{id} jusqu’à ce que le statut soit completed. La tâche terminée contient les URL de vos images. Le même point de terminaison gère la génération à partir de texte, les retouches avec référence et les retouches avec masque.

Ce guide présente un parcours complet et exécutable en Python, avec l’équivalent JavaScript, suivi des erreurs les plus fréquentes et de ce que chacune signifie.

De quoi avez-vous besoin avant la première requête ?

Deux choses : une clé API et un ID de modèle.

Créez une clé sur la page Clés API et conservez-la dans une variable d’environnement sur votre serveur, jamais dans du code navigateur :

export SEEDROUTER_API_KEY="your-key"

Choisissez ensuite l’un des quatre ID de modèle GPT Image 2.5. Copiez-les exactement ; il n’existe pas d’ID gpt-image-2.5 seul.

Si vous ne savez pas par quel modèle commencer, utilisez Flare ; Flare vs Sunburst explique quand Sunburst en vaut la peine.

Comment générer une image avec l’API GPT Image 2.5 en Python ?

L’envoi répond immédiatement. La réponse est une référence de tâche, pas l’image.

import os
import requests

response = requests.post(
    "https://api.seedrouter.ai/v1/images/generations",
    headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
    json={
        "model": "gpt-image-2.5-flare",
        "prompt": "An amber glass bottle on a cream background, studio lighting",
        "size": "1024x1024",
        "quality": "low",
    },
    timeout=60,
)
response.raise_for_status()
task_id = response.json()["id"]

Enregistrez task_id avant toute autre chose. C’est votre seul moyen d’accéder au travail que vous venez de payer, et c’est ce qui vous permet de reprendre si votre processus redémarre pendant le rendu de l’image.

Comment récupérer l’image ?

Interrogez la tâche toutes les quelques secondes jusqu’à ce qu’elle se termine. Cette boucle attend jusqu’à dix minutes ; atteindre ce délai arrête votre boucle, pas la tâche.

import time

print(f"Task ID: {task_id}")
deadline = time.monotonic() + 600
while time.monotonic() < deadline:
    result = requests.get(
        f"https://api.seedrouter.ai/v1/tasks/{task_id}",
        headers={"Authorization": f"Bearer {os.environ['SEEDROUTER_API_KEY']}"},
        timeout=30,
    )
    result.raise_for_status()
    task = result.json()
    if task["status"] == "completed":
        for image in task["output"]["data"]:
            print(image["url"])
        break
    if task["status"] == "failed":
        raise RuntimeError(task["error"]["message"])
    time.sleep(3)
else:
    raise TimeoutError(f"Still waiting. Resume polling task {task_id}.")

Téléchargez les URL que vous voulez garder et stockez-les vous-même. Les URL de résultat servent à la livraison, pas au stockage à long terme.

À quoi ressemble le même appel en JavaScript ?

La requête est identique ; seul le client HTTP change. Exécutez-la sur votre serveur pour que la clé n’atteigne jamais un navigateur.

const response = await fetch('https://api.seedrouter.ai/v1/images/generations', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SEEDROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'gpt-image-2.5-flare',
    prompt: 'An amber glass bottle on a cream background, studio lighting',
    size: '1024x1024',
    quality: 'low',
  }),
});
if (!response.ok) throw new Error(`Request failed: ${response.status}`);
const { id: taskId } = await response.json();

Interrogez GET https://api.seedrouter.ai/v1/tasks/${taskId} avec le même en-tête, exactement comme dans la boucle Python.

Comment retoucher une image existante ?

Ajoutez des images de référence à la même requête. Il n’y a ni point de terminaison de retouche séparé ni champ de mode : envoyer images en fait une retouche, et ajouter un mask limite la modification à une zone.

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Make the bottle blue. Preserve the composition and lighting.",
  "images": [{"image_url": "https://example.com/reference.png"}],
  "mask": {"image_url": "https://example.com/mask.png"}
}

Les entrées doivent être des URL HTTPS publiques. Vous pouvez envoyer jusqu’à 16 images de référence en PNG, JPEG ou WebP, de moins de 50 Mo chacune. Le masque est un PNG de moins de 4 Mo, de la même taille que la première image de référence, et sa zone transparente indique ce qu’il faut modifier. Les chaînes base64, les URL data: et les envois de fichiers sont refusés : déposez d’abord vos fichiers sur votre propre stockage et envoyez les URL.

Pourquoi l’API indique-t-elle que le modèle n’est pas disponible ?

Le code d’erreur 20002 avec HTTP 400 (« The requested model is not available. ») signifie que la valeur de model n’est pas un ID servi par l’API. La cause habituelle est une quasi-erreur : gpt-image-2.5 sans niveau, gpt-image-2-5-flare avec un tiret à la place du point, ou une faute de frappe dans sunburst. Copiez un ID depuis le tableau ci-dessus.

Les erreurs de paramètres sont signalées avant la vérification du modèle. Si une requête contient aussi un champ invalide, vous recevez 20001 avec un message qui nomme le champ, par exemple quality. Corrigez-le d’abord ; l’erreur de modèle apparaît à l’essai suivant si l’ID est toujours faux.

Une tâche peut aussi échouer après avoir été acceptée. Cette requête d’interrogation renvoie quand même HTTP 200, avec status: "failed" et un objet error comme le code 60001 (politique de contenu) ou 60002 (échec de la génération). Les tâches échouées ne sont pas facturées. Le catalogue des erreurs liste chaque code, y compris les erreurs de solde et de limite de débit, avec l’étape suivante pour chacun.

Questions fréquentes

Existe-t-il un appel officiel du SDK Python qui renvoie directement l’image ?

Pas sur cette API. La livraison est asynchrone : vous envoyez toujours la requête, conservez l’identifiant de tâche et interrogez. stream et partial_images ne sont pas pris en charge.

Puis-je demander plusieurs images à la fois ?

Oui. Réglez n entre 1 et 10. La tâche terminée liste une URL par image livrée, et vous êtes facturé pour les images livrées.

Comment obtenir un PNG transparent ?

Réglez background sur transparent et output_format sur png. Le JPEG n’a pas de canal alpha : cette combinaison est donc refusée avant l’exécution.

Construisez l’intégration autour de l’identifiant de tâche

Enregistrez l’identifiant de tâche dès que vous le recevez, interrogez avec un délai maximal, et traitez un dépassement de délai d’interrogation comme « toujours en cours » plutôt que comme « échoué ». Tout le reste, y compris chaque champ et chaque limite, se trouve dans la référence de l’API GPT Image 2.5, et vous pouvez essayer une requête sans code dans le Playground.