> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # OpenAI Images Edits API Demande et Utilisation > OpenAI generation API guide - Ace Data Cloud Le service d'édition d'images d'OpenAI permet d'envoyer un nombre illimité d'images et d'instructions, et de recevoir les images modifiées en retour. Actuellement, l'API prend en charge `dall-e-2`, `gpt-image-1`, le dernier **`gpt-image-2`**, ainsi que les modèles de la série **`nano-banana` / `nano-banana-2-lite` / `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 les fonctionnalités d'édition d'images officielles d'OpenAI. ## Processus de Demande Pour utiliser l'API OpenAI Images Edits, commencez par obtenir votre API Token sur le [tableau de bord Ace Data Cloud](https://platform.acedata.cloud/console/applications) pour le garder en réserve. ![](https://cdn.acedata.cloud/5hmkdg.jpg) Si vous n'êtes pas encore connecté ou inscrit, vous serez automatiquement redirigé vers la page de connexion pour vous inviter à vous inscrire et à vous connecter, après quoi vous serez automatiquement renvoyé à la page actuelle. **Un seul API Token suffit pour accéder à tous les services de la plateforme, sans avoir besoin de faire une demande séparée pour chaque service.** La première demande vous donnera un quota gratuit pour une expérience sans frais ; lorsque le quota est insuffisant, vous pouvez recharger le solde général dans le [tableau de bord](https://platform.acedata.cloud/console/coin). > 📘 Documentation complète : [OpenAI Images Edits API →](https://platform.acedata.cloud/documents/openai-images-edits) ## Modèle GPT-Image-2 `gpt-image-2` présente des améliorations significatives par rapport à `gpt-image-1` dans le contexte de l'édition d'images : * **La structure est plus stable** : changer de peau, de palette de couleurs ou de fond ne déforme presque jamais la mise en page et la composition de l'image d'origine. * **La conservation du texte est plus précise** : les images contenant du texte, comme les infographies, les affiches et les menus, conservent un texte clair et lisible après l'édition. * **Support de l'envoi direct d'URL** : en plus du téléchargement de fichiers traditionnel `multipart/form-data`, `gpt-image-2` **supporte également l'envoi d'URL d'images au format JSON**, sans avoir besoin de télécharger d'abord l'image sur votre appareil, ce qui est idéal pour l'intégration dans des pipelines côté serveur. * **Support de l'envoi direct en base64** : conformément à l'official, le champ `image` peut également accepter directement du base64 (`data:image/png;base64,...` ou base64 brut), permettant d'éditer des images locales sans avoir à les télécharger sur un hébergement d'images. * **Support de la redéfinition en haute résolution** : vous pouvez envoyer une image d'origine de 1K et demander une sortie en 2K / 4K via le paramètre `size`, le modèle effectuera également un agrandissement pendant le processus d'édition. ### Intermédiaire Officiel / Variantes Inversées (`:official` / `:reverse`) `gpt-image-2` utilise par défaut la ligne inverse. Vous pouvez explicitement choisir la ligne via le suffixe du nom du modèle : * **`gpt-image-2:official`** : ligne de transfert officielle. Supporte `n > 1` (retour de plusieurs images à la fois) et des véritables 2K / 4K, **facturé par image, au prix de 2 fois le tarif par défaut de `gpt-image-2`**. Actuellement, cela n'est fourni que par le canal openai-hk, et si la ligne n'est pas disponible, une erreur sera directement renvoyée, sans rétrogradation vers la ligne inverse. * **`gpt-image-2:reverse`** : équivalent complet à `gpt-image-2` par défaut (ligne inverse), sans changement de prix. > Les restrictions concernant le paramètre “n” ci-dessous ne s'appliquent qu'à la ligne par défaut / inverse ; `gpt-image-2:official` supporte `n > 1` et est facturé par image. ### Valeurs supportées pour `size` Les contraintes de l'interface d'édition pour `size` sont identiques à celles de l'interface de génération — `gpt-image-2` nécessite que `size` soit `auto`, vide, ou conforme au format `WIDTHxHEIGHT`, toute autre forme renverra une erreur 400. **Tous les formats (1K / 2K / 4K / personnalisé) sont facturés de manière uniforme par image, indépendamment de la résolution de l'image d'origine et de la valeur demandée pour `size`.** Les contraintes strictes pour les dimensions personnalisées s'appliquent également : la largeur et la hauteur doivent être des multiples de 16, la longueur maximale ≤ 3840, et le nombre total de pixels ≤ 8,294,400. | Ratio | 1K Recommandé | 2K Recommandé | 4K Recommandé | | ----- | ------------- | ------------- | ------------- | | 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 d'origine est `1024x1024`, lorsque `size` est `2048x2048`, le modèle redessinera selon les instructions d'édition et produira une image 2K ; si `size` est `3840x2160`, il produira une image 4K en mode paysage ; si `auto` est transmis ou omis, le modèle choisira lui-même. Les trois options sont facturées de manière identique. > **Concernant le paramètre `n`** > L'interface d'édition de `gpt-image-2` **ne supporte actuellement pas `n > 1`** : ce paramètre sera silencieusement ignoré, que vous transmettiez `n=1` ou `n=10`, une seule image sera renvoyée par demande, et la facturation ne sera que pour une image. Si vous avez besoin d'obtenir plusieurs résultats d'édition candidats en une seule fois, veuillez **initier plusieurs demandes en parallèle**. Cette restriction s'applique également à `gpt-image-1` / `gpt-image-1.5`, ainsi qu'aux séries `nano-banana` / `nano-banana-2-lite` / `nano-banana-2` / `nano-banana-pro`. `dall-e-2` est actuellement le seul modèle d'édition à supporter nativement `n > 1`. Voici deux exemples réels sous différents angles pour apprécier les capacités d'édition de `gpt-image-2`. ### Méthode d'appel 1 : JSON + URL d'image (recommandé) Envoyez directement la demande au format `application/json`, en remplissant le champ `image` avec l'URL d'une image, le modèle ira chercher cette image et l'éditera selon le `prompt`. Par exemple, l'image d'origine ci-dessous a été générée avec `gpt-image-2` pour un guide de vulgarisation scientifique :

Nous souhaitons la modifier pour obtenir un schéma de couleurs en "mode nuit". Nous pouvons l'appeler ainsi : ```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) ``` Le résultat est le suivant : ```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 } ``` L'image après modification est la suivante :

On peut voir que la structure des modules, la répartition des informations et la typographie ont été strictement conservées, seule la palette de couleurs a été inversée pour un thème sombre. > **Remarque** : Le champ `image` prend également en charge un tableau, par exemple `"image": ["url1", "url2", "url3"]`, permettant de transmettre jusqu'à 16 images de référence simultanément pour que le modèle prenne en compte plusieurs images lors de l'édition. > **Transmission en base64** : `image` (et chaque élément du tableau) peut être une URL ou en base64 — `data:image/png;base64,...` ou base64 brut, ce qui est adapté pour les images locales que l'on ne souhaite pas d'abord télécharger sur un hébergement d'images. Par exemple : > > ```python theme={null} > import base64, requests > b64 = base64.b64encode(open("input.png", "rb").read()).decode() > payload = { > "model": "gpt-image-2", > "image": f"data:image/png;base64,{b64}", > "prompt": "Convert this infographic to dark mode.", > "size": "1024x1536" > } > requests.post("https://api.acedata.cloud/openai/images/edits", json=payload, > headers={"authorization": "Bearer {token}"}) > ``` ### Méthode d'appel deux : JSON + plusieurs images de référence `gpt-image-2` prend en charge la référence à plusieurs images pour générer le résultat final, par exemple en combinant plusieurs photos de produits dans un seul 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 : changer de style + conserver la structure Voici un autre exemple, remplaçant une étagère en bois par une étagère flottante moderne, tout en conservant strictement le nombre et l'arrangement des livres sur chaque étagère. Image originale (étagère en bois générée avec `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 de l'édition (`task_id`: `e9544dba-727e-44a2-81e1-223d49869380`) :

On peut voir que le style et l'environnement ont été complètement remplacés selon les instructions, mais le nombre de livres sur chaque étagère (1 / 3 / 7) a été strictement conservé, et une petite plante succulente a été ajoutée comme demandé. ### Méthode d'appel trois : multipart/form-data (compatible avec OpenAI SDK) Si vous utilisez déjà le SDK Python officiel d'OpenAI, l'ancienne méthode de téléchargement `multipart/form-data` est également applicable, 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) ``` Lors de l'utilisation du SDK, il est nécessaire d'importer deux variables d'environnement, `OPENAI_BASE_URL` doit être défini sur `https://api.acedata.cloud/openai`, et `OPENAI_API_KEY` doit être défini sur le 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` a également intégré `/openai/images/edits` dans les scénarios d'édition, il suffit de changer `model` en l'un des modèles du tableau ci-dessous. | Modèle | Facturation (Crédits / fois) | Scénarios d'application | | -------------------- | ---------------------------- | ----------------------------------------------------------------------------------------- | | `nano-banana` | 0.14 | Édition d'images ordinaire, la plus rapide et la moins coûteuse | | `nano-banana-2-lite` | 0.14 | Modèle d'image léger Gemini 3.1, prend en charge uniquement 1K, édition à faible latence | | `nano-banana-2` | 0.28 | Amélioration significative de la qualité et des détails | | `nano-banana-pro` | 0.35 | Le modèle phare de la série, meilleure conservation de la structure, du texte et du style | > **Important : Plage de support des paramètres** > Nano Banana se connecte au protocole OpenAI via une couche d'adaptation, ne prenant en charge que les paramètres suivants : `model`, `prompt`, `image`. > > * `image` peut être téléchargé via `multipart/form-data` (le worker le convertira en `data:;base64,...` pour l'envoyer en amont), ou peut être transmis directement sous forme de chaîne d'URL d'image dans les champs de formulaire. > * Les paramètres `mask`, `n`, `size`, `response_format`, etc. ne sont pas pris en charge ; s'ils sont remplis, ils seront ignorés. > * La structure de retour suit le format OpenAI (`data[].url`), mais `created` est fixé à `0`, et `b64_json` ne sera pas retourné, `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=ajouter une feuille verte sur le dessus de la pomme" \ -F "image=https://platform.cdn.acedata.cloud/nanobanana/6870b330-65c4-436c-bb80-819fdae7a7a4.png" ``` Le résultat retourné est le suivant : ```json theme={null} { "created": 0, "data": [ { "url": "https://platform.cdn.acedata.cloud/nanobanana/311e95b6-5eb1-4c4a-8ee6-0cb03ee44f61.jpeg", "revised_prompt": "ajouter une feuille verte sur le dessus de la pomme" } ] } ``` 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": "ajouter une feuille verte sur le dessus de la pomme" } response = requests.post(url, headers=headers, files=files, data=data) print(response.text) ``` ### Rappel asynchrone Le mécanisme de rappel asynchrone `callback_url` est également valable pour nano-banana, le processus d'appel est identique à celui des autres modèles, voir la section [Rappel asynchrone](#rappel-asynchrone) ci-dessous. ## Utilisation de base Nous pouvons maintenant utiliser le code pour faire un appel, ci-dessous un 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=Créer un joli panier-cadeau avec ces articles à l'intérieur' ``` Lors de la première utilisation de cette interface, nous devons remplir au moins quatre éléments, l'un est `authorization`, que nous pouvons sélectionner directement dans la liste déroulante. Un autre paramètre est `model`, `model` est la catégorie de modèle que nous choisissons d'utiliser sur le site officiel d'OpenAI, ici nous avons principalement 1 type de modèle, les détails peuvent être consultés dans les modèles que nous fournissons. Un autre paramètre est `prompt`, `prompt` est le mot d'invite que nous entrons pour générer l'image. Le dernier paramètre est `image`, ce paramètre nécessite le chemin de l'image à éditer, l'image à éditer est montrée ci-dessous :

Code d'appel Python équivalent : ```python theme={null} import base64 from openai import OpenAI client = OpenAI() prompt = """ Générez une image photoréaliste d'un panier-cadeau sur un fond blanc étiqueté 'Relax & Unwind' avec un ruban et une police ressemblant à de l'écriture manuscrite, contenant tous les articles des images de référence. """ 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, nous devons d'abord importer deux variables d'environnement, une `OPENAI_BASE_URL`, qui peut être définie sur `https://api.acedata.cloud/openai`, et une variable d'authentification `OPENAI_API_KEY`, cette valeur est obtenue à partir de `authorization`, sur Mac OS, vous pouvez définir les variables d'environnement avec les commandes suivantes : ```shell theme={null} export OPENAI_BASE_URL=https://api.acedata.cloud/openai export OPENAI_API_KEY={token} ``` Après l'appel, nous constatons qu'une image `gift-basket.png` est générée dans le répertoire actuel, le résultat est le suivant :

Ainsi, nous avons terminé l'opération d'édition d'image, actuellement l'interface Edits prend en charge trois modèles : `dall-e-2`, `gpt-image-1` et `gpt-image-2`, parmi lesquels `gpt-image-2` est le modèle recommandé à utiliser, voir la section [Modèle GPT-Image-2](#gpt-image-2-模型) ci-dessus. ## Rappel asynchrone Étant donné que l'API OpenAI Images Edits peut prendre un certain temps pour éditer les images, si l'API ne répond pas pendant longtemps, la requête HTTP maintiendra la connexion, entraînant une consommation supplémentaire de ressources système, c'est pourquoi cette API propose également un support de rappel asynchrone. Le processus global est le suivant : lorsque le client initie une demande, il spécifie un champ `callback_url` supplémentaire, après que le client a lancé la demande API, l'API renverra immédiatement un résultat contenant un champ `task_id`, représentant l'ID de la tâche actuelle. Lorsque la tâche est terminée, le résultat de l'édition de l'image sera envoyé au `callback_url` spécifié par le client sous forme de JSON POST, incluant également le champ `task_id`, permettant ainsi de lier le résultat de la tâche par ID. Voyons comment procéder à travers un exemple. Tout d'abord, le rappel Webhook est un service capable de recevoir des requêtes HTTP, les développeurs doivent le remplacer par l'URL de leur propre serveur HTTP. Pour des raisons de démonstration, nous utilisons un site Web de démonstration Webhook public [https://webhook.site/](https://webhook.site/), en ouvrant ce site, vous obtiendrez une URL Webhook, comme illustré ci-dessous : ![](https://cdn.acedata.cloud/cjjfly.png) Copiez cette URL, elle peut être utilisée comme Webhook, l'exemple ici est `https://webhook.site/3d32690d-6780-4187-a65c-870061e8c8ab`. Ensuite, nous pouvons définir le champ `callback_url` sur l'URL Webhook ci-dessus, tout en remplissant les paramètres correspondants, comme le montre le code suivant : ```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" ``` Après l'appel, vous pouvez constater qu'un résultat est immédiatement obtenu, comme suit : ```json theme={null} { "task_id": "6a97bf49-df50-4129-9e46-119aa9fca73c" } ``` Après un moment, nous pouvons observer le résultat de l'édition de l'image sur l'URL Webhook, le contenu est le suivant : ```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 peut voir qu'il y a un champ `task_id` dans le résultat, le champ `data` contient les mêmes résultats d'édition d'image que l'appel synchrone, et le champ `task_id` permet d'associer les tâches. ## Gestion des erreurs Lors de l'appel de l'API, si une erreur se produit, l'API renverra le code d'erreur et les informations correspondantes. Par exemple : * `400 token_mismatched` : Mauvaise requête, probablement en raison de paramètres manquants ou invalides. * `400 api_not_implemented` : Mauvaise requête, probablement en raison de paramètres manquants ou invalides. * `401 invalid_token` : Non autorisé, jeton d'autorisation invalide ou manquant. * `429 too_many_requests` : Trop de requêtes, vous avez dépassé la limite de taux. * `500 api_error` : Erreur interne du serveur, quelque chose s'est mal passé sur le serveur. ### 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 Grâce à ce document, vous avez compris comment utiliser l'API OpenAI Images Edits pour utiliser facilement la fonction d'édition d'images officielle d'OpenAI. Nous espérons que ce document vous aidera à mieux intégrer et utiliser cette API. Si vous avez des questions, n'hésitez pas à contacter notre équipe de support technique.