L'API d'édition d'images OpenAI modifie une image existante à partir d'une consigne. L'itinéraire natif est le suivant : POST /v1/images/edits; elle accepte une image, une invite et des commandes d'édition facultatives telles qu'un masque ou des images de référence. Utilisez l'API Image pour une requête ciblée, et l'API Responses lorsque le produit nécessite un workflow d'images en plusieurs étapes.
Une retouche fiable se résume à un petit enchaînement d'étapes : verrouiller le fichier source, indiquer ce qui doit rester inchangé, préciser ce qui peut être modifié, vérifier les octets renvoyés, puis enregistrer le fichier validé. Si vous préférez passer d'un logiciel de retouche d'images à d'autres outils multimédias au sein d'un même espace de travail, Créer et modifier des images avec GPT Image 2 en GlobalGPT; son API publique utilise un contrat de tâche asynchrone différent, que ce guide distingue du point de terminaison natif de OpenAI.
Réponse rapide : choisissez l'approche avant de commencer à coder
| Besoin | Itinéraire | Demander la forme | Résultat à traiter |
|---|---|---|---|
| Création ou modification d'une image | OpenAI Image API | POST /v1/images/edits, formulaire en plusieurs parties | data[0].b64_json; le décoder et le stocker |
| Quelques opérations avec le contexte d'image | API de réponses OpenAI | POST /v1/responses avec un outil de génération d'images | Extraire l'élément de sortie relatif à la génération d'images |
| Plusieurs modèles de médias derrière un seul compte | API publique GlobalGPT | POST /tasks, puis interroger GET /tasks/{id} | output.url; enregistrez-le avant la fin du délai de 30 jours |
Les noms des points de terminaison se ressemblent, mais le contenu des requêtes et le traitement des résultats ne sont pas interchangeables.
À quoi sert l'API d'édition d'images OpenAI ?
Le processus d'édition commence à partir d'une image existante. Votre instruction décrit la modification, tandis que l'image d'entrée fournit le contexte visuel qui doit être conservé après la modification. Vous pouvez remplacer un arrière-plan, ajouter ou supprimer un élément, procéder à une refonte plus globale, ou fournir plusieurs images comme références. Le modèle interprète toujours la requête ; l'API n'est pas un éditeur de pixels garantissant les limites de la sélection.
Le document OpenAI décrit deux procédures utiles. Le API d'images est la solution idéale lorsqu'une requête doit renvoyer une seule image. Le API de réponses est la solution la plus adaptée lorsque l'utilisateur examine le résultat, demande une nouvelle modification et conserve le contexte de l'image d'un tour à l'autre. Ce choix a une incidence à la fois sur la structure de la requête et sur le code qui extrait le résultat.
API « Image » et API « Responses »
| Question | API d'images | API de réponses |
|---|---|---|
| Meilleur pour | Une seule action de création ou de modification | Une expérience d'édition en plusieurs étapes |
| Exemple d'entrée | Image en plusieurs parties, invite, masque facultatif | Outil de saisie de conversation et de génération d'images |
| Traitement des données de sortie | data[0].b64_json | Rechercher l'élément de sortie correspondant à la génération d'images |
| Détail des coûts | L'édition directe utilise les fréquences d'entrée/sortie actuelles | Les règles de saisie mises en cache peuvent varier ; veuillez vérifier les tarifs en vigueur |
Effectuez une première modification à l'aide de l'API native OpenAI
Conservez la clé API sur votre serveur et chargez-la à partir d'une variable d'environnement. L'exemple ci-dessous envoie une image et une invite à l'endpoint « edits » décrit dans la documentation. Le image[] Le champ peut être répété lorsque le modèle sélectionné prend en charge plusieurs entrées. Le pipeline du shell décode la première image Base64 renvoyée en un fichier PNG local.
Modification native de Curl : enregistrer le résultat au format b64_json
curl -s \
-X POST "https://api.openai.com/v1/images/edits" \
-H "Authorization: Bearer $OPENAI_API_KEY" \
-F "model=gpt-image-2.5-sunburst" \
-F "image[]=@source.png" \
-F "prompt=Remplace uniquement l'arrière-plan par une scène de studio dans des tons beige chaud ; conserve le produit et l'étiquette tels quels." \
| jq -r '.data[0].b64_json' \
| base64 --decode > edited.pngModification du SDK Python : décoder les octets renvoyés
from openai import OpenAI
import base64
client = OpenAI()
result = client.images.edit(
model="gpt-image-2.5-sunburst",
image=open("source.png", "rb"),
prompt="Remplacer uniquement l'arrière-plan par une scène de studio beige chaud ; conserver le produit et l'étiquette tels quels.",
)
image_bytes = base64.b64decode(result.data[0].b64_json)
with open("edited.png", "wb") as output:
output.write(image_bytes)Avant de considérer ce fichier comme prêt pour la production, vérifiez-le : contrôlez son type MIME, ses dimensions, le nombre d'octets, et assurez-vous que les détails visuels importants sont toujours présents. Une réponse 200 indique simplement que la requête a été acceptée ; elle ne garantit pas que l'étiquette, le logo ou la géométrie du produit aient été conservés.
Utilisez les masques et les images de référence en toute sécurité
Un masque indique au modèle la zone que vous souhaitez modifier, mais le masquage d’images dans GPT reste basé sur les invites. Le guide de OpenAI précise clairement que le modèle utilise le masque à titre indicatif et non comme une limite absolue au niveau des pixels. Veillez à ce que l’invite soit précise concernant le sujet à protéger et vérifiez l’ensemble de l’image une fois la génération terminée.
Vérification préalable du masque
- L'image et le masque utilisent le même format.
- L'image et le masque ont les mêmes dimensions.
- La taille du fichier de masque est inférieure à 50 Mo.
- Le masque contient un canal alpha.
- La consigne précise ce qui doit rester inchangé et ce qui doit être remplacé.
Vérifiez un masque avant de le mettre en ligne
from PIL import Image
source = Image.open("source.png")
mask = Image.open("mask.png")
assert source.format == mask.format, (source.format, mask.format)
assert source.size == mask.size, (source.size, mask.size)
assert mask.width * mask.height > 0
assert mask.mode in {"RGBA", "LA"}, mask.mode
assert mask.fp is None or True # vérifier séparément la taille du fichier sur le disque
print("source:", source.size, source.format)
print("masque :", mask.size, mask.mode)Si vous transmettez plusieurs images avec un masque, le guide actuel précise que le masque s'applique à la première image. Il s'agit là d'une contrainte utile pour concevoir un flux de travail de référence : faites en sorte que la première image fournie soit celle dont vous souhaitez modifier la zone, et considérez les images restantes comme des références, plutôt que de partir du principe que le masque s'applique à l'ensemble de ces images.
Les images de référence répondent à un autre type de problème. Elles peuvent servir de référence pour l'identité d'un produit, une gamme d'éclairage, une palette de couleurs ou une composition. Elles n'obligent pas le modèle à reproduire chaque contour. Si la forme exacte d'un emballage ou d'une étiquette doit rester inchangée, prévoyez une étape de vérification visuelle ou une étape de retouche classique après la génération du modèle.
Choisissez le modèle et les paramètres
La liste actuelle figurant dans le guide illustré OpenAI comprend gpt-image-2.5-sunburst, gpt-image-2.5-flare, et gpt-image-2. Considérez les noms de modèles et les options prises en charge comme une documentation évolutive : consultez la page du modèle juste avant de l'intégrer, et enregistrez une version datée si la reproductibilité est importante.
Choix de paramètres permettant d'éviter les défaillances évitables
| Décision | Règle pratique | Pourquoi c'est important |
|---|---|---|
| Fidélité de l'entrée | Omettre fidélité_d'entrée pour gpt-image-2; ses données d'entrée d'images sont traitées avec une grande fidélité. | L'envoi d'un champ non pris en charge peut transformer une modification valide en une requête rejetée. |
| Qualité | Documentation sur les itinéraires « 2.5 Sunburst » et « Flare » faible, moyen, élevé, xhigh, et max. | Un réglage plus élevé relève d'un compromis entre coût et latence, et ne garantit pas une meilleure conservation. |
| Format | Demandez le format de sortie pris en charge par le point de terminaison actuel, puis examinez le fichier décodé. | Votre pipeline de stockage doit se fier aux octets et au type MIME, et pas uniquement à l'option demandée. |
| Contexte | Indiquez l'arrière-plan souhaité dans la ligne de commande et utilisez l'option d'arrière-plan décrite dans la documentation lorsque celle-ci est prise en charge. | Le modèle continue d'interpréter la scène ; veillez à ce que les contraintes relatives au sujet restent explicites. |
| Références | Utilisez une image de référence pour orienter l'identité visuelle, les couleurs ou l'éclairage, et définissez le rôle de chaque élément. | L'ambiguïté des rôles attribués aux images complique le diagnostic d'une dérive. |
Quel est le coût de l'API d'édition d'images OpenAI ?
OpenAI facture l'utilisation de GPT Image par catégories de jetons plutôt que selon un tarif forfaitaire unique par modification. La page de tarification actuelle répertorie des tarifs distincts pour les entrées d'images, les entrées mises en cache et les sorties d'images. Les modifications effectuées via l’API Direct Image ne bénéficient pas du traitement des entrées mises en cache décrit pour l’outil de génération d’images dans l’API Responses ; par conséquent, ne copiez pas une estimation de l’API Responses dans une requête Direct /v1/images/modifications budget.
Taux des jetons d'image publiés, vérifiés le 28 septembre 2026
| Modèle | Entrée d'image / 1 million de tokens | Image mise en cache / 1 million de jetons | Sortie d'images / 1 million de jetons |
|---|---|---|---|
| GPT Image 2.5 | $8 | $2* | $30 |
| Image GPT 2 | $4 | $1* | $15 |
*La colonne « cached-input » s'affiche pour le contexte tarifaire publié. Le guide tarifaire précise que le paramètre « cached-input » s'applique à l'outil de génération d'images de l'API Responses, et non aux requêtes directes adressées à l'API Images, telles que /v1/images/modifications. Les tarifs peuvent varier ; effectuez le calcul en fonction de la consommation indiquée pour votre propre demande.
Établir une estimation transparente en fonction de la consommation
def estimate_image_cost(image_input_tokens, image_output_tokens,
input_rate, output_rate) :
return (image_input_tokens / 1_000_000) * input_rate + \
(image_output_tokens / 1_000_000) * output_rate
# Exemple uniquement : remplacez par les valeurs d'utilisation de votre réponse.
estimate = estimate_image_cost(
image_input_tokens=250_000,
image_output_tokens=120_000,
input_rate=4.00,
output_rate=15.00,
)
print(f"${estimate:.4f}")Cette formule est un exemple à titre indicatif et ne constitue en aucun cas une garantie d'un montant fixe par image. Veuillez inclure dans votre budget les nouvelles tentatives, le stockage des fichiers, ainsi que toute utilisation distincte de textes ou d'outils. Lorsque le résultat est important, veillez à regrouper la requête, l'utilisation de la réponse, le hachage du fichier décodé et la décision d'approbation.
GlobalGPT utilise un contrat API de traitement d'images différent
Le Documentation de l'API GlobalGPT décrit la génération d'images, de vidéos et de fichiers audio comme des tâches multimédias asynchrones. Son URL de base publique est https://api2.glbgpt.com/ai-api/open/v1. Envoyer le fichier JSON à /tâches, sondage /tâches/{id}, et lire output.url après la réussite d'une tâche. Le catalogue de modèles répertorie gpt-image-2 et gpt-image-2.5 sous forme de routes « image-edit/reference » pouvant prendre jusqu’à quatre images en entrée et format d'image.
Documentation de l'API publique S05 : Documentation publique relative au contrat de tâche asynchrone ; cet article le distingue du point de terminaison natif de OpenAI dédié aux modifications en plusieurs parties.
Catalogue des modèles publics S06 : Preuves issues du catalogue public de modèles concernant les itinéraires GPT Image et leurs limites documentées en matière de tâches liées aux images ; vérifiez les crédits et les champs dynamiques avant publication.
Forme de la tâche publique GlobalGPT
BASE="https://api2.glbgpt.com/ai-api/open/v1"
# Facultatif : obtenir un devis sans créer de tâche ni réserver de crédits.
curl "$BASE/tasks/estimate" \
-H "Authorization: Bearer $GLOBALGPT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2.5",
"prompt": "Conservez la bouteille et l'étiquette telles quelles. Remplacer uniquement l'arrière-plan par un éclairage de studio beige chaud.",
"images": ["https://YOUR_PUBLIC_IMAGE_URL/product.png"],
"aspect_ratio": "3:2"
}'
# Ne soumettre qu’après avoir vérifié le devis.
curl "$BASE/tasks" \
-H "Authorization: Bearer $GLOBALGPT_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: image-edit-example-001" \
-d '{
"model": "gpt-image-2.5",
"prompt": "Ne modifiez ni la bouteille ni l'étiquette. Remplacez uniquement l’arrière-plan par un éclairage de studio beige chaud.",
"images": ["https://YOUR_PUBLIC_IMAGE_URL/product.png"],
"aspect_ratio": "3:2"
}'
# Interroger l’identifiant de la tâche renvoyée jusqu’à ce que l’opération aboutisse ou échoue.
curl "$BASE/tasks/TASK_ID" \
-H "Authorization: Bearer $GLOBALGPT_API_KEY"Ne collez pas le message en plusieurs parties de OpenAI masque, fidélité_d'entrée, taille, ou qualité champs dans ce JSON et partons du principe qu'ils fonctionnent. La documentation publique actuelle de GlobalGPT ne mentionne pas ces champs pour cette route d'image. Les champs non pris en charge peuvent être ignorés et renvoyés dans paramètres_ignorés, vérifiez donc cette réponse avant de conclure qu’un paramètre a pris effet.
Selon la documentation publique, GlobalGPT réserve des crédits lorsqu'une tâche multimédia est soumise, les libère en cas d'échec de la tâche et conserve les fichiers multimédias traités avec succès pendant 30 jours. Enregistrez le fichier renvoyé sur un espace de stockage que vous contrôlez si l'URL doit rester accessible plus longtemps. Utilisez le point de terminaison d'estimation avant un traitement par lots, une clé d’idempotence lors de la réinitialisation d’une requête réseau, et l’ID de tâche d’origine lorsque l’interrogation est simplement lente.
Ce qu'a révélé le test du modèle GlobalGPT
Pour illustrer concrètement cette distinction, j’ai effectué un test API sur un modèle GlobalGPT limité le 28 septembre 2026, à l’aide de deux invites d’entrée fictives sans référence à une marque et de deux invites de modification. Chaque tâche utilisait GPT Image 2, une requête au format 3:2 et la première sortie valide. Les images ci-dessous constituent des preuves issues du test du modèle ; il ne s'agit ni d'une session dans l'espace de travail d'un navigateur, ni d'un benchmark, ni d'une garantie que chaque modification préservera tous les contours.
Entrée P00 : L'image source figée : une bouteille fictive sans marque, dotée d'un bouchon blanc court et d'une étiquette courte.
Référence P01 : L'image de référence figée : utilisée uniquement à des fins d'éclairage et de couleur, et non comme deuxième identité du produit.
T01 : retouche d'arrière-plan sur une seule image
Afficher l'invite complète
Conservez sans modification la bouteille en céramique, le bouchon blanc court, le texte fictif de l'étiquette " NORTH " et " 250 ml ", les couleurs, l'angle de prise de vue et les proportions de l'image d'origine. Remplacez uniquement le fond blanc pur par un décor de studio intérieur beige chaud, inspiré par la lumière douce d'une fenêtre et des ombres délicates. N’ajoutez aucun nouvel objet, logo, mot, filigrane, personne ou étiquette. Conservez la bouteille comme seul sujet dans une composition au format paysage 3:2.
Ce que cela montre : La bouteille reste reconnaissable, l'étiquette « NORTH / 250 ml » est visible, et le fond blanc laisse place à une scène d'intérieur aux tons beige chauds, avec de douces ombres rappelant celles d'une fenêtre.
Limite : Il s'agit d'un premier résultat valide. Cela ne prouve pas la conservation exacte des pixels ni la fidélité générale des étiquettes.
T02 : référence d'éclairage et de couleur à partir de deux images
Afficher l'invite complète
Utilisez l’image d’entrée 1 comme référence exacte du produit et l’image d’entrée 2 uniquement comme référence pour l’éclairage beige chaud, la température de couleur et les ombres douces en intérieur. Conservez inchangés la forme de la bouteille en céramique, le bouchon blanc court, le texte fictif de l’étiquette " NORTH " et " 250 ml ", les couleurs, l’angle de prise de vue et les proportions de l’image d’entrée 1. Remplacez le fond blanc par une scène de studio d'intérieur aux tons beige chaud et apaisants. Ne copiez aucun objet, texte, logo, filigrane, personne ou étiquette supplémentaire provenant de l'image d'entrée 2. Conservez la bouteille comme seul sujet dans une composition au format paysage 3:2.
Ce que cela montre : Le produit et l'étiquette NORTH / 250 ml restent reconnaissables, tandis que le décor reprend l'ambiance chaleureuse du P01, avec ses tons beige, sa table et la lumière qui filtre par la fenêtre.
Limite : La proportion du bouchon, le contour de la bouteille et son emplacement ont visiblement changé. Ne considérez pas cela comme une préservation parfaite ou exacte de l’identité ; procédez à une comparaison manuelle lorsque les dimensions des produits doivent correspondre.
Comment utiliser ces données : Le résultat utile est un processus de validation reproductible. Figez l'URL d'entrée, nommez le sujet protégé, décrivez le rôle de référence, inspectez les octets renvoyés et comparez le produit approuvé à la source avant publication. Le transfert de style peut aboutir même si la géométrie continue de varier.
Gérer les erreurs et les réponses lentes
Symptôme → vérification → action
| Symptôme | Vérifiez d'abord | Une prochaine étape en toute sécurité |
|---|---|---|
| 401 / erreur d'authentification | Clé côté serveur, autorisations de compte, hôte du point de terminaison | Arrêtez-vous et corrigez l'authentification ; ne notez pas la qualité de l'image. |
| 400 / 422 : requête incorrecte | ID du modèle, noms des champs composés, type de fichier, options non prises en charge | Modifiez uniquement le champ indiqué dans le message d'erreur, puis conservez la requête d'origine qui a échoué. |
| 429 / 5xx / capacité | Si un identifiant de tâche a été créé | Si aucun identifiant de tâche n'existe, réessayez une fois conformément à votre politique ; si une tâche existe, interrogez cet identifiant. |
| La tâche reste en file d'attente ou en cours de traitement | Statut, heure du dernier sondage, estimation du fournisseur | Effectuer une interrogation à un intervalle défini ; ne pas créer de doublon tant que le statut est inconnu. |
| Le résultat est un objet JSON enregistré sous forme d'image | Type de contenu, premiers octets, format décodé | Analyser la réponse, la décoder b64_json ou télécharger output.url, puis valider. |
| Le paramètre semble n'avoir aucun effet | GlobalGPT paramètres_ignorés et la fiche technique du modèle | Supprimez les champs non pris en charge et utilisez le contrat spécifique au modèle. |
Il convient de distinguer les éléments liés au transport de ceux liés à la qualité. Un délai d'attente, une erreur DNS ou une réponse liée à la capacité du fournisseur signifient que vous ne disposez pas d'une image valide à évaluer. À l'inverse, une image valide dont la casquette ou l'étiquette a été modifiée constitue un résultat visuel qui doit être signalé tel quel, même si la composition semble attrayante.
Liste de contrôle pour la retouche d'images en environnement de production
- Figer la source : enregistrer le fichier d'entrée, ses dimensions, son format et son hachage.
- Attribuer des rôles aux images : identifier l'image en question ainsi que les éventuelles références en matière d'éclairage, de palette de couleurs ou de composition.
- Cues protégés en écriture : énumérez l'étiquette, la silhouette, les couleurs et les proportions qui doivent être revues.
- Choisissez le contrat : Utilisez le format multipart OpenAI pour le point de terminaison « native edits » ou les tâches JSON GlobalGPT pour son API multimédia publique.
- Établir un devis et l'envoyer : utiliser les taux actuels OpenAI ou GlobalGPT
/tâches/estimation; ajouter une clé d'idempotence pour garantir la sécurité des soumissions en cas de nouvelle tentative. - Interroger et décoder : conserver un identifiant de tâche, valider le fichier renvoyé, puis enregistrer les octets ou l'URL dans un espace de stockage approuvé.
- Valider visuellement : comparer le résultat avec le document source avant qu'il ne soit intégré à un catalogue de produits, à une publicité ou à une page destinée aux clients.
Si vous souhaitez exécuter le même processus sans avoir à assembler plusieurs tableaux de bord de modèles distincts, essayez Image GPT 2 dans GlobalGPT. Pour la version du flux de travail destinée aux navigateurs, voir modifier des images dans l'espace de travail GlobalGPT; pour une analyse plus approfondie de la configuration et des tarifs, voir Configuration et tarifs de l'API GPT Image.
Foire aux questions
Qu'est-ce que l'API d'édition d'images OpenAI ?
Il s'agit de la route de modification d'images POST /v1/images/edits. Vous envoyez une image d'entrée et une instruction, accompagnées éventuellement d'un masque ou d'images de référence, puis vous décodez les données d'image renvoyées. Utilisez l'API Image pour une modification unique et l'API Responses lorsque le produit nécessite une conversation en plusieurs étapes autour d'une image.
L'API d'édition d'images OpenAI renvoie-t-elle une URL publique vers l'image ?
Les exemples documentés de l'API Image renvoient des données au format b64_json. Décodez ces octets, validez le fichier, puis enregistrez-le dans un espace de stockage que vous contrôlez. Ne partez pas du principe qu'une réponse positive correspond à une URL hébergée sur un CDN.
Le masque d'image OpenAI correspond-il à une sélection pixel par pixel ?
Non. Un masque guide une modification basée sur des instructions. Le modèle peut modifier les pixels situés autour de la zone demandée ; veillez donc à vérifier les étiquettes, les détails du produit, les marquages de sécurité et tout autre élément qui doit rester correct.
Combien d'images d'entrée un outil de retouche d'images peut-il traiter ?
Le guide d'images actuel prend en charge plusieurs images d'entrée pour les flux de travail de référence. Pour connaître la limite exacte et le comportement spécifique au modèle, consultez la documentation du modèle concerné ; le nombre maximal pris en charge ne garantit pas une conservation parfaite dans toutes les compositions.
Puis-je envoyer la requête OpenAI /v1/images/edits à GlobalGPT en modifiant la valeur de « base_url » ?
Le contrat multimédia public du n° GlobalGPT utilise la méthode JSON POST /tasks, puis GET /tasks/{id}, avec des images et un rapport d'aspect (aspect_ratio) lorsque le modèle sélectionné les accepte. La documentation publique ne mentionne pas le masque multipart, ni les paramètres input_fidelity, size ou quality du modèle OpenAI pour cette route.
Comment dois-je évaluer une tâche d'image avant de la soumettre ?
Pour GlobalGPT, envoyez d'abord le même corps JSON à /tasks/estimate. Cela ne crée pas de tâche et ne réserve pas de crédits. Pour OpenAI, effectuez le calcul en utilisant les tarifs actuels par million de jetons, puis vérifiez l'utilisation réelle dans la réponse ou dans l'historique de facturation.
