Comment utiliser 1K, 2K, 4K, Quality et Mask avec GPT Image : guide de tests BetterToken

• Pourquoi les résultats diffèrent-ils d’un appel à l’autre avec le même modèle et les mêmes paramètres ?
• Pourquoi l’image reçue est-elle réduite à 1K alors que j’ai demandé 4K ou une dimension précise ?
• La retouche locale avec Mask ou quality=high a-t-elle réellement fonctionné ? Selon quel critère la facturation finale est-elle calculée ?

Remarque : ce guide porte sur gpt-image-2, gpt-image-2.5-flare et gpt-image-2.5-sunburst. Les paramètres et la facturation de la série Nano Banana sont différents ; ils feront l’objet d’un autre article afin d’éviter toute confusion.

​

1. Pourquoi les résultats peuvent-ils varier avec le même modèle et les mêmes paramètres ?

​

2. Notre méthode de test : que signifie « pris en charge » ?

1. Décoder les pixels du fichier original : nous ne nous fions pas à la seule déclaration de l’API. Nous décodons les dimensions de chaque image livrée à partir du fichier d’origine, puis nous les comparons au niveau de facturation indiqué dans la réponse et au débit réel du compte.
2. Vérifier que les dimensions sont atteintes : nous comparons séparément la largeur et la hauteur explicitement demandées. Une dimension réelle supérieure est considérée comme conforme ; si l’un des côtés est inférieur de plus de 5% à la dimension cible, le résultat n’est pas conforme (remarque : ce critère sert à évaluer rigoureusement les résultats du test ; cela ne signifie pas que l’API rejette automatiquement les images valides qui n’atteignent pas la dimension demandée). Si la dimension est omise ou que auto est transmis, aucun canevas fixe n’est défini comme objectif.
3. Distinguer l’acceptation des paramètres du résultat réel : l’absence d’erreur signifie seulement que « le paramètre a été accepté ». Pour savoir si Mask isole strictement une zone ou si quality=high apporte un gain visuel, il faut examiner l’image finale.

​

3. Résultats des tests : quels paramètres sont le plus souvent mal compris ?

• Tolérance aux paramètres par défaut : la génération fonctionne normalement si quality et size sont omis, transmis comme null ou explicitement définis sur "auto".
• Comment demander correctement du 4K : « 4K » désigne un niveau de facturation et ne signifie pas que les images carrées 4096x4096 sont prises en charge. Pour une grande image horizontale de niveau 4K, utilisez 3840x2160.
• Blocage des paramètres invalides sans frais : les requêtes de test envoyant 4096x4096, stream=true, une chaîne vide quality="", une chaîne vide size="" ou n=0 ont toutes renvoyé une erreur HTTP 400 et n’ont généré aucun frais.

​

4. Ce que propose BetterToken : pas besoin d’adapter chaque route

1. Routage intelligent selon les capacités : le système sélectionne automatiquement un service disponible doté des capacités correspondantes selon le modèle transmis, la dimension cible (par exemple 2K/4K) et la présence de paramètres d’édition d’image ou de Mask.
2. Interface unifiée et valeurs de repli pour les paramètres : les interfaces standard POST /v1/images/generations (génération d’image) et POST /v1/images/edits (édition à partir d’une image de référence/Mask) traitent automatiquement null, auto et les paramètres omis, et bloquent les entrées invalides au niveau de la passerelle.
3. Retour transparent des dimensions réelles et du détail de facturation : en plus des données d’image, le champ bettertoken_image_billing du corps de réponse indique directement la largeur et la hauteur décodées réelles (width/height), le niveau de facturation (billing_resolution), la devise et le montant réglé (settled_amount).
4. Distinction claire entre deux notions essentielles :
   • La prise en charge du paramètre Mask ≠ une retouche précise au pixel près : l’interface permet de charger une image de référence et une Mask pour effectuer une édition, mais certains résultats de test ont également modifié des zones protégées à l’extérieur du masque. Par exemple, lors de notre test géométrique des deux cercles, le cercle gauche transparent devait changer de couleur et le cercle droit opaque devait être protégé ; les deux cercles ont finalement changé de couleur. Ainsi, nous confirmons la prise en charge du paramètre Mask, mais ne garantissons pas un isolement strict au pixel près à chaque appel.
   • La prise en charge du paramètre quality ≠ une amélioration de qualité garantie et fixe : l’interface accepte des valeurs comme "auto" ou "high" et les route correctement. Toutefois, la génération étant aléatoire, nous ne promettons pas, sur la base d’un seul échantillon, que high produira une amélioration d’un pourcentage donné.

⚠️ Deux limites réelles à connaître avant l’intégration :

1. Le routage par capacité ne garantit pas un nombre de pixels strictement fixe à chaque appel : en raison des différences de sortie des services sous-jacents, les pixels peuvent varier même si la requête est dirigée vers le bon nœud (par exemple, certaines requêtes 1024x1024 ont aujourd’hui renvoyé 1024×936 et certains échantillons demandant 3840x2160 ont renvoyé 3840×2161). Si le rapport du canevas est essentiel à votre activité, utilisez les dimensions réelles renvoyées pour recadrer ou post-traiter l’image.
2. Demander du 1K ne signifie pas nécessairement payer le tarif 1K : le système classe l’image selon les dimensions valides réellement livrées. Aujourd’hui, les deux modèles 2.5 (et certains cas de gpt-image-2) ont renvoyé 1254×1254 pour des demandes 1024x1024 ; le système les a donc classées au niveau 2K et a appliqué le tarif correspondant.

​

5. Prise en charge des trois modèles : lequel appeler et quelles valeurs transmettre ?

​

6. Deux exemples d’images réelles : quels sont les résultats ?

​

Exemple A : photographie de produit pour le commerce en ligne, dimensions et détails en 1K / 2K / 4K

Générer une véritable photo de studio pour le commerce en ligne : un mug en céramique rouge corail (anse orientée vers la droite) posé sur un plan de travail en pierre gris clair, avec un linge en lin beige plié à gauche. Le mug porte le texte blanc bien net « BETTER DAY ». Lumière latérale douce venant du haut à gauche ; conserver les reflets subtils de l’émail céramique, les fibres du lin et les ombres de contact naturelles. Le mug est entièrement visible et centré ; arrière-plan neutre et simple, sans autres objets, filigrane ni texte supplémentaire.

Photorealistic ecommerce studio photograph. A coral-red ceramic mug with a handle on the right sits on a pale gray stone tabletop, with a folded beige linen cloth to its left. The mug reads "BETTER DAY" in clear white lettering. Soft directional light from upper left, subtle glaze reflections, visible linen fibers and natural contact shadows. Entire mug in frame, centered composition, simple neutral background. No other objects, no watermark, no additional text.

• Rendu soigné : les trois images montrent les reflets de l’émail rouge corail, l’anse à droite, le plan de travail en pierre gris clair, les fibres du linge en lin beige et le texte blanc « BETTER DAY » bien lisible.
• Différences entre échantillons indépendants : chaque génération est un échantillon indépendant ; les proportions du mug, l’épaisseur de la police et le pliage du tissu varient naturellement (par exemple, le texte est disposé sur deux lignes dans l’image horizontale 4K). Les recadrages montrent donc les détails réels de chaque image et ne constituent pas une expérience optique de netteté avec une composition strictement identique.
• Limite de facturation illustrée directement : bien que la première image ait été demandée en 1024x1024, elle a été livrée en image carrée haute définition 1254×1254 et facturée au niveau 2K (¥0.11), comme la deuxième image en 2048×2048.

​

Exemple B : changement local de couleur d’un produit, résultat réel et limites de Mask

Remplacer uniquement le corps rouge corail du mug dans la zone transparente du masque par un bleu marine foncé. Préserver la matière céramique, l’éclairage et les reflets. Garder inchangés le texte blanc « BETTER DAY », l’anse rouge, le linge en lin, le plan de travail, l’arrière-plan et la composition générale. N’ajouter ni supprimer aucun objet.

Change only the coral-red mug body inside the transparent mask to deep navy blue. Preserve ceramic texture, lighting and reflections. Keep the white "BETTER DAY" lettering, red handle, linen cloth, tabletop, background and composition unchanged. Do not add or remove any objects. Do not change anything outside the transparent mask.

• L’objectif principal de recoloration est atteint : le corps extérieur du mug devient bleu marine foncé et conserve son éclat céramique ; l’anse rouge hors masque, le linge en lin à gauche et l’arrière-plan sont préservés, et le texte « BETTER DAY » dans le masque reste lisible.
• La limite stricte de Mask n’est pas respectée (débordement) : en observant le bord et la paroi intérieure du mug, on constate que la partie rouge corail initialement dans la zone protégée opaque a elle aussi été recolorée en bleu foncé. Dans le test géométrique plus extrême des « deux cercles », le cercle droit non masqué a également changé de couleur.
• Conseil d’utilisation : lors de l’envoi d’une image de référence et d’une Mask, assurez-vous qu’elles ont les mêmes dimensions de canevas (zone à modifier transparente, zone à préserver opaque) et indiquez dans le Prompt à la fois « ce qui doit changer » et « ce qui doit être conservé ». Pour les images commerciales industrielles avec logo de marque, petits textes d’emballage ou exigences strictes sur les contours, agrandissez l’image après génération et vérifiez les limites de la zone protégée.

​

7. Tarifs et coût réel d’utilisation : quel est le montant facturé ?

💡 Point essentiel pour le budget : calculez selon le « niveau réellement livré », et non selon les « paramètres demandés ». Comme le montrent les tests ci-dessus, certaines requêtes 1024x1024 (1K) envoyées aujourd’hui à flare, sunburst ou gpt-image-2 ont livré des images 1254×1254. Le système les classe alors au niveau 2K selon la dimension réelle (soit ¥0.15 ou ¥0.11, et non le tarif 1K de ¥0.035). Si les 100 requêtes 1024x1024 envoyées à flare renvoyaient toutes 1254×1254, le coût des 100 images aux tarifs actuels serait de ¥15.00 (estimation arithmétique). En outre, la classification tient compte de la dimension cible et d’un seuil d’écart raisonnable (par exemple, 3840×2159 est normalement classé en 4K, et 1536×1024 en 1K). Ne recalculez pas les frais côté application selon une règle simpliste telle que « le côté le plus long dépasse 1024 » ; le règlement est toujours déterminé par le champ bettertoken_image_billing du corps de réponse.

​

Pourquoi ne pas se fier uniquement au « faible prix par image » ?

1. Le tarif n’est comparable que si la réponse réelle atteint la dimension visée : une requête annoncée comme « compatible 4K à très bas prix », mais qui ne renvoie qu’une petite image réduite en 1024, ne peut pas être utilisée en production nécessitant des images haute définition et ne doit pas être comparée comme un tarif 4K valable.
2. Intégrez les échecs et le coût des nouvelles tentatives dans le total : les tests de paramètres invalides de cette série n’ont pas été facturés ; lorsqu’une image est bien livrée mais ne répond pas au besoin, la soumettre à nouveau constitue une nouvelle requête à budgéter séparément. Les 4 images des exemples de produits et Mask de ce guide (3 générations + 1 retouche) ont chacune été livrées en un seul appel. L’échantillon Mask présente le débordement de couleur mentionné ci-dessus. Les tarifs unitaires étaient ¥0.11, ¥0.11, ¥0.13 et ¥0.11, soit un coût réel total de seulement ¥0.46 pour les 4 images ; la facture correspond exactement aux débits du compte. Si l’instabilité de la route ou l’incompatibilité des paramètres oblige à répéter les générations, le coût réel d’obtention d’un visuel utilisable peut augmenter même si le prix affiché par image est faible.
3. Réduisez les coûts d’ingénierie d’adaptation cachés : grâce à la normalisation des paramètres, au routage intelligent selon les capacités et au retour en temps réel des pixels et champs de facturation réels, BetterToken réduit le travail consistant à adapter chaque service et à compiler séparément les dimensions et les coûts.

​

8. Exemples d’appels prêts à copier

​

Exemple 1 : requête JSON pour générer une image de produit haute définition (POST /v1/images/generations)

curl https://bettertoken.ai/v1/images/generations -o response.json \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{
  "model": "gpt-image-2",
  "prompt": "Photorealistic ecommerce studio photograph. A coral-red ceramic mug with a handle on the right sits on a pale gray stone tabletop, with a folded beige linen cloth to its left. The mug reads \"BETTER DAY\" in clear white lettering. Soft directional light from upper left, subtle glaze reflections, visible linen fibers and natural contact shadows. Entire mug in frame, centered composition, simple neutral background. No other objects, no watermark, no additional text.",
  "size": "2048x2048",
  "quality": "high",
  "n": 1,
  "response_format": "b64_json",
  "output_format": "png"
}
JSON

• Remarque sur les dimensions : pour une image horizontale 4K, remplacez "size" par "3840x2160" (n’utilisez pas "4096x4096"). Les dimensions valides doivent actuellement respecter les critères suivants : largeur et hauteur multiples de 16, côté le plus long inférieur ou égal à 3840, rapport entre le côté long et le côté court inférieur ou égal à 3:1, et nombre total de pixels compris entre 655,360 et 8,294,400.
• Remarque sur l’identification du format de fichier : même si la requête spécifie "output_format": "png", certains nœuds sous-jacents peuvent renvoyer des données binaires au format JPEG. Lors de l’enregistrement ou du traitement de l’image, identifiez le format réel à partir de l’en-tête du fichier (Magic Bytes) plutôt que de coder l’extension en dur.

​

Exemple 2 : retouche locale Multipart avec image de référence et Mask (POST /v1/images/edits)

curl https://bettertoken.ai/v1/images/edits -o response.json \
  -H "Authorization: Bearer $BETTERTOKEN_API_KEY" \
  -F "model=gpt-image-2" \
  -F "image=@product-1k-0.png;type=image/png" \
  -F "mask=@mask-mug.png;type=image/png" \
  -F 'prompt=Change only the coral-red mug body inside the transparent mask to deep navy blue. Preserve ceramic texture, lighting and reflections. Keep the white "BETTER DAY" lettering, red handle, linen cloth, tabletop, background and composition unchanged. Do not add or remove any objects. Do not change anything outside the transparent mask.' \
  -F "size=2048x2048" \
  -F "quality=high" \
  -F "n=1" \
  -F "response_format=b64_json"

​

Exemple 3 : lecture des pixels livrés et des informations de facturation (structure de réponse et code d’analyse)

{
  "created": 1792398084,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA..."
    }
  ],
  "bettertoken_image_billing": {
    "currency": "CNY",
    "settled_amount": "0.11",
    "outputs": [
      {
        "index": 0,
        "width": 2048,
        "height": 2048,
        "billing_resolution": "2K",
        "currency": "CNY",
        "amount": "0.11"
      }
    ]
  }
}

import base64
import io
import json
from pathlib import Path
from PIL import Image  # 需要 Pillow

# 将 API 的 JSON 响应保存为 response.json 后执行。
resp_json = json.loads(Path("response.json").read_text())
if "error" in resp_json:
    raise RuntimeError(resp_json["error"])

billing = resp_json["bettertoken_image_billing"]
outputs = {item["index"]: item for item in billing["outputs"]}
for index, item in enumerate(resp_json["data"]):
    img_bytes = base64.b64decode(item["b64_json"], validate=True)
    with Image.open(io.BytesIO(img_bytes)) as image:
        image.load()
        width, height = image.size
        ext = {"PNG": "png", "JPEG": "jpg", "WEBP": "webp"}.get(image.format)
        if ext is None:
            raise ValueError(f"未处理的图片格式：{image.format}")
    Path(f"output_{index}.{ext}").write_bytes(img_bytes)
    info = outputs[index]
    print(f"图片 {index}：原图 {width}×{height}；计费档位 {info['billing_resolution']}")
    print(f"单张费用：{info['amount']} {info['currency']}")
    if (width, height) != (info["width"], info["height"]):
        print("图片像素与响应尺寸不一致，请保留结果并联系支持。")
print(f"本次结算：{billing['settled_amount']} {billing['currency']}")

• Documentation officielle d’OpenAI : guide de rédaction des prompts d’image (Image Prompting Guide)
• OpenAI Cookbook : exemple de génération et de retouche d’images avec haute fidélité d’entrée