API OpenAI Images Edits : Demande et utilisation

Le service d’édition d’images OpenAI permet de transmettre un nombre arbitraire d’images et d’instructions, et de recevoir en sortie des images modifiées. Actuellement, l’API supporte simultanément dall-e-2, gpt-image-1, le dernier modèle gpt-image-2, ainsi que la série de modèles nano-banana / nano-banana-2 / nano-banana-pro accessibles via la même interface. Ce document présente principalement le processus d’utilisation de l’API OpenAI Images Edits, qui permet d’utiliser facilement les fonctionnalités officielles d’édition d’images OpenAI.

Processus de demande

Pour utiliser l’API OpenAI Images Edits, rendez-vous d’abord sur la page OpenAI Images Edits API et cliquez sur le bouton « Acquire » pour obtenir les identifiants nécessaires à la requête :

Si vous n’êtes pas connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion pour vous inscrire et vous connecter. Après inscription et connexion, vous serez automatiquement ramené sur cette page. Lors de la première demande, un quota gratuit est offert, permettant d’utiliser cette API gratuitement.

Modèle GPT-Image-2

gpt-image-2 offre des améliorations très nettes par rapport à gpt-image-1 dans le contexte de l’édition d’images :

Maintien plus stable de la structure : lors du changement de peau, de palette de couleurs ou d’arrière-plan, la mise en page et la composition originales sont presque intactes.
Conservation plus précise du texte : les images contenant du texte (infographies, affiches, menus) conservent un texte clair et lisible après édition.
Support du passage direct d’URL : en plus du traditionnel téléchargement de fichiers en multipart/form-data, gpt-image-2 supporte également l’envoi d’URL d’image au format JSON, sans besoin de télécharger l’image localement, idéal pour une intégration côté serveur.
Support du rééchantillonnage haute résolution : il est possible de fournir une image originale 1K et de demander une sortie 2K ou 4K via le paramètre size, le modèle effectuant l’agrandissement lors de l’édition.

Valeurs supportées pour `size` et niveaux de tarification

Les contraintes sur size sont identiques à celles de l’API de génération : gpt-image-2 accepte size à auto, vide, ou au format WIDTHxHEIGHT. Toute autre forme renvoie une erreur 400. La tarification se divise en deux niveaux, indépendamment de la résolution d’origine, basée uniquement sur la valeur de size demandée :

Prix standard 1K : toute dimension recommandée 1K dans le tableau ci-dessous, ou alias courant 1K (1254x1254, 1672x941, 941x1672).
Autres niveaux (×1.5) : dimensions recommandées 2K / 4K dans le tableau, ou toute valeur personnalisée WIDTHxHEIGHT.

Les contraintes en amont sur les dimensions personnalisées s’appliquent également : largeur et hauteur multiples de 16, côté long ≤ 3840, pixels totaux ≤ 8 294 400.

Ratio	1K (prix standard)	2K recommandé (×1.5)	4K recommandé (×1.5)
1:1	`1024x1024`	`2048x2048`	`2880x2880`
4:3	`1536x1024`	`2048x1536`	`3264x2448`
3:4	`1024x1536`	`1536x2048`	`2448x3264`
16:9	`1792x1024`	`2048x1152`	`3840x2160`
9:16	`1024x1792`	`1152x2048`	`2160x3840`

Par exemple : pour une image originale 1024x1024, si size est 2048x2048, le modèle rééchantillonne et édite en 2K, facturé au niveau « autre » ; si size est 3840x2160, la sortie est en 4K paysage, facturée aussi au niveau « autre » ; si size est auto ou omis, la facturation est au prix standard 1K.

À propos du paramètre n L’API d’édition gpt-image-2 ne supporte pas n > 1 : ce paramètre est silencieusement ignoré, que vous passiez n=1 ou n=10, une seule image est retournée par requête et facturée comme telle. Pour obtenir plusieurs résultats candidats, il faut lancer plusieurs requêtes en parallèle. Cette limitation s’applique aussi à gpt-image-1 / gpt-image-1.5 et à la série nano-banana. Seul dall-e-2 supporte nativement n > 1.

Voici deux exemples concrets illustrant les capacités d’édition de gpt-image-2.

Mode d’appel 1 : JSON + URL d’image (recommandé)

Envoyez directement une requête en application/json avec le champ image contenant l’URL d’une image, le modèle la récupérera et éditera selon le prompt. Par exemple, l’image originale ci-dessous est une infographie générée avec gpt-image-2 :

Nous souhaitons la convertir en mode nuit. Voici comment appeler l’API :

curl -X POST "https://api.xhuoapi.ai/v1/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "image": "https://platform.cdn.xhuoapi.ai/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png",
    "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
    "size": "1024x1536"
  }'

Ou en Python :

import requests

url = "https://api.xhuoapi.ai/v1/openai/images/edits"

headers = {
    "accept": "application/json",
    "authorization": "Bearer {token}",
    "content-type": "application/json"
}

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.xhuoapi.ai/gpt-image/5c9fa635-8794-4c6d-88f8-584d7f4716c6_0.png",
    "prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
    "size": "1024x1536"
}

response = requests.post(url, json=payload, headers=headers)
print(response.text)

La réponse est la suivante :

{
  "success": true,
  "task_id": "cb104e35-af1f-45be-9fac-b62e2b256753",
  "trace_id": "3e5c77c6-6c2e-4bba-a42d-98ea049b58a8",
  "created": 1777048863,
  "data": [
    {
      "revised_prompt": "Convert this infographic to dark mode: dark navy background, light cream text, deep gray rounded module cards with soft shadows. Keep all layout, structure, and module arrangement identical — only invert the color scheme.",
      "url": "https://platform.cdn.xhuoapi.ai/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png"
    }
  ],
  "elapsed": 83.859
}

L’image éditée est la suivante :

On constate que la structure des modules, la répartition des informations et la typographie sont strictement conservées, seule la palette de couleurs a été inversée pour un thème sombre.

Astuce : le champ image accepte aussi un tableau, par exemple "image": ["url1", "url2", "url3"], jusqu’à 16 images de référence simultanées, permettant au modèle de s’inspirer de plusieurs images pour l’édition.

Mode d’appel 2 : JSON + plusieurs images de référence

gpt-image-2 supporte la prise en compte simultanée de plusieurs images pour générer le résultat final, par exemple pour combiner plusieurs photos de produits dans un panier cadeau :

payload = {
    "model": "gpt-image-2",
    "image": [
        "https://example.com/item1.png",
        "https://example.com/item2.png",
        "https://example.com/item3.png"
    ],
    "prompt": "Combine all the items above into a single 'Relax & Unwind' gift basket on a clean white background, photorealistic, soft natural lighting.",
    "size": "1024x1024"
}

Exemple de scénario : changement de style + maintien de la structure

Voici un autre exemple, où une étagère en bois est remplacée par une étagère flottante moderne, tout en conservant strictement le nombre et l’arrangement des livres sur chaque niveau. Image originale (étagère en bois générée avec gpt-image-2) :

Requête :

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.xhuoapi.ai/gpt-image/141970f0-65fb-4ec8-ab7d-9be173641350_0.png",
    "prompt": "Replace the wooden bookshelf with a sleek modern white floating shelf mounted on a pastel blue wall. Keep the exact same arrangement of books (1 book on top, 3 in middle, 7 on bottom). Add a small potted succulent on the top shelf next to the book. Bright airy daylight from the left.",
    "size": "1024x1024"
}

Résultat d’édition (task_id: e9544dba-727e-44a2-81e1-223d49869380) :

Le style et l’environnement ont été entièrement remplacés selon le prompt, mais le nombre de livres par étage (1 / 3 / 7) est strictement conservé, et une petite plante succulente a été ajoutée comme demandé.

Mode d’appel 3 : multipart/form-data (compatible OpenAI SDK)

Si vous utilisez déjà le SDK Python officiel OpenAI, la méthode d’upload en multipart/form-data est toujours valide, il suffit de changer model en gpt-image-2 :

import base64
from openai import OpenAI
client = OpenAI()

result = client.images.edit(
    model="gpt-image-2",
    image=[open("test.png", "rb")],
    prompt="Convert this image to dark mode while keeping the layout intact."
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)
with open("edited.png", "wb") as f:
    f.write(image_bytes)

Lors de l’utilisation du SDK, il faut d’abord définir deux variables d’environnement : OPENAI_BASE_URL à https://api.xhuoapi.ai/v1/openai et OPENAI_API_KEY à votre token obtenu :

export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai
export OPENAI_API_KEY={token}

Série de modèles Nano Banana

La série nano-banana est également accessible via /openai/images/edits en changeant simplement le paramètre model par l’un des modèles suivants :

Modèle	Tarification (Crédits / requête)	Cas d’usage
`nano-banana`	0.14	Édition d’image classique, la plus rapide et économique
`nano-banana-2`	0.28	Qualité et détails nettement améliorés
`nano-banana-pro`	0.35	Modèle phare, meilleure conservation de la structure, du texte et du style

Important : portée des paramètres supportés Nano Banana, via une couche d’adaptation, supporte uniquement les paramètres : model, prompt, image.

image peut être uploadé en multipart/form-data (converti en interne en data:<mime>;base64,... pour l’upstream) ou passé en chaîne URL dans un champ formulaire.

Les paramètres mask, n, size, response_format ne sont pas supportés et seront ignorés.

La structure de réponse suit le format OpenAI (data[].url), mais created est toujours 0, pas de b64_json, et revised_prompt est toujours égal au prompt original.

Appel via formulaire + URL d’image

curl -X POST "https://api.xhuoapi.ai/v1/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=nano-banana" \
  -F "prompt=add a green leaf on top of the apple" \
  -F "image=https://platform.cdn.xhuoapi.ai/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png"

Réponse :

{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.xhuoapi.ai/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg",
      "revised_prompt": "add a green leaf on top of the apple"
    }
  ]
}

Image éditée :

Appel via formulaire + fichier local

import requests

url = "https://api.xhuoapi.ai/v1/openai/images/edits"

headers = {
    "authorization": "Bearer {token}"
}

files = {
    "image": open("apple.png", "rb"),
}
data = {
    "model": "nano-banana-pro",
    "prompt": "add a green leaf on top of the apple"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.text)

Callback asynchrone

Le mécanisme de callback asynchrone via callback_url fonctionne aussi avec nano-banana, le processus est identique aux autres modèles, voir la section Callback asynchrone ci-dessous.

Utilisation basique

Voici un exemple d’appel via CURL :

curl -s -D >(grep -i x-request-id >&2) \
  -o >(jq -r '.data[0].b64_json' | base64 --decode > gift-basket.png) \
  -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[][email protected]" \
  -F 'prompt=Create a lovely gift basket with these this items in it'

Lors de la première utilisation de cette API, il faut renseigner au minimum quatre éléments : le champ authorization (sélectionnable dans la liste déroulante), le paramètre model (choix du modèle OpenAI, ici un seul modèle principal disponible, voir la liste fournie), le paramètre prompt (texte décrivant l’image à générer), et enfin image (chemin vers l’image à éditer). L’image à éditer est illustrée ci-dessous :

Exemple Python équivalent :

import base64
from openai import OpenAI
client = OpenAI()

prompt = """
Generate a photorealistic image of a gift basket on a white background 
labeled 'Relax & Unwind' with a ribbon and handwriting-like font, 
containing all the items in the reference pictures.
"""

result = client.images.edit(
    model="gpt-image-1",
    image=[
        open("test.png", "rb")
    ],
    prompt=prompt
)

image_base64 = result.data[0].b64_json
image_bytes = base64.b64decode(image_base64)

# Enregistrer l’image dans un fichier
with open("gift-basket.png", "wb") as f:
    f.write(image_bytes)

Pour utiliser Python, il faut d’abord définir deux variables d’environnement : OPENAI_BASE_URL à https://api.xhuoapi.ai/v1/openai et OPENAI_API_KEY à votre token obtenu dans authorization. Sous Mac OS, vous pouvez définir ces variables avec :

export OPENAI_BASE_URL=https://api.xhuoapi.ai/v1/openai
export OPENAI_API_KEY={token} 

Après appel, une image gift-basket.png sera générée dans le répertoire courant, comme illustré ci-dessous :

Ainsi, l’édition d’image est réalisée. L’API Edits supporte actuellement trois modèles : dall-e-2, gpt-image-1 et gpt-image-2, ce dernier étant recommandé, voir la section Modèle GPT-Image-2.

Callback asynchrone

L’édition d’image via OpenAI Images Edits API peut prendre un certain temps. Si l’API ne répond pas rapidement, la connexion HTTP reste ouverte, consommant des ressources système supplémentaires. Pour pallier cela, l’API propose un support de callback asynchrone. Le processus est le suivant : le client ajoute un champ callback_url lors de la requête. L’API répond immédiatement avec un task_id identifiant la tâche. Une fois l’édition terminée, le résultat est envoyé en POST JSON à l’URL callback_url fournie, incluant aussi le task_id pour faire le lien avec la requête initiale. Voici un exemple pratique. Un webhook est un service HTTP capable de recevoir des requêtes. Le développeur doit remplacer l’URL par celle de son propre serveur HTTP. Pour la démonstration, on utilise le site public https://webhook.site/, qui fournit un URL webhook unique, comme montré ci-dessous :

Copiez cette URL, par exemple https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab, et utilisez-la comme webhook. Ensuite, ajoutez le champ callback_url dans la requête avec cette URL, par exemple :

curl -X POST "https://api.xhuoapi.ai/v1/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[][email protected]" \
  -F "prompt=Create a lovely gift basket with these items in it" \
  -F "callback_url=https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab"

La réponse immédiate contient un task_id :

{
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c"
}

Après un court délai, vous pouvez consulter le webhook pour voir le résultat de l’édition, par exemple :

{
  "success": true,
  "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c",
  "trace_id": "9b4b1ff3-90f2-470f-b082-1061ec2948cc",
  "data": {
    "created": 1721626477,
    "data": [
      {
        "b64_json": "iVBORw0KGgo..."
      }
    ]
  }
}

On retrouve le champ task_id et les données d’image au format base64, identiques à un appel synchrone, permettant d’associer les résultats à la tâche.

Gestion des erreurs

Lors d’un appel API, en cas d’erreur, un code et un message d’erreur sont retournés, par exemple :

400 token_mismatched : requête incorrecte, paramètres manquants ou invalides.
400 api_not_implemented : requête incorrecte, paramètres manquants ou invalides.
401 invalid_token : non autorisé, token d’authentification invalide ou absent.
429 too_many_requests : trop de requêtes, limite de débit dépassée.
500 api_error : erreur interne serveur.

Exemple de réponse d’erreur

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}

Conclusion

Ce document vous a présenté comment utiliser l’API OpenAI Images Edits pour exploiter facilement les fonctionnalités officielles d’édition d’images OpenAI. Nous espérons qu’il vous aidera à mieux intégrer et utiliser cette API. Pour toute question, n’hésitez pas à contacter notre équipe de support technique.

Documentation Index

​Processus de demande

​Modèle GPT-Image-2

​Valeurs supportées pour size et niveaux de tarification

​Mode d’appel 1 : JSON + URL d’image (recommandé)

​Mode d’appel 2 : JSON + plusieurs images de référence

​Exemple de scénario : changement de style + maintien de la structure

​Mode d’appel 3 : multipart/form-data (compatible OpenAI SDK)

​Série de modèles Nano Banana

​Appel via formulaire + URL d’image

​Appel via formulaire + fichier local

​Callback asynchrone

​Utilisation basique

​Callback asynchrone

​Gestion des erreurs

​Exemple de réponse d’erreur

​Conclusion

Processus de demande

Modèle GPT-Image-2

Valeurs supportées pour `size` et niveaux de tarification

Mode d’appel 1 : JSON + URL d’image (recommandé)

Mode d’appel 2 : JSON + plusieurs images de référence

Exemple de scénario : changement de style + maintien de la structure

Mode d’appel 3 : multipart/form-data (compatible OpenAI SDK)

Série de modèles Nano Banana

Appel via formulaire + URL d’image

Appel via formulaire + fichier local

Callback asynchrone

Utilisation basique

Callback asynchrone

Gestion des erreurs

Exemple de réponse d’erreur

Conclusion