> ## Documentation Index > Fetch the complete documentation index at: https://germeytechnology-docs-remove-4o-image-nav.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # 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](https://platform.acedata.cloud/documents/openai-images-edits) et cliquez sur le bouton « Acquire » pour obtenir les identifiants nécessaires à la requête : ![](https://cdn.acedata.cloud/nyq0xz.png) 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 : ```shell theme={null} 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 : ```python theme={null} 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 : ```json theme={null} { "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 : ```python theme={null} 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 : ```python theme={null} 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` : ```python theme={null} 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 : ```shell theme={null} 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:;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 ```shell theme={null} 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 : ```json theme={null} { "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 ```python theme={null} 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](#callback-asynchrone). ## Utilisation basique Voici un exemple d’appel via CURL : ```curl theme={null} 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 : ```python theme={null} 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 : ```shell theme={null} 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](#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/](https://webhook.site/), qui fournit une URL de webhook, comme ci-dessous : ![](https://cdn.acedata.cloud/cjjfly.png) 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 : ```shell theme={null} 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 : ```json theme={null} { "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 : ```json theme={null} { "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 ```json theme={null} { "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.