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-2supporte é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.
Par exemple : si l’image originale fait1024x1024, avecsizeà2048x2048, le modèle redessinera et produira une image 2K ; avecsizeà3840x2160, il produira une image 4K en format paysage ; avecautoou omission, le modèle choisira automatiquement. Ces trois cas sont facturés de la même manière.
À propos du paramètreVoici deux exemples concrets illustrant les capacités d’édition denL’API d’éditiongpt-image-2ne supporte pasn > 1: ce paramètre est silencieusement ignoré, que vous passiezn=1oun=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.5et à la sérienano-banana/nano-banana-2/nano-banana-pro. Seuldall-e-2supporte nativementn > 1pour l’édition.
gpt-image-2.
Mode d’appel 1 : JSON + URL d’image (recommandé)
Envoyez directement une requête enapplication/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 :
Astuce : le champimageaccepte 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 :
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 pargpt-image-2) :
Appel :
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 enmultipart/form-data est aussi supporté, il suffit de changer model en gpt-image-2 :
OPENAI_BASE_URL à https://api.acedata.cloud/openai et OPENAI_API_KEY à votre token obtenu :
Modèles de la série Nano Banana
La sérienano-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.
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.
imagepeut être envoyé via uploadmultipart/form-data(le worker convertira endata:<mime>;base64,...pour l’upstream) ou via un champ formulaire contenant une URL d’image.- Les paramètres
mask,n,size,response_formatne sont pas supportés et seront ignorés s’ils sont fournis.- La structure de retour suit le format OpenAI (
data[].url), maiscreatedest toujours0, aucunb64_jsonn’est retourné, etrevised_promptest toujours égal au prompt original.
Appel via formulaire + URL d’image
Appel via formulaire + fichier local
Callback asynchrone
Le mécanisme de callback asynchrone viacallback_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 :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 :
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 :
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émentairecallback_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 :
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.

