API OpenAI Images Edits : Demande et utilisation

OpenAI generation 集成指南 - Ace Data Cloud

Le service d’édition d’images OpenAI permet de transmettre un nombre quelconque d’images et d’instructions, et de recevoir en sortie les images modifiées. Actuellement, l’API prend en charge dall-e-2, gpt-image-1, le plus récent 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 nous permet d’utiliser facilement la fonctionnalité officielle 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 encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion pour vous inscrire et vous connecter. Après connexion, vous serez automatiquement ramené à cette page.

Lors de la première demande, un crédit gratuit est offert, permettant d’utiliser l’API gratuitement.

​

Modèle GPT-Image-2

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

• Maintien plus stable de la structure : lors du changement de peau, de couleur ou d’arrière-plan, la mise en page et la composition de l’image originale sont presque intactes.
• Conservation plus précise du texte : les images contenant du texte comme les infographies, affiches, menus restent lisibles après édition.
• Support du passage direct d’URL : en plus du traditionnel upload de fichiers en multipart/form-data, gpt-image-2 supporte également l’envoi d’URL d’image en JSON, sans besoin de télécharger l’image localement, idéal pour une intégration côté serveur.
• Support du redessin haute résolution : on peut envoyer une image originale en 1K et demander une sortie en 2K / 4K via le paramètre size, le modèle effectue l’agrandissement pendant l’édition.

​

Valeurs supportées pour size

Les contraintes sur size dans l’API d’édition sont identiques à celles de l’API de génération — gpt-image-2 accepte size à auto, vide, ou au format WIDTHxHEIGHT. Toute autre forme renverra une erreur 400. Tous les formats (1K / 2K / 4K / personnalisés) sont facturés à l’unité par image, indépendamment de la résolution originale ou de la valeur demandée dans size.

Les contraintes strictes en amont s’appliquent aussi : largeur et hauteur multiples de 16, côté long ≤ 3840, nombre total de pixels ≤ 8 294 400.

Ratio	Recommandé 1K	Recommandé 2K	Recommandé 4K
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 : si l’image originale fait 1024x1024, avec size à 2048x2048, le modèle redessinera et produira une image 2K ; avec size à 3840x2160, il produira une image 4K en format paysage ; avec auto ou omission, le modèle choisira automatiquement. Ces trois cas sont facturés de la même manière.

À 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 sera retournée et facturée par requête. 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 / nano-banana-2 / nano-banana-pro. Seul dall-e-2 supporte nativement n > 1 pour l’édition.

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 récupérera l’image et l’éditera selon le prompt.

Par exemple, cette image originale est une infographie générée par gpt-image-2 :

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

curl -X POST "https://api.acedata.cloud/openai/images/edits" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "image": "https://platform.cdn.acedata.cloud/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.acedata.cloud/openai/images/edits"

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

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.acedata.cloud/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)

Réponse retournée :

{
  "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.acedata.cloud/gpt-image/cb104e35-af1f-45be-9fac-b62e2b256753_0.png"
    }
  ],
  "elapsed": 83.859
}

Image éditée :

On constate que la structure des modules, la segmentation de l’information et la typographie sont strictement conservées, seule la palette de couleurs a été inversée en 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, pour que le modèle prenne en compte plusieurs images lors de 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 la disposition des livres sur chaque niveau.

Image originale (étagère en bois générée par gpt-image-2) :

Appel :

payload = {
    "model": "gpt-image-2",
    "image": "https://platform.cdn.acedata.cloud/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é complètement remplacés selon le prompt, mais le nombre de livres par niveau (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, l’upload en multipart/form-data est aussi supporté, 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)

Pour utiliser le SDK, il faut d’abord définir deux variables d’environnement, OPENAI_BASE_URL à https://api.acedata.cloud/openai et OPENAI_API_KEY à votre token obtenu :

export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token}

​

Modèles de la série 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 du tableau ci-dessous.

Modèle	Coût (Crédits / requête)	Scénario d’usage
nano-banana	0.14	Édition d’image standard, 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 de la série, meilleure conservation de la structure, du texte et du style

Important : portée des paramètres supportés

Nano Banana utilise une couche d’adaptation au protocole OpenAI, et ne supporte que les paramètres suivants : model, prompt, image.

• image peut être envoyé via upload multipart/form-data (le worker convertira en data:<mime>;base64,... pour l’upstream) ou via un champ formulaire contenant une URL d’image.
• Les paramètres mask, n, size, response_format ne sont pas supportés et seront ignorés s’ils sont fournis.
• La structure de retour suit le format OpenAI (data[].url), mais created est toujours 0, aucun b64_json n’est retourné, et revised_prompt est toujours égal au prompt original.

​

Appel via formulaire + URL d’image

curl -X POST "https://api.acedata.cloud/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.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png"

Réponse :

{
  "created": 0,
  "data": [
    {
      "url": "https://platform.cdn.acedata.cloud/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.acedata.cloud/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 également avec nano-banana, le processus est identique aux autres modèles, voir la section suivante Callback asynchrone.

​

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.acedata.cloud/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[]=@test.png" \
  -F 'prompt=Create a lovely gift basket with these this items in it'

Lors de la première utilisation de cette API, il faut fournir au moins quatre éléments : un authorization choisi dans la liste déroulante, un paramètre model correspondant au modèle OpenAI choisi (ici un modèle parmi ceux proposés), un paramètre prompt qui est la description textuelle pour générer l’image, et enfin un paramètre image correspondant au chemin de l’image à éditer, comme illustré ci-dessous :

Exemple équivalent en Python :

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éfinir deux variables d’environnement, OPENAI_BASE_URL à https://api.acedata.cloud/openai et OPENAI_API_KEY à votre token obtenu via authorization. Sous Mac OS, vous pouvez définir ces variables ainsi :

export OPENAI_BASE_URL=https://api.acedata.cloud/openai
export OPENAI_API_KEY={token} 

Après appel, un fichier gift-basket.png est généré dans le répertoire courant, voici le résultat :

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 le modèle 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 requête HTTP reste ouverte, consommant des ressources système. Pour cela, l’API propose un support de callback asynchrone.

Le processus est le suivant : le client envoie une requête avec un champ supplémentaire callback_url. L’API répond immédiatement avec un résultat contenant un task_id représentant l’ID de la tâche. Une fois la tâche terminée, le résultat de l’édition est envoyé en POST JSON vers l’URL callback_url fournie, incluant aussi le task_id pour associer la réponse à la requête.

Voici un exemple d’utilisation.

Un webhook est un service HTTP capable de recevoir des requêtes. Le développeur doit remplacer par l’URL de son propre serveur HTTP. Pour la démonstration, on utilise un site public de webhook https://webhook.site/, qui fournit une URL de webhook, comme ci-dessous :

Copiez cette URL, par exemple https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab, et utilisez-la comme webhook.

Ensuite, envoyez la requête avec le champ callback_url défini sur cette URL, comme dans l’exemple :

curl -X POST "https://api.acedata.cloud/v1/images/edits" \
  -H "Authorization: Bearer {token}" \
  -F "model=gpt-image-1" \
  -F "image[]=@test.png" \
  -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 sera :

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

Quelques instants plus tard, vous verrez sur le webhook la réponse de l’édition d’image, 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 voit que la réponse contient un champ task_id et un champ data avec le résultat d’édition d’image identique à l’appel synchrone, ce qui permet d’associer la tâche via son ID.

​

Gestion des erreurs

Lors d’un appel API, en cas d’erreur, l’API retourne un code d’erreur et un message. 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’autorisation invalide ou manquant.
• 429 too_many_requests : trop de requêtes, limite de débit dépassée.
• 500 api_error : erreur serveur interne.

​

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 permis de comprendre comment utiliser facilement l’API OpenAI Images Edits pour exploiter la fonctionnalité officielle 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.