Cómo usar 1K, 2K, 4K, Quality y Mask en GPT Image: guía de pruebas de BetterToken

• ¿Por qué varían los resultados entre llamadas con el mismo modelo y los mismos parámetros?
• ¿Por qué, aunque se solicite 4K o un tamaño específico, la imagen recibida se reduce a 1K?
• ¿El retoque localizado con Mask o quality=high realmente se aplica? ¿Con qué criterio se cobra al final?

Nota: Esta guía se centra en gpt-image-2, gpt-image-2.5-flare y gpt-image-2.5-sunburst. Los parámetros y el sistema de facturación de la serie Nano Banana son diferentes; los explicaremos en otro artículo para evitar confusiones.

​

1. ¿Por qué pueden variar los resultados con el mismo modelo y los mismos parámetros?

​

2. Cómo probamos: ¿qué consideramos «compatible»?

1. Decodificar los píxeles del archivo original: no confiamos sin más en lo que declara la interfaz. Decodificamos las dimensiones de cada imagen entregada a partir del archivo original y las contrastamos con el nivel de facturación indicado en la respuesta y el cargo real en la cuenta.
2. Determinar si se alcanza el tamaño: comparamos por separado el ancho y el alto solicitados de forma explícita. Si las dimensiones reales son mayores, se considera aprobado; si cualquiera de los lados queda más de un 5% por debajo del tamaño objetivo, se considera que no lo alcanza (nota: este criterio sirve para evaluar estrictamente los resultados de la prueba; no significa que la API descarte automáticamente las imágenes válidas que no alcancen el tamaño solicitado). Si se omite el tamaño o se envía auto, no se considera que haya un lienzo fijo como objetivo.
3. Separar la aceptación de parámetros del resultado real: que la interfaz no dé error solo significa que «acepta el parámetro». Para determinar si Mask aísla estrictamente una zona o si quality=high mejora la imagen de forma visible, hay que examinar el resultado final.

​

3. Resultados de las pruebas: ¿qué parámetros se malinterpretan con más facilidad?

• Tolerancia a parámetros predeterminados: la imagen se genera correctamente tanto si quality y size se omiten, se envían como null o se especifican como "auto".
• Cómo solicitar 4K correctamente: «4K» es un concepto de nivel de facturación y no significa que se admitan imágenes cuadradas de 4096x4096. Para obtener una imagen grande de alta resolución de nivel 4K, usa el tamaño horizontal 3840x2160.
• Bloqueo de parámetros no válidos sin cargos: al enviar 4096x4096, stream=true, una cadena vacía quality="", una cadena vacía size="" o n=0, todas las solicitudes de prueba devolvieron un error HTTP 400 y no generaron ningún cargo.

​

4. Qué ofrece BetterToken: no tienes que adaptar cada ruta por separado

1. Enrutamiento inteligente según las capacidades: el sistema selecciona automáticamente un servicio disponible con las capacidades correspondientes, según el modelo, el tamaño objetivo (por ejemplo, 2K/4K) y si se incluyen parámetros de edición de imágenes o Mask.
2. Interfaz unificada y valores alternativos para los parámetros: las interfaces estándar POST /v1/images/generations (generación de imágenes) y POST /v1/images/edits (edición con imagen de referencia/Mask) procesan automáticamente los valores null, auto y los parámetros omitidos, y bloquean las entradas no válidas directamente en el gateway.
3. Devolución transparente de las dimensiones reales y los detalles de facturación: junto con los datos de la imagen, el campo bettertoken_image_billing del cuerpo de la respuesta indica directamente el ancho y alto decodificados reales (width/height), el nivel de facturación (billing_resolution), la moneda y el importe liquidado (settled_amount).
4. Distinción clara entre dos conceptos fundamentales:
   • Admitir el parámetro Mask ≠ garantizar un retoque preciso a nivel de píxel: la interfaz permite subir una imagen de referencia y una Mask para editar, pero algunos resultados de las pruebas también modificaron zonas protegidas fuera de la máscara. Por ejemplo, en nuestra prueba geométrica de dos círculos, se pidió cambiar el color del círculo izquierdo transparente y proteger el derecho opaco, pero se cambiaron ambos. Por eso, confirmamos que se admite el envío del parámetro Mask, pero no garantizamos que se consiga siempre un aislamiento estricto de las zonas a nivel de píxel.
   • Admitir el parámetro quality ≠ garantizar una mejora fija de la calidad: la interfaz admite valores como "auto" o "high" y los enruta correctamente. Sin embargo, como la generación tiene un componente aleatorio, no prometemos a partir de una sola muestra que high proporcione una mejora de calidad de un porcentaje determinado.

⚠️ Dos límites reales que debes conocer antes de integrar:

1. Enrutar según las capacidades no equivale a fijar estrictamente los píxeles en cada llamada: por las diferencias de salida de los servicios subyacentes, los píxeles reales pueden variar incluso si la solicitud se enruta al nodo correcto (por ejemplo, hoy hubo solicitudes de 1024x1024 que devolvieron 1024×936, y muestras de solicitudes de 3840x2160 que devolvieron 3840×2161). Si la proporción del lienzo es crítica para tu aplicación, recorta o procesa la imagen después según el ancho y alto reales de la respuesta.
2. Solicitar 1K no siempre implica que se facture como 1K: el sistema clasifica la imagen según las dimensiones de la imagen válida realmente entregada. Hoy, dos modelos 2.5 (y algunos casos de gpt-image-2) devolvieron 1254×1254 al recibir solicitudes de 1024x1024; el sistema las clasificó como nivel 2K y las facturó según la tarifa correspondiente.

​

5. Compatibilidad de los tres modelos: ¿cuál debo llamar y qué valores debo enviar?

​

6. Dos casos con imágenes reales: ¿qué resultados ofrecen?

​

Caso A: fotografía de producto para comercio electrónico; dimensiones y detalles en 1K / 2K / 4K

Genera una fotografía realista de estudio para comercio electrónico: una taza de cerámica de color rojo coral (con el asa hacia la derecha) sobre una encimera de piedra gris claro, con un paño de lino beige doblado a la izquierda. La taza lleva el texto blanco y nítido «BETTER DAY». Luz lateral suave desde arriba a la izquierda; conserva los reflejos sutiles del esmalte cerámico, las fibras del lino y las sombras de contacto naturales. La taza aparece completa y centrada; el fondo es sencillo y neutro, sin otros objetos, marcas de agua ni texto adicional.

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.

• Imágenes bien acabadas: las tres muestran los reflejos del esmalte rojo coral, el asa a la derecha, la encimera de piedra gris claro, las fibras del paño de lino beige y el texto blanco «BETTER DAY», claramente legible.
• Diferencias entre muestras independientes: cada generación es una muestra independiente, por lo que varían de forma natural la proporción de la taza, el grosor de las letras y la forma de doblar la tela (por ejemplo, en la imagen horizontal 4K el texto aparece en dos líneas). Por eso, los recortes solo muestran los detalles reales de cada imagen; no constituyen un experimento óptico de nitidez con composiciones estrictamente idénticas.
• Límite de facturación visible: aunque en la primera imagen se solicitó 1024x1024, se entregó una imagen cuadrada de alta resolución de 1254×1254; por ello, se cobró como nivel 2K (¥0.11), igual que la segunda imagen de 2048×2048.

​

Caso B: cambio de color localizado de un producto; resultados y límites reales de Mask

Cambia únicamente el cuerpo rojo coral de la taza dentro de la zona transparente de la máscara a azul marino oscuro. Conserva el material cerámico, la iluminación y los reflejos. Mantén sin cambios las letras blancas «BETTER DAY», el asa roja, el paño de lino, la encimera, el fondo y la composición general. No añadas ni elimines ningún objeto.

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.

• Se logró el cambio de color principal: el exterior del cuerpo de la taza pasó correctamente a azul marino oscuro y conservó el brillo cerámico; se mantuvieron el asa roja fuera de la máscara, el paño de lino de la izquierda y el fondo, y el texto «BETTER DAY» dentro de la máscara siguió siendo legible.
• El límite estricto de Mask no se superó (hubo filtración fuera de la zona): al observar el borde y la pared interior de la taza, se ve que parte del color rojo coral, originalmente dentro de la zona protegida opaca, también se cambió a azul oscuro. En la prueba geométrica más extrema de «dos círculos», también cambió el círculo derecho que no estaba enmascarado.
• Recomendación de uso: al subir una imagen de referencia y una Mask, asegúrate de que ambas tengan el mismo tamaño de lienzo (la zona que se debe modificar ha de ser transparente y la que se conserva, opaca), e indica en el Prompt tanto «qué cambiar» como «qué conservar». En imágenes comerciales industriales con logotipos de marca, texto pequeño en el envase o requisitos estrictos para los bordes, amplía la imagen después de generarla e inspecciona los límites de la zona protegida.

​

7. Precios y coste real de uso: ¿cuánto se cobra al final?

💡 Punto clave para planificar el presupuesto: calcula el coste según el «nivel realmente entregado», no según los «parámetros solicitados». Como muestran las pruebas anteriores, hoy algunas solicitudes a flare, sunburst o gpt-image-2 con 1024x1024 (1K) entregaron imágenes de 1254×1254. En ese caso, el sistema las clasifica según el resultado real como 2K (es decir, cobra ¥0.15 o ¥0.11, no el precio 1K de ¥0.035). Si las 100 solicitudes de 1024x1024 a flare devolvieran 1254×1254, al precio actual el coste de las 100 imágenes sería ¥15.00 (estimación aritmética). Además, la lógica de clasificación combina el tamaño objetivo con un umbral de desviación razonable (por ejemplo, 3840×2159 se clasifica normalmente como 4K y 1536×1024 como 1K). No recalcules el coste en tu aplicación con una regla simplista como «si el lado más largo supera 1024»; la liquidación siempre se determina según el campo bettertoken_image_billing del cuerpo de la respuesta.

​

¿Por qué no basta con fijarse en el «precio bajo por imagen»?

1. El precio solo es comparable si el tamaño real de la respuesta alcanza el objetivo: una solicitud que anuncia «compatibilidad con 4K a un precio muy bajo», pero solo devuelve una imagen reducida de 1024, no puede utilizarse en un entorno de producción que necesite imágenes de alta resolución y no debe compararse como un precio 4K válido.
2. Incluye en el total los fallos y el coste de volver a generar: las pruebas de parámetros no válidos de esta ronda no tuvieron coste; si una imagen se entregó correctamente pero no satisface tus necesidades, volver a enviarla es una nueva solicitud y debe presupuestarse por separado. Las 4 imágenes de los casos de producto y Mask de esta guía (3 generadas + 1 editada) se entregaron con una solicitud cada una. La muestra de Mask tuvo el cambio de color fuera de la zona explicado arriba. Sus precios individuales fueron ¥0.11, ¥0.11, ¥0.13 y ¥0.11, con un coste real total de solo ¥0.46 por las 4 imágenes; la factura coincidió exactamente con los cargos de la cuenta. Si una ruta inestable o parámetros incompatibles te obligan a repetir las generaciones, el coste real de obtener un recurso utilizable puede aumentar aunque el precio anunciado por imagen sea bajo.
3. Reduce el coste oculto de adaptación para el equipo de desarrollo: BetterToken unifica la normalización de parámetros, enruta según las capacidades y devuelve en tiempo real los píxeles reales y los campos de facturación, reduciendo el trabajo de adaptar cada servicio y organizar por separado las dimensiones y los costes.

​

8. Ejemplos de llamadas listos para copiar

​

Ejemplo 1: solicitud JSON para generar una imagen de producto de alta resolución (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

• Nota sobre las dimensiones: para una imagen horizontal 4K, cambia "size" por "3840x2160" (no uses "4096x4096"). Las dimensiones válidas actuales deben cumplir lo siguiente: ancho y alto múltiplos de 16, lado más largo no superior a 3840, relación entre lado largo y corto no superior a 3:1 y un total de entre 655,360 y 8,294,400 píxeles.
• Nota sobre la identificación del formato de archivo: aunque la solicitud especifique "output_format": "png", algunos nodos subyacentes pueden devolver contenido binario en formato JPEG. Al guardar o procesar la imagen, conviene identificar el formato real según la cabecera del archivo (Magic Bytes) y no fijar la extensión por adelantado.

​

Ejemplo 2: edición localizada con imagen de referencia y Mask en Multipart (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"

​

Ejemplo 3: lectura de los píxeles realmente entregados y los datos de facturación (estructura de respuesta y código de análisis)

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

• Documentación oficial de OpenAI: guía para escribir prompts de imágenes (Image Prompting Guide)
• OpenAI Cookbook: ejemplo de generación y edición de imágenes con alta fidelidad de entrada