GPT Image 2 / 2.5 : génération et édition d'images

Choisissez le point de terminaison avant d'écrire la requête : le texte-vers-image utilise /images/generations ; l'image-vers-image utilise /images/edits avec des fichiers image téléversés. Mentionner « image de référence 1 » dans un prompt ne joint pas d'image.

Modèles et points de terminaison

ID de modèle	Texte-vers-image	Image-vers-image
gpt-image-2	/images/generations	/images/edits + fichiers image
gpt-image-2.5-sunburst	/images/generations	/images/edits + fichiers image
gpt-image-2.5-flare	/images/generations	/images/edits + fichiers image

Ce sont des ID de modèles distincts. Modifiez explicitement model lorsque vous changez de modèle ; GPT Image 2.5 n'est pas un alias de GPT Image 2. Consultez la disponibilité actuelle et les tarifs du compte sur le marché.

Opération	Méthode et point de terminaison	Format de requête
Texte-vers-image	POST https://apimaster.ai/v1/images/generations	JSON
Image-vers-image / édition	POST https://apimaster.ai/v1/images/edits	multipart/form-data avec de vrais fichiers image
Édition d'image asynchrone	POST https://apimaster.ai/v1/images/edits/async	Mêmes fichiers multipart que pour les éditions ; renvoie un ID de tâche
Texte-vers-image asynchrone	POST https://apimaster.ai/v1/images/generations/async	JSON ; renvoie un ID de tâche
Interroger une tâche	GET https://apimaster.ai/v1/tasks/{task_id}?model=MODEL_ID	Authentification Bearer

Pour une réponse de tâche issue de l'édition d'images, utilisez /images/edits/async. Téléversez les mêmes fichiers et champs que pour les éditions synchrones, puis interrogez /tasks/{task_id}. Ne déplacez pas une requête d'édition vers generations/async. Ces points de terminaison de tâche réutilisent le contrat asynchrone existant : un fournisseur amont asynchrone peut renvoyer sa tâche rapidement, tandis qu'un fournisseur amont synchrone peut terminer l'édition avant que la passerelle ne renvoie un ID de tâche. Ils ne constituent pas une promesse d'exécution immédiate en arrière-plan. N'utilisez pas Chat Completions pour ces modèles.

Authentification et délais d'attente

Créez une clé API et envoyez Authorization: Bearer YOUR_API_KEY. Les requêtes de génération JSON utilisent Content-Type: application/json. Pour les téléversements de fichiers, laissez cURL ou votre bibliothèque HTTP générer la frontière multipart ; ne définissez pas manuellement l'en-tête Content-Type.

Prévoyez au moins 180 secondes pour les requêtes de base, 300 secondes pour les résolutions plus élevées et 600 secondes pour les éditions exigeantes ou la haute qualité. Un délai d'attente côté client ne prouve pas que la requête amont s'est arrêtée. Évitez les soumissions dupliquées immédiates.

Texte-vers-image : génération JSON

curl --fail-with-body --max-time 300 "https://apimaster.ai/v1/images/generations" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A watercolor orange cat sitting on a windowsill at sunset",
    "n": 1,
    "size": "1024x1024"
  }'

Pour Sunburst ou Flare, remplacez l'ID de modèle par gpt-image-2.5-sunburst ou gpt-image-2.5-flare. N'ajoutez pas d'images de référence à cet exemple ; utilisez les exemples d'édition ci-dessous.

Image-vers-image : téléverser une référence

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Change only the background to pale mint green. Preserve the subject, lettering and layout of the reference image." \
  -F "n=1" \
  -F "size=1024x1024" \
  -F "image=@reference.png;type=image/png"

Remplacez reference.png par une image locale existante. Le @ indique à cURL de téléverser les octets du fichier ; image=reference.png n'envoie qu'une simple chaîne de nom de fichier. Ce schéma de point de terminaison s'applique également à gpt-image-2 et gpt-image-2.5-sunburst.

Image-vers-image : téléverser plusieurs références

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Create one comic page. Reference 1 defines character A, reference 2 defines character B, and reference 3 defines the setting. Preserve each character's appearance." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

Répétez le même champ image[] pour chaque fichier, dans l'ordre décrit par le prompt. n est le nombre d'images en sortie, pas le nombre de références. Les limites de références dépendent du modèle sélectionné et de la route disponible ; ne présumez pas d'une limite universelle de 16 images. Commencez avec une seule référence et n=1, puis ajoutez des entrées selon vos besoins.

Exemple d'édition en Python

Installez requests. Cet exemple téléverse un vrai fichier et gère à la fois les réponses d'images sous forme d'URL et de base64.

import base64
import os
from pathlib import Path
import requests

api = "https://apimaster.ai/v1"
headers = {"Authorization": "Bearer " + os.environ["APIMASTER_API_KEY"]}
with open("reference.png", "rb") as image:
    response = requests.post(
        f"{api}/images/edits",
        headers=headers,
        data={
            "model": "gpt-image-2.5-flare",
            "prompt": "Change only the background to pale mint green. Preserve the subject and lettering.",
            "n": 1,
            "size": "1024x1024",
        },
        files={"image": ("reference.png", image, "image/png")},
        timeout=(20, 600),
    )
response.raise_for_status()
item = response.json()["data"][0]
if item.get("b64_json"):
    Path("result.png").write_bytes(base64.b64decode(item["b64_json"]))
elif item.get("url"):
    print(item["url"])
else:
    raise RuntimeError("No image returned: " + str(response.json()))

Pour plusieurs fichiers, passez une liste d'entrées ("image[]", (filename, file_object, mime_type)) répétées à files. Gardez chaque fichier ouvert jusqu'à la fin de la requête.

Édition d'images asynchrone

Utilisez ce point de terminaison avec GPT Image 2, Sunburst ou Flare lorsque votre application consomme des ID de tâches. Les règles de téléversement de fichiers, l'ordre des références, les limites de capacités et l'authentification sont les mêmes que pour les éditions synchrones.

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/edits/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-flare" \
  -F "prompt=Combine the three reference images into one poster, preserving their subjects and order." \
  -F "n=1" \
  -F "image[]=@character-a.png;type=image/png" \
  -F "image[]=@character-b.png;type=image/png" \
  -F "image[]=@setting.png;type=image/png"

La soumission renvoie data[0].task_id. Interrogez en utilisant le même ID de modèle :

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2.5-flare" \
  -H "Authorization: Bearer YOUR_API_KEY"

Une tâche suivie terminée a cette forme ; chaque image générée est incluse :

{
  "data": {
    "status": "succeeded",
    "result": {
      "images": [{"url": "https://your-image-host.example/result.png"}]
    }
  }
}

La tâche appartient au compte soumissionnaire. Interrogez-la avec une clé API valide pour ce compte. Une soumission échouée renvoie une erreur plutôt qu'une tâche exploitable ; une fois qu'un ID de tâche a été renvoyé, continuez à interroger cette tâche au lieu de soumettre à nouveau l'édition. Consultez le tableau des statuts de sondage ci-dessous.

Intégrations URL ou base64 existantes

Si votre entrée est une URL, téléchargez l'image dans votre application et téléversez ses octets vers /images/edits. S'il s'agit d'un URI de données base64, décodez la charge utile dans un fichier ou un tampon d'octets et téléversez-le. Ne soumettez pas l'URL ou le texte base64 comme s'il s'agissait d'un téléversement de fichier.

Certaines routes GPT Image 2 prennent en charge l'extension image_urls sur generations. Ce n'est pas un contrat d'édition d'image portable et il ne faut pas supposer que cela fonctionne avec GPT Image 2.5. Les nouvelles intégrations doivent utiliser les exemples d'éditions multipart ci-dessus. Une requête JSON contenant image_urls, image ou images n'est pas équivalente au téléversement de fichiers vers edits.

Paramètres et limites de capacités

Champ	Utilisation
model	Obligatoire ; utilisez un ID de modèle exact du tableau ci-dessus
prompt	Obligatoire ; décrivez le résultat et l'ordre des références
image / image[]	Fichiers réellement téléversés pour les éditions ; utilisez PNG ou JPEG pour les exemples de base
n	Nombre d'images en sortie ; commencez avec 1 ; le maximum dépend de la route
size	Optionnel ; 1024x1024 est l'exemple de base ; les autres dimensions en pixels ou ratios d'aspect dépendent de la route
resolution	Extension optionnelle spécifique à la route telle que 1k, 2k, 4k ; chaque modèle/route ne prend pas en charge chaque niveau
quality	Optionnel ; les valeurs acceptées et le coût dépendent de la route
background, output_format, output_compression	Optionnels ; la transparence et l'encodage de sortie nécessitent la prise en charge par la route
mask	GPT Image 2 uniquement, lorsqu'une route d'édition disponible prend en charge les masques téléversés ; non pris en charge par le gestionnaire multipart actuel de GPT Image 2.5

Pour GPT Image 2, la prise en charge des masques doit être vérifiée séparément de l'édition ordinaire par références. Un masque PNG compatible doit correspondre aux dimensions de l'entrée et inclure un canal alpha. Le point de terminaison multipart actuel de GPT Image 2.5 rejette les fichiers de masque téléversés ; n'ajoutez pas de masque aux exemples Sunburst ou Flare ci-dessus. Ne présumez pas qu'une solution de contournement mask_url en JSON est prise en charge sans vérifier la route choisie.

N'envoyez que les champs optionnels dont vous avez besoin. Ils peuvent modifier les routes éligibles et le prix ; définir explicitement une valeur par défaut n'est pas toujours équivalent à l'omettre. Aucun tableau fixe de tailles en pixels ni liste de paramètres avancés ne s'applique uniformément aux trois ID de modèles. Les tarifs réels et les capacités prises en charge suivent le marché et la réponse de la requête.

Réponses synchrones

Une génération ou une édition réussie renvoie des entrées d'images dans data :

{
  "created": 1789890000,
  "data": [{"url": "https://your-image-host.example/result.png"}]
}

Selon la route et le format de sortie, une entrée peut plutôt contenir b64_json. Décodez-le en octets d'image. Téléchargez rapidement les URL de résultats temporaires. Une réponse HTTP 200 ou un nombre d'images seul ne prouve pas que les détails des références ont été préservés ; inspectez le résultat par rapport à l'entrée.

Tâches asynchrones : soumission et sondage

Pour le texte-vers-image, soumettez du JSON sans images de référence à generations/async. Pour l'édition d'images, utilisez l'exemple multipart edits/async ci-dessus. Les deux utilisent le même point de terminaison de requête de tâche :

curl --fail-with-body --max-time 600 "https://apimaster.ai/v1/images/generations/async" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-image-2","prompt":"A watercolor cat on the moon","n":1}'

{
  "code": 200,
  "data": [{"status": "submitted", "task_id": "task_EXAMPLE"}]
}

L'enveloppe de soumission rapporte normalement submitted ; un fournisseur amont peut déjà rapporter un état d'achèvement. Le premier sondage peut déjà être terminé. Un ID de tâche ne garantit pas une réponse immédiate : si le fournisseur amont sélectionné est synchrone, la plateforme attend la fin de la génération avant de renvoyer la tâche. Maintenez un délai d'attente de soumission suffisant.

Sondez avec le même ID de modèle utilisé pour la soumission :

curl --fail-with-body "https://apimaster.ai/v1/tasks/TASK_ID?model=gpt-image-2" \
  -H "Authorization: Bearer YOUR_API_KEY"

Statut de la tâche	Action
pending, submitted, processing, in_progress	Attendre ; interroger à nouveau après 3 à 5 secondes
succeeded, success, completed	Lire chaque entrée dans data.result.images ; les tâches suivies utilisent un url sous forme de chaîne, tandis que les réponses amont héritées peuvent utiliser un tableau d'URL
failed, error, cancelled	Arrêter le sondage et examiner l'erreur

Utilisez un délai global de sondage fini, par exemple 10 minutes. S'il expire, conservez l'ID de tâche pour des vérifications ultérieures au lieu de créer automatiquement une autre tâche payante. Les réponses de requête de tâche et les réponses d'images synchrones ont des structures différentes.

Dépannage des images de référence

1. Vérifiez que le chemin de requête réel est /v1/images/edits ou /v1/images/edits/async, et non generations ou generations/async.
2. Vérifiez que le multipart contient des octets de fichier sous image ou image[] répété, avec une frontière générée. Le texte du prompt, les noms de fichiers et le nombre de références ne remplacent pas les fichiers.
3. Vérifiez l'ID de modèle exact. Une extension GPT Image 2 n'est pas automatiquement prise en charge par Sunburst ou Flare.
4. Si les détails de tâche/journal ne montrent aucun aperçu, ne concluez pas qu'aucune image n'a été envoyée : les journaux peuvent omettre les données base64 et le contenu des fichiers téléversés. Inversement, un nombre de références journalisé n'établit pas qu'un fournisseur amont a utilisé les images.
5. Testez avec une référence simple contenant un lettrage ou des formes distinctives, et demandez un changement d'arrière-plan sans décrire ces détails. Comparez la sortie visuellement.
6. Pour le support, conservez l'ID de requête (X-Oneapi-Request-Id), l'ID de tâche s'il existe, le modèle, le point de terminaison, l'horodatage, les champs de requête assainis et les images de référence. Ne partagez jamais votre clé API.

Pour une réponse 400, examinez la compatibilité du point de terminaison et des paramètres ; 401 indique un échec d'authentification ; 429 indique une limite de débit/quota. Pour les délais d'attente ou les échecs amont, conservez l'ID de requête/tâche et vérifiez la tâche ou l'enregistrement d'utilisation existant avant de soumettre à nouveau.