Beaucoup de développeurs qui intègrent l'interface d'édition d'images de gpt-image-2 se heurtent au même problème : en parcourant la documentation de référence de l'API images/edit, on y lit bien que « les modèles GPT image acceptent jusqu'à 16 images », mais impossible de trouver la limite de taille par fichier. Est-ce qu'il n'y a pas de limite ? Ou est-ce un oubli dans la documentation ?
La réponse est : la limite existe, et elle est très claire — chaque image doit peser moins de 50 Mo, et les formats PNG, WebP et JPG sont supportés. Le souci, c'est que cette règle ne figure pas dans le tableau des paramètres de la page de référence, mais dans un guide d'utilisation distinct sur la génération d'images. Cette fragmentation de l'information en a piégé plus d'un.
Dans cet article, nous allons faire le tour complet des restrictions d'upload pour l'API gpt-image-2 : nombre, taille, format, règles de masque, contraintes de résolution, et une question pratique bien plus importante que la limite des 50 Mo : pourquoi nous vous déconseillons fortement d'envoyer réellement des images de 50 Mo.
Restrictions d'upload d'images pour l'API gpt-image-2 : spécifications officielles complètes
Commençons par le plus important. gpt-image-2 reçoit les images via le point de terminaison v1/images/edits. Les limites officielles sont résumées dans le tableau ci-dessous.
Tableau récapitulatif des limites d'upload pour gpt-image-2
| Restriction | Spécification officielle | Source |
|---|---|---|
| Nombre max d'images par requête | 16 images (modèles GPT image) | API Reference : images/edit |
| Taille par image | < 50 Mo | Guide d'utilisation Image Generation |
| Formats supportés | PNG, WebP, JPG | Guide d'utilisation Image Generation |
| Méthode d'envoi | image_url ou file_id (au choix) |
API Reference : images/edit |
| Masque | Même format/taille que l'original, < 50 Mo, canal alpha requis | Guide d'utilisation Image Generation |
| Nombre de générations (n) | 1 à 10 images | API Reference : images/edit |
En théorie, une seule requête d'édition peut donc contenir 16 images proches de 50 Mo. Cependant, il y a une différence entre la "limite théorique" et la "réalité technique", que nous aborderons plus loin.
Un point important à noter : dans la nouvelle version de l'API, le paramètre images accepte un tableau d'objets, chaque objet fournissant soit image_url, soit file_id. Le file_id provient d'un pré-upload via l'API Files, ce qui est idéal pour les bibliothèques de ressources réutilisables ; image_url supporte les adresses publiques ou les URL de données en base64, parfait pour des requêtes ponctuelles. La limite de 50 Mo s'applique de la même manière aux deux méthodes.
🎯 Conseil pour vos tests : Si vous n'êtes pas sûr que vos images respectent les limites, le plus simple est d'envoyer une requête réelle et d'analyser le message d'erreur. Nous vous recommandons d'utiliser les interfaces compatibles OpenAI d'APIYI (apiyi.com) pour effectuer ces tests de limites. Le tableau de bord des logs de la plateforme permet de visualiser précisément la taille du corps de la requête et les détails des erreurs, ce qui est bien plus intuitif que de déboguer l'API officielle en direct.
Revenons à la question initiale : pourquoi la page de référence mentionne-t-elle 16 images sans préciser leur taille ? Il s'agit en réalité d'un choix de conception dans la structure de la documentation d'OpenAI. La page de référence de images/edit est organisée selon le "schéma des paramètres". Le paramètre images n'est qu'un tableau d'objets au niveau du schéma ; la limite de quantité fait donc partie des contraintes du tableau et y est inscrite. En revanche, la taille et le format des fichiers relèvent de la "validation à l'exécution" et sont classés dans les textes descriptifs du guide de génération d'images.
Il existe d'autres règles similaires "cachées dans le guide" qu'il vaut mieux vérifier avant de développer des fonctionnalités d'édition d'images :
- Les trois exigences pour le masque (mask) : il doit avoir le même format et les mêmes dimensions que l'image éditée, peser moins de 50 Mo et contenir un canal alpha. Utiliser un JPG comme masque est la cause d'erreur la plus fréquente, car le format JPG ne gère pas le canal alpha.
- La résolution n'est pas libre : le paramètre
sizede gpt-image-2 prend en charge des résolutions personnalisées, mais avec des contraintes strictes : le côté le plus long ne doit pas dépasser 3840 px, la largeur et la hauteur doivent être des multiples de 16 px, le rapport hauteur/largeur ne doit pas dépasser 3:1, et le nombre total de pixels doit se situer entre 655 360 et 8 294 400. - L'image d'entrée est facturée : l'image de référence dans une requête d'édition est facturée selon les jetons d'entrée d'image. Avec
input_fidelity: high, la consommation de jetons d'entrée augmente considérablement.
Contraintes de résolution et de paramètre size pour gpt-image-2
| Dimension de contrainte | Règle | Exemple |
|---|---|---|
| Côté le plus long | ≤ 3840 px | 3840×2160 (4K paysage) autorisé |
| Alignement des côtés | Multiples de 16 px | 1024, 1536, 2048 sont valides |
| Rapport hauteur/largeur | ≤ 3:1 | 2048×1152 valide, 3072×1024 valide |
| Total de pixels | 655 360 – 8 294 400 | En dessous de 768×854, la requête sera rejetée |
| Préréglages courants | 1024×1024 / 1536×1024 / 2048×2048 / 3840×2160 | Idem pour le mode portrait |
Si votre activité nécessite de basculer fréquemment entre différentes résolutions, je vous suggère d'intégrer ce tableau de contraintes dans une vérification locale avant l'envoi de la requête. Intercepter les dimensions invalides côté client permet d'économiser un aller-retour réseau par rapport à attendre une erreur 400 de l'API. Le centre de documentation d'APIYI (apiyi.com) propose également une liste de vérification des paramètres pour gpt-image-2, que vous pouvez utiliser directement pour votre implémentation.
Pratique de gpt-image-2 : 50 Mo est la limite, 1,5 Mo est le point idéal
Maintenant que vous connaissez la limite stricte de 50 Mo, la question la plus importante est : quelle taille d'image faut-il réellement transmettre dans vos projets ? Notre conseil est de maintenir chaque image autour de 1,5 Mo, et de ne pas dépasser 5 Mo. Ce n'est pas une estimation au hasard, il y a trois raisons majeures à cela.
La première est l'expansion liée au base64. Si vous intégrez des images via des data URL, l'encodage base64 augmente le volume d'environ 33 % — une image originale de 40 Mo approche les 53 Mo après encodage, et avec la structure JSON, la requête risque de dépasser la limite. Lorsque vous intégrez 16 images en base64, ce problème est multiplié par 16. Pour les ressources volumineuses, utilisez impérativement le canal de pré-téléchargement file_id.
La deuxième concerne le temps de transfert et de décodage. Au-delà de 5 Mo, le temps d'upload et de décodage côté serveur augmente de manière non linéaire. En cas d'instabilité réseau, cela déclenche souvent des délais d'attente (timeouts) et des tentatives de reconnexion, ce qui ralentit la génération globale. Une image d'environ 1,5 Mo se télécharge en 1 à 2 secondes sur une connexion domestique standard, ce qui représente le meilleur équilibre entre stabilité et qualité.
La troisième est la loi des rendements décroissants en termes de qualité. gpt-image-2 effectue un prétraitement interne sur les images d'entrée. Si la résolution d'entrée dépasse largement la résolution de sortie, les pixels excédentaires sont essentiellement gaspillés. Un JPG de 3840 px sur son côté le plus long, compressé à moins de 2 Mo, est visuellement indiscernable d'un PNG sans perte de 40 Mo pour l'édition, alors que le coût et le temps de traitement diffèrent d'un ordre de grandeur.
Recommandations pour la taille des images avec gpt-image-2
| État de l'image | Traitement suggéré | Résultat attendu |
|---|---|---|
| < 1,5 Mo | Upload direct | Vitesse et stabilité optimales |
| 1,5 Mo – 5 Mo | Upload direct, conversion JPG/WebP conseillée | Vitesse acceptable |
| 5 Mo – 20 Mo | Compression (côté long ≤ 3840px + qualité 85) | Qualité quasi intacte, temps réduit |
| 20 Mo – 50 Mo | Compression obligatoire, utiliser file_id |
Évite le dépassement via base64 |
| > 50 Mo | Dépasse la limite, compression indispensable | Sinon, erreur immédiate |
💡 Conseil pour les scénarios par lots : Pour les cas à haute concurrence comme le détourage e-commerce ou la stylisation par lots, nous recommandons une pré-compression via sharp ou Pillow ("côté long 3840px + qualité JPG 85"). Nous l'avons validé avec les clients entreprises d'APIYI (apiyi.com) : cette étape réduit le temps de traitement de bout en bout de plus de 40 % par requête d'édition, sans aucune plainte sur la qualité.
Démarrage rapide avec l'API gpt-image-2 : Exemple de code pour édition multi-images
gpt-image-2 suit le protocole d'interface standard d'OpenAI. Voici un exemple minimal d'édition avec plusieurs images de référence ; via le service proxy API d'APIYI, il suffit de remplacer la base_url :
import base64
from openai import OpenAI
client = OpenAI(
api_key="sk-your-apiyi-key",
base_url="https://api.apiyi.com/v1" # Interface unifiée APIYI
)
def to_data_url(path):
with open(path, "rb") as f:
b64 = base64.b64encode(f.read()).decode()
return f"data:image/jpeg;base64,{b64}"
result = client.images.edit(
model="gpt-image-2",
image=[to_data_url("product.jpg"), to_data_url("style-ref.jpg")],
prompt="Fusionnez l'image produit avec le style néon cyber de l'image de référence, en conservant le sujet intact",
input_fidelity="high", # Haute fidélité pour les détails, consomme plus de jetons d'entrée
size="2048x2048",
quality="high"
)
print(result.data[0].b64_json[:64]) # Retourne l'image résultante encodée en base64
Points clés sur les paramètres : lorsque input_fidelity est réglé sur high, la conservation des détails (visages, logos) est nettement améliorée, au prix d'une consommation accrue de jetons d'entrée ; quality et size sont les deux principaux leviers de coût de sortie ; le paramètre n permet de générer jusqu'à 10 images par requête. Côté facturation, gpt-image-2 est facturé au jeton : 5 $/M pour l'entrée texte, 8 $/M pour l'entrée image (2 $/M si hit en cache), et 30 $/M pour la sortie image. Rapporté à une seule image, le niveau "low" 1024×1024 coûte environ 0,006 $, le niveau "medium" environ 0,05 $, et le niveau "high" environ 0,21 $. La sortie reste toujours le poste de dépense principal.
Notez également que les limites de débit officielles dépendent du niveau de votre compte : le Tier 1 est limité à 5 images/minute, le Tier 4 à 150 images/minute, et le Tier 5 à 250 images/minute. Les nouveaux comptes ont un niveau bas, ce qui rend facile le dépassement des limites lors de tâches par lots. Utiliser une plateforme d'agrégation comme APIYI (apiyi.com) permet de contourner les limites par compte, ce qui est idéal pour les environnements de production nécessitant une génération massive et simultanée.
Différences de limites d'importation entre gpt-image-2 et les modèles de génération précédente
Si votre projet provient de gpt-image-1 ou de DALL·E 2, vous devez prêter attention à quelques différences générationnelles. Le changement le plus significatif a eu lieu entre DALL·E 2 et la série GPT image : l'interface d'édition de DALL·E 2 n'acceptait qu'une seule image PNG carrée de moins de 4 Mo. Avec la série GPT image, ces limites ont été assouplies pour permettre jusqu'à 16 images, 50 Mo et trois formats différents. La logique de prétraitement "PNG + compression 4 Mo" codée en dur dans de nombreux anciens projets peut être considérablement simplifiée après la migration.
La mise à niveau de gpt-image-2 par rapport à gpt-image-1 se concentre principalement sur la résolution et les coûts. gpt-image-1 ne prenait en charge que trois formats de sortie fixes (1024×1024, 1536×1024, 1024×1536), tandis que gpt-image-2 permet des résolutions personnalisées, allant jusqu'à une sortie 4K avec un bord long de 3840 px. Côté tarif, le coût d'entrée des images pour gpt-image-2 est passé de 10 $/M à 8 $/M, et le coût de sortie de 40 $/M à 30 $/M. Un nouveau palier de mise en cache à 2 $/M a également été ajouté, réduisant considérablement les coûts pour les scénarios utilisant des images de référence répétées.
Comparaison des limites d'importation entre gpt-image-2 et les modèles précédents
| Critère de comparaison | DALL·E 2 | gpt-image-1 | gpt-image-2 |
|---|---|---|---|
| Nombre d'images en entrée | 1 image | Jusqu'à 16 images | Jusqu'à 16 images |
| Limite de taille par image | < 4 Mo | < 50 Mo | < 50 Mo |
| Formats d'entrée | PNG carré uniquement | PNG/WebP/JPG | PNG/WebP/JPG |
| Résolution de sortie | Image carrée fixe | 3 tailles fixes | Personnalisée, bord long 3840px |
| Prix de sortie d'image | Facturation par image | 40 $/M tokens | 30 $/M tokens (cache entrée 2 $/M) |
| input_fidelity | Non pris en charge | Pris en charge | Pris en charge, meilleure fidélité des détails |
Lors de la migration du code, il suffit généralement de modifier le paramètre model, mais il est recommandé de mettre à jour simultanément la validation de la résolution et la stratégie de compression en suivant les contraintes du tableau ci-dessus. Si vous souhaitez vérifier les résultats de la migration avant de modifier le code de production, vous pouvez utiliser APIYI (apiyi.com) pour appeler les deux générations de modèles avec le même ensemble de ressources, afin de comparer visuellement la qualité de l'édition et les différences de facturation réelles.
FAQ sur l'importation d'images pour gpt-image-2
Q1 : Quelle est la taille maximale autorisée pour une seule image dans gpt-image-2 ?
La limite stricte est de 50 Mo, avec prise en charge des formats PNG, WebP et JPG. Cette limite figure dans le guide d'utilisation de la génération d'images d'OpenAI, et non dans le tableau des paramètres de référence de l'API images/edit, ce qui explique pourquoi elle est difficile à trouver sur la page de référence. En pratique, il est conseillé de rester entre 1,5 et 5 Mo pour une expérience optimale.
Q2 : Comment fonctionne la limite de 16 images ?
Le paramètre images accepte jusqu'à 16 objets image, chaque objet étant spécifié par une image_url ou un file_id. Le modèle traitera plusieurs images comme une référence combinée, ce qui est idéal pour les scénarios d'édition combinant "image produit + image de style + référence de composition". Notez que 16 est la limite d'entrée, tandis que le nombre de sorties est contrôlé par le paramètre n, avec une limite de 10 images.
Q3 : Quelle est la cause habituelle de l'erreur "invalid mask" ?
Dans 90 % des cas, il s'agit d'un problème de canal alpha. Le masque doit avoir le même format et les mêmes dimensions que l'image éditée, et doit impérativement inclure un canal alpha. Le format JPG ne prenant pas en charge le canal alpha, le masque doit obligatoirement être au format PNG. Les zones transparentes indiquent les zones "autorisées à être redessinées", tandis que les zones opaques restent inchangées.
Q4 : Comment choisir entre l'importation en base64 et l'importation par file_id ?
Pour les petites images (< 5 Mo) ou les requêtes ponctuelles, l'utilisation d'une URL de données base64 est la plus simple. Pour les images volumineuses ou les ressources nécessitant une réutilisation fréquente, utilisez l'API Files pour un pré-téléchargement afin d'obtenir un file_id. Cela permet d'éviter l'augmentation de volume de 33 % liée au base64 et facilite la réutilisation entre les requêtes. En cas de doute, vous pouvez tester les deux méthodes sur la console APIYI (apiyi.com) et comparer les temps de traitement réels avant de choisir votre solution.
Résumé : les trois chiffres clés des limites d'upload de gpt-image-2
Pour revenir à notre question initiale, les limites de l'API d'édition d'images gpt-image-2 peuvent se résumer en trois chiffres : 16 images (limite maximale d'images en entrée unique, indiquée dans la documentation de référence), 50 Mo (limite de taille par image, indiquée dans le guide d'utilisation) et 1,5 Mo (la taille idéale pour une pratique optimale en ingénierie). Le fait que la documentation sépare le nombre et la taille sur deux pages différentes est la source de la confusion autour de cette limite de "16 images".
Les recommandations pour la mise en œuvre sont simples : avant l'upload, compressez systématiquement vos images pour que le côté le plus long soit inférieur à 3840 px, avec une qualité JPG autour de 85 ; utilisez toujours des PNG avec canal alpha pour les masques ; et passez les fichiers volumineux par le canal file_id. En faisant de ces trois points une étape de prétraitement systématique avant chaque requête, vous pourrez pratiquement dire adieu à toutes les erreurs liées à l'upload.
Si vous avez besoin d'invoquer gpt-image-2 de manière stable depuis la Chine, ou si vous souhaitez augmenter vos limites de débit pour un usage en production, vous pouvez passer par l'interface unifiée d'APIYI (apiyi.com). Elle est compatible avec le SDK natif d'OpenAI, il suffit de modifier une ligne de base_url pour migrer.
Références : OpenAI API Reference : developers.openai.com/api/reference/resources/images/methods/edit
Auteur : Équipe APIYI
Spécialisés dans l'agrégation d'API de grands modèles de langage et les meilleures pratiques. Pour plus d'évaluations de modèles et de guides d'intégration, visitez APIYI sur apiyi.com.
