Paramètres de l’API GPT Image 2 : taille, résolution, ratio et qualité

L’API GPT Image 2 reçoit le nom du modèle dans model, les dimensions de sortie dans size sous la forme WIDTHxHEIGHT en pixels, et la qualité dans quality (low, medium, high ou auto). Il n’existe pas de champ resolution ni aspect_ratio. Pour obtenir une image 16:9 en 4K, vous envoyez "size": "3840x2160". Les tailles doivent utiliser des multiples de 16, garder chaque côté à 3 840 pixels au plus, rester entre 1:3 et 3:1, et totaliser entre 655 360 et 8 294 400 pixels.

Ce guide passe en revue chaque paramètre qui modifie l’image, avec la valeur exacte à envoyer et l’erreur que renvoie une valeur incorrecte. Chaque erreur ci-dessous a été vérifiée sur l’API en production.

Quel est le nom du modèle GPT Image 2 dans l’API ?

Utilisez gpt-image-2 ou gpt-image-2-official. Il s’agit du même modèle avec les mêmes champs ; gpt-image-2 facture un prix fixe par image livrée, et gpt-image-2-official facture les tokens déclarés par chaque rendu.

Les noms tirés des titres ne fonctionnent pas comme ID de modèle. gpt-image-2.0, GPT Image 2 ou chatgpt-images-2 renvoient tous HTTP 400 avec le code d’erreur 20002.

Comment définir la résolution et le ratio d’image ?

Avec size, en pixels. Choisissez le ratio et le budget de pixels souhaités, puis envoyez la largeur et la hauteur correspondantes :

Ce sont les mêmes conversions que celles du Playground quand vous choisissez un ratio et un préréglage 1K, 2K ou 4K. Le carré en 4K s’arrête à 2880x2880, car un carré de 3 840 pixels dépasserait la limite totale de pixels.

size: "auto" laisse les dimensions au modèle. C’est la valeur par défaut, et elle est pratique, mais définissez une taille explicite lorsque les sorties doivent correspondre à une mise en page ou entre elles.

OpenAI qualifie d’expérimentale toute sortie au-delà de 2560×1440. Elle est acceptée dans les limites indiquées ici, mais une toile plus grande ne garantit pas davantage de détails.

Quelles valeurs de taille sont rejetées ?

Notez les deux dernières lignes. Un champ inconnu est rejeté, mais l’erreur ne le nomme pas. Si vous obtenez 20001 avec le message général « Check the parameters against the API documentation », cherchez un champ que l’API n’accepte pas, comme resolution, aspect_ratio ou response_format.

Quelle qualité choisir ?

quality accepte low, medium, high et auto. Les niveaux supérieurs prennent plus de temps et conservent des détails plus fins. xhigh et max sont propres à GPT Image 2.5 ; les envoyer à GPT Image 2 renvoie 20001 avec un message qui nomme quality.

Une routine pratique : faites vos brouillons en low tant que la composition évolue, vérifiez la texture et le petit texte en medium, et produisez les versions finales en high. Sur gpt-image-2, le prix est le même à chaque niveau. Sur gpt-image-2-official, les niveaux supérieurs déclarent davantage de tokens de sortie et coûtent donc plus cher. Le guide des tarifs donne les chiffres.

auto laisse le modèle choisir le niveau. Définissez une valeur explicite quand vous comparez des rendus, sinon deux requêtes « identiques » peuvent être rendues à des niveaux différents.

Qu’est-ce qui contrôle le format et l’arrière-plan ?

• output_format : png (par défaut) ou jpeg. La sortie WebP n’est pas proposée ; webp renvoie 20001 avec un message qui nomme output_format.
• output_compression : de 0 à 100, uniquement avec jpeg.
• background : auto, opaque ou transparent. La transparence nécessite png ; transparent avec jpeg renvoie 20001 avec un message qui nomme background.
• n : de 1 à 10 images par requête. Vous êtes facturé pour les images livrées.
• moderation : auto ou low.

Comment passer les images de référence et les masques ?

Sous forme d’URL, jamais sous forme de fichiers ou de base64. images accepte de 1 à 16 objets de la forme {"image_url": "https://..."}, et l’envoyer transforme la requête en retouche. mask accepte un objet de même forme : un PNG de la taille de la première image de référence, dont la zone transparente indique ce qu’il faut modifier. La référence liste les limites de fichiers.

Questions fréquentes

GPT Image 2 prend-il en charge la 4K ?

Oui, dans les limites ci-dessus. 3840x2160 pour le 16:9 et 2160x3840 pour le 9:16 sont les plus grands cadres, et 2880x2880 est le plus grand carré.

Puis-je envoyer un ratio au lieu de pixels ?

Pas à l’API. Convertissez d’abord le ratio en une taille WIDTHxHEIGHT, à l’aide du tableau ci-dessus ou du Playground, qui affiche la taille exacte avant l’envoi.

Quelles sont la taille et la qualité par défaut ?

Les deux valent auto par défaut, ce qui laisse le choix au modèle. Envoyez des valeurs explicites quand vous avez besoin d’une sortie prévisible.

Envoyez des pixels, fixez la qualité, lisez le message d’erreur

Presque tous les problèmes de paramètres relèvent de trois cas : un ratio envoyé comme taille, un champ que l’API n’accepte pas, ou une valeur hors limites. Dans le premier et le troisième cas, le message d’erreur nomme le champ ; un message général qui ne nomme aucun champ pointe vers le deuxième. Gardez cette page à côté de la référence de l’API GPT Image 2 pendant votre intégration.