How to Use GPT Image 1K, 2K, 4K, Quality, and Mask: BetterToken Test Guide

• Why do calls with the same model and parameters produce different results at different times?
• Why does a request for 4K or a specific size sometimes return a downgraded 1K image?
• When you use Mask for local editing or quality=high, does it actually take effect? What standard is used to charge for the result?

Note: This guide focuses on gpt-image-2, gpt-image-2.5-flare, and gpt-image-2.5-sunburst. The Nano Banana model series has different parameters and billing, which we will cover separately to avoid confusion.

​

1. Why can the same model and parameters produce different results?

​

2. How did we test: what counts as “supported”?

1. Decode the original file’s pixels: We do not rely on API declarations. For every delivered image, we decode the original file to read its width and height, then compare the billing tier in the response with the actual account deduction.
2. Determine whether dimensions meet the target: We compare the actual width and height with each explicitly requested dimension. A larger returned dimension passes; if either dimension is more than 5% smaller than the target, the result fails (Note: this criterion is used to evaluate test results strictly. It does not mean the API automatically discards valid images that miss the requested dimensions.) If dimensions are omitted or set to auto, we treat the request as having no fixed-canvas target.
3. Report parameter acceptance and actual results separately: An error-free response means only that “the parameter was accepted.” Whether Mask achieves strict region isolation and whether quality=high produces a perceptible improvement must be judged from the final image.

​

3. What did the tests find: which parameters are easiest to misunderstand?

• Default-parameter tolerance: Image generation works whether quality and size are omitted, passed as null, or explicitly set to "auto".
• How to request 4K correctly: “4K” is a billing-tier concept; it does not mean that a 4096x4096 square image is supported. To request a high-resolution image at the 4K level, use the landscape size 3840x2160.
• Invalid parameters rejected without billing: Requests with 4096x4096, stream=true, an empty quality="", an empty size="", or n=0 all returned HTTP 400 errors and incurred no charge at all.

​

4. What does BetterToken provide: no need to adapt each route yourself

1. Intelligent routing based on capabilities: The system automatically matches your model, target size (such as 2K/4K), and whether your request includes image-editing/Mask parameters to an available service with the corresponding capabilities.
2. Unified API and parameter fallbacks: The standardized POST /v1/images/generations (image generation) and POST /v1/images/edits (reference-image/Mask editing) endpoints automatically handle null, auto, and omitted parameters, and reject invalid input directly at the gateway layer.
3. Transparent reporting of actual dimensions and billing details: Along with the image data, the bettertoken_image_billing field in the response body tells you the image’s actual decoded width and height (width/height), billing tier (billing_resolution), currency, and settlement amount (settled_amount).
4. A clear distinction between two core concepts:
   • Supporting the Mask parameter ≠ pixel-precise inpainting: The API supports uploading a reference image and Mask for editing, but some test results also changed protected areas outside the mask. For example, in our geometric two-circle test, the left circle was transparent and requested to change color, while the right circle was opaque and meant to be protected; both circles changed color in the result. Therefore, we explicitly support passing the Mask parameter, but do not guarantee strict pixel-level region isolation every time.
   • Supporting the quality parameter ≠ guaranteeing a fixed degree of image-quality improvement: The API accepts parameters such as "auto" or "high" and routes them correctly. However, because every image generation is stochastic, we do not overstate based on a single sample that high will always improve quality by a particular percentage.

⚠️ Two real limitations to understand before integration:

1. Capability-based routing does not mean pixels are strictly fixed on every request: Due to differences in underlying service outputs, actual pixels can fluctuate even when routing reaches the appropriate node. For example, today’s samples still include a request for 1024x1024 that returned 1024×936, and a request for 3840x2160 that returned 3840×2161. If your business is highly sensitive to canvas proportions, crop or post-process based on the actual dimensions returned.
2. A 1K request may not ultimately be billed at 1K: The billing system assigns a tier based on the specification of the valid image actually delivered. Today, the two 2.5 models (and gpt-image-2 in some cases) returned 1254×1254 images with more pixels when asked for 1024x1024; the system classified these as 2K-tier images and billed them accordingly.

​

5. Support across the 3 models: which model should I call, and what value should I pass?

​

6. Two real image examples: what do the results actually look like?

​

Example A: Ecommerce product photography, showing 1K / 2K / 4K sizes and details

Generate a realistic ecommerce studio photograph: a coral-red ceramic mug (handle facing right) sits on a pale gray stone countertop, with a folded beige linen cloth to its left. The mug has the clear white text “BETTER DAY” printed on it. Soft side lighting from the upper left; retain subtle reflections on the ceramic glaze, linen fibers, and natural contact shadows. Keep the entire mug centered in frame, with a simple neutral background and no other objects, watermark, or extra text.

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.

• High visual completeness: All three images show the coral-red glaze reflections, right-side handle, pale gray stone tabletop, beige linen fibers, and clearly readable white “BETTER DAY” lettering.
• Differences from independent sampling: Each generation is an independent sample, so the mug’s proportions, font weight, and cloth folds naturally differ (for example, the lettering in the 4K landscape image is arranged on two lines). The cropped images show the actual details in each image; they are not a controlled optical sharpness test with identical compositions.
• Billing boundary shown directly: Although the first request was for 1024x1024, it delivered a high-resolution 1254×1254 square image, so it was billed at the same 2K tier (¥0.11) as the second 2048×2048 image.

​

Example B: Local product recoloring, showing the actual effect and limits of Mask

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

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.

• The main recoloring request was achieved: The outside of the mug body successfully turned deep navy blue while retaining ceramic highlights. The red handle outside the mask, the linen on the left, and the background were generally preserved; the “BETTER DAY” lettering inside the mask remained readable.
• Strict Mask boundary failed (changes spread beyond the mask): A close look at the rim and inner wall shows that the coral-red areas originally inside the opaque protected region were also changed to deep blue. In the more extreme geometric “two circles changed color” test, the unmasked right-hand circle also changed color.
• Usage recommendation: When uploading a reference image and Mask, make sure their canvas dimensions match (transparent where changes are allowed, opaque where content must be preserved), and state both “what to change” and “what to preserve” in the prompt. For industrial or commercial images with brand logos, small packaging text, or strict edge requirements, always zoom in and inspect protected-area boundaries after generation.

​

7. Prices and actual usage costs: what are you ultimately charged?

💡 Key budgeting point: estimate costs by the “actual delivered tier,” not the “request parameter”! As shown in the tests above, some requests sent today to flare, sunburst, or gpt-image-2 for 1024x1024 (1K) delivered 1254×1254 images. The system therefore assigned the actual result to 2K (charging ¥0.15 or ¥0.11, rather than the 1K price of ¥0.035). If all 100 1024x1024 requests to flare returned 1254×1254, those 100 images would cost ¥15.00 (arithmetic estimate) at current prices. The system also assigns tiers using the target dimensions and a reasonable deviation threshold (for example, 3840×2159 is normally assigned to 4K and 1536×1024 to 1K). Do not hard-code a recalculation in your business logic based only on whether “the longest side is greater than 1024.” Always use the bettertoken_image_billing field in the response body as the billing source of truth.

​

Why can’t you look only at the “low price per image” on the surface?

1. A quote is comparable only when the actual result meets the target dimensions: A request advertised as “4K supported at a very low price” that actually returns a downgraded 1024 image cannot be used in a production environment that needs high-resolution images, so it is not a valid 4K price for comparison.
2. Include failures and rework in the total cost: The invalid-parameter tests in this round were free. If an image was successfully delivered but the result was unsatisfactory, submitting another generation is a new request and should be budgeted separately. The 4 product and Mask case images shown in this guide (3 generated images + 1 edit) were each delivered in a single request. The Mask sample had the out-of-mask recoloring described above. Their prices were ¥0.11, ¥0.11, ¥0.13, and ¥0.11, for a real total cost of only ¥0.46 for all 4 images, matching the bill and account deduction exactly. If unstable routes or incompatible parameters force repeated generation, the actual all-in cost of getting one usable asset can rise even when the quoted price per image is low.
3. Reduce hidden engineering adaptation costs: BetterToken’s unified parameter conventions, capability-based intelligent routing, and real-time pixel and billing fields reduce the development work needed to adapt each service and compile size and cost information yourself.

​

8. Copy-ready request examples

​

Example 1: JSON request to generate a high-resolution product image (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

• Size specification: For a 4K landscape image, change "size" to "3840x2160" (do not use "4096x4096"). Valid dimensions must currently meet all of these conditions: width and height are both multiples of 16, the longest side is no more than 3840, the aspect ratio of long side to short side is no more than 3:1, and the total pixel count is between 655,360 and 8,294,400.
• File format identification: Even when the request specifies "output_format": "png", some underlying nodes may return binary content in JPEG format. When saving or processing images, identify the actual image format from its header (Magic Bytes); do not hard-code the file extension.

​

Example 2: Multipart reference image and Mask-based local editing (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"

​

Example 3: Read actual delivered pixels and billing information (response structure and parsing code)

{
  "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']}")

• OpenAI official documentation: Image Prompting Guide
• OpenAI Cookbook: Image generation and editing with high input fidelity