> ## Documentation Index > Fetch the complete documentation index at: https://docs.xhuoapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # API OpenAI Images Edits : Demande et utilisation > OpenAI generation 集成指南 - XHuoAPI 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](https://api.xhuoapi.ai/documents/251f1efa-aaa6-462e-8af4-66854b1bc94d) et cliquez sur le bouton « Acquire » pour obtenir les identifiants nécessaires à la requête : ![](https://cdn.xhuoapi.ai/nyq0xz.png) 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 : ```shell theme={null} 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 : ```python theme={null} 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 : ```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.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 : ```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 l’arrangement des livres sur chaque niveau. Image originale (étagère en bois générée avec `gpt-image-2`) :

Requête : ```python theme={null} 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` : ```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 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 : ```shell theme={null} 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:;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 ```shell theme={null} 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 : ```json theme={null} { "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 ```python theme={null} 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](#asynchrone-callback) ci-dessous. ## 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.xhuoapi.ai/v1/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 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 : ```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’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 : ```shell theme={null} 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](#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/](https://webhook.site/), qui fournit un URL webhook unique, comme montré ci-dessous : ![](https://cdn.xhuoapi.ai/cjjfly.png) 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 : ```shell theme={null} curl -X POST "https://api.xhuoapi.ai/v1/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 contient un `task_id` : ```json theme={null} { "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 : ```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 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 ```json theme={null} { "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.