Generar imágenes nativas en 4K con GPT Image 2: relaciones de aspecto y flujos de escalado
Modelo objetivo:
gpt-image-2
Endpoint de inferencia:https://api.toapis.com/v1/images/generations
Relacionado: Guía de la API GPT Image 2 · Inpainting y outpainting · Espejo y proxy global · Referencia de tamaños de la API
1. TL;DR y panorama de rendimiento
- Tarea: producir una imagen lista para impresión o para un hero en el nivel 4K documentado, con la relación de aspecto que realmente necesitas, desde una sola solicitud a
gpt-image-2. - Contrato:
POST /v1/images/generationscon el ID de modelogpt-image-2.sizees una relación de aspecto (1:1,16:9y las demás proporciones documentadas).resolutiones1k,2ko4k. La referencia oficial publica las dimensiones en píxeles resultantes para cada par. - Lo que no debes enviar:
size: "2048x2048", un flagquality: "hd"engpt-image-2exacto, o un campo inventadoupscale: trueque prometa convertir un render de 2048 px en3840x2160. El 4K es un valor deresolutionde primera clase. - Protocolo asíncrono: la llamada de envío devuelve un
idde tarea. ConsultaGET /v1/images/generations/{id}(oGET /v1/tasks/{id}) hasta que el estado seacompletedofailed. Las tareas en 4K pueden tardar más que los borradores en 1K; un timeout del cliente no demuestra que la tarea haya fallado. - FinOps: haz borradores en
1k, promociona los prompts aceptados a4ky confirma la tarifa vigente por nivel. No copies filas de precio antiguas de 1024 px / 2048 px en una previsión.
2. Relaciones de aspecto, niveles de resolución y salida nativa en 4K
El contrato actual de gpt-image-2 separa la forma del nivel. size elige la relación de aspecto; resolution elige el nivel de calidad; el servicio deriva el ancho y el alto en píxeles de ambos. Por eso una "imagen en 4K" no siempre es 3840x2160: ese tamaño es el resultado documentado de size: "16:9" más resolution: "4k". Una salida cuadrada en 4K está documentada como 2880x2880.
Las proporciones predefinidas que aparecen en la referencia oficial son:
1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 21:9, 9:21
Puedes enviar auto y dejar que el proveedor upstream elija, pero entonces la proporción final y el tamaño en píxeles no están garantizados. gpt-image-2 exacto no documenta un campo custom de tamaño en píxeles; las proporciones personalizadas width:height (por ejemplo 7:4) están documentadas en gpt-image-2-vip y gpt-image-2-official, sujetas a sus propios límites (lados múltiplos de 16, borde largo de como máximo 3,840 px, proporción de como máximo 3:1, total de píxeles entre 655,360 y 8,294,400).
La tabla de tamaños de la referencia de la API para gpt-image-2 exacto es:
| size | 1k | 2k | 4k |
|---|---|---|---|
1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
3:2 | 1536x1024 | 2048x1360 | 3520x2336 |
2:3 | 1024x1536 | 1360x2048 | 2336x3520 |
4:3 | 1024x768 | 2048x1536 | 3312x2480 |
3:4 | 768x1024 | 1536x2048 | 2480x3312 |
5:4 | 1280x1024 | 2560x2048 | 3216x2576 |
4:5 | 1024x1280 | 2048x2560 | 2576x3216 |
16:9 | 1536x864 | 2048x1152 | 3840x2160 |
9:16 | 864x1536 | 1152x2048 | 2160x3840 |
2:1 | 2048x1024 | 2688x1344 | 3840x1920 |
1:2 | 1024x2048 | 1344x2688 | 1920x3840 |
21:9 | 2016x864 | 2688x1152 | 3840x1648 |
9:21 | 864x2016 | 1152x2688 | 1648x3840 |
Dos advertencias van junto a esa tabla:
- El playground actual de ToAPIs mantiene
3:2y2:3en 4K, pero omite5:4y4:5cuando la resolución es 4K. La tabla de tamaños anterior sigue listando píxeles en 4k para esas dos proporciones. Si tu producto necesita5:4o4:5en 4k, confírmalo con una solicitud real en lugar de asumir que el filtro del playground es el límite de la API. - En distintas superficies aparecen minúsculas (
4k) y mayúsculas (4K). Los ejemplos oficiales degpt-image-2usan minúsculas; la configuración del playground usa1K/2K/4K. Sigue la referencia de la API en los clientes y no trates las mayúsculas como un segundo parámetro.

Figura 1: la resolución es un campo de solicitud de primera clase. La ruta documentada es pedir 4k directamente, no inventar un flag de escalado posterior.
No hay un interruptor upscale: true documentado en ToAPIs que tome un render nativo de 2048 px y devuelva 3840x2160. Si ya tienes una imagen en 1K o 2K y quieres una más grande, el movimiento admitido es una nueva generación (opcionalmente con el borrador en reference_images) con resolution: "4k". No prometas fidelidad tipográfica, "originales de impresión a 300 DPI" ni escalado sin artefactos a menos que hayas medido esas propiedades en tus propios activos.
gpt-image-2 exacto también acepta de forma opcional background: "transparent" y hasta 14 URL en reference_images. No expone quality en el contrato actual del playground; quality es un campo de IDs como gpt-image-2-vip.
3. Implementación en producción: cURL y Python
Los ejemplos internacionales de esta serie usan https://api.toapis.com. La documentación oficial indica a los usuarios de China continental que usen https://toapis.cn. Mantén un solo origen por entorno.
Paso 1: envío con cURL en 4K nativo
curl -X POST "https://api.toapis.com/v1/images/generations" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "gpt-image-2",
"prompt": "Wide architectural photograph of a concrete pavilion at dusk, still water in the foreground, no typography, no logos",
"size": "16:9",
"resolution": "4k",
"n": 1,
"response_format": "url"
}'
Esta solicitud está documentada para apuntar a 3840x2160. Para un original cuadrado en 4K, cambia size a 1:1 (documentado como 2880x2880). Para un fotograma de historia en 9:16, usa size: "9:16" (documentado como 2160x3840).
Paso 2: helper de Python para borrador y promoción
Itera en 1k, guarda el prompt aceptado (y las URL de referencia opcionales) y vuelve a enviar en 4k. El helper de consulta es el mismo contrato asíncrono que se usa en la guía de espejo y proxy.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
ENDPOINT = f"{BASE}/v1/images/generations"
HEADERS = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
def dispatch_image(
prompt: str,
size: str = "16:9",
resolution: str = "1k",
model: str = "gpt-image-2",
reference_images: list[str] | None = None,
) -> str:
payload = {
"model": model,
"prompt": prompt,
"size": size,
"resolution": resolution,
"n": 1,
"response_format": "url",
}
if reference_images:
payload["reference_images"] = reference_images
res = requests.post(ENDPOINT, headers=HEADERS, json=payload, timeout=30)
res.raise_for_status()
data = res.json()
task_id = data.get("id") or data.get("task_id")
if not task_id:
raise RuntimeError(f"Unexpected submission envelope: {data}")
return task_id
def poll_image_task(task_id: str, deadline_s: int = 300) -> str:
poll_url = f"{BASE}/v1/images/generations/{task_id}"
interval = 2.0
start = time.time()
while time.time() - start < deadline_s:
time.sleep(interval)
poll = requests.get(poll_url, headers=HEADERS, timeout=15)
if poll.status_code == 429:
retry_after = poll.headers.get("Retry-After")
time.sleep(float(retry_after) if retry_after else min(interval * 2, 20))
continue
poll.raise_for_status()
data = poll.json()
status = data.get("status")
if status == "completed":
return data["result"]["data"][0]["url"]
if status == "failed":
raise RuntimeError(f"Generation failed: {data.get('error')}")
interval = min(interval * 1.5, 8.0)
raise TimeoutError(
f"Task {task_id} exceeded {deadline_s}s; check status before retrying"
)
if __name__ == "__main__":
prompt = (
"Wide architectural photograph of a concrete pavilion at dusk, "
"still water in the foreground, no typography, no logos"
)
draft_id = dispatch_image(prompt, size="16:9", resolution="1k")
print("Draft:", draft_id, poll_image_task(draft_id))
final_id = dispatch_image(prompt, size="16:9", resolution="4k")
print("4K:", final_id, poll_image_task(final_id, deadline_s=300))
Da a las consultas en 4K un plazo más largo que a los borradores en 1K. Guarda el id de la tarea de inmediato, para que un timeout del cliente se pueda resolver después con una consulta de estado. Si más adelante cambias el cliente a gpt-image-2-vip (proporciones personalizadas, quality) o a gpt-image-2-official, cambia una variable a la vez y vuelve a leer la referencia de ese ID: las unidades de facturación no son automáticamente las mismas.
4. Gestión de errores y matriz de estados
Las categorías siguientes son puntos de partida para el diagnóstico, no una garantía de códigos de error exactos de ToAPIs. Un envío HTTP correcto todavía requiere que leas el status de la tarea.
| Estado HTTP | Categoría habitual | Acción recomendada |
|---|---|---|
400 | Campo inválido o combinación no admitida | Comprueba que size sea una proporción documentada, que resolution sea 1k / 2k / 4k y que no hayas enviado una cadena de píxeles como 2048x2048 ni un flag upscale no documentado |
401 | Clave de API ausente o inválida | Rota la clave en el panel de ToAPIs y confirma la cabecera Authorization |
429 | Límite de tarifa o de concurrencia | Respeta Retry-After cuando esté presente; aplica backoff con jitter; reintenta solo cuando sea seguro |
5xx o timeout de red | Problema temporal de la pasarela o del upstream | Comprueba el estado de la tarea antes de reenviar; las tareas en 4K pueden seguir en in_progress después de un timeout del cliente |
5. Precios y ROI con FinOps
- No reutilices precios unitarios antiguos como
$0.024para 1024 px o$0.072para 2048 px. Esas filas pertenecen a un contrato de tamaño obsoleto. - La guía del modelo GPT Image 2 muestra actualmente una comparación en la landing de ToAPIs de
$0.015/$0.020/$0.025por imagen en1K/2K/4Kparagpt-image-2estándar. Úsalo solo como comparación publicada. Confirma la tarifa que se aplica a tu cuenta y al ID de modelo exacto que llamas. - Un bucle económico consiste en hacer borradores en
1ky luego promocionar el prompt aceptado (y las referencias) a4k. Dos tareas exitosas son dos imágenes facturables, salvo que los términos de tu cuenta digan otra cosa. No hay un atajo gratuito documentado de "escalar el mismo prompt". - Los precios por token del proveedor oficial y los precios por solicitud de ToAPIs no son intercambiables. Si pasas a
gpt-image-2-vipo a una SKU de canal oficial, vuelve a leer la hoja de precios de ese ID. - Como contexto, consulta el artículo de precios de GPT Image 2 y luego verifica cada cifra contra el catálogo en vivo antes de incluirla en una previsión.
6. Preguntas frecuentes
Consulta el bloque FAQ de la cabecera. Resumen: el 4K es un valor de resolution de primera clase, no un flag upscale; las dimensiones en píxeles dependen de size y de resolution; no envíes 1024x1024 como size; confirma 5:4 / 4:5 en 4k contra la API en vivo si necesitas esas proporciones; confirma las tarifas publicadas de 1K / 2K / 4K en tu cuenta.
7. Lista de acciones
- Crea una clave en el Portal de desarrolladores de ToAPIs.
- Define una URL base por entorno (
https://api.toapis.como, cuando sea necesario,https://toapis.cn) y prueba el fragmento cURL consize: "16:9"yresolution: "1k". - Promociona el mismo prompt a
resolution: "4k"y confirma el tamaño en píxeles documentado para esa proporción (para16:9,3840x2160). - Guarda el
idde la tarea, da a las consultas en 4K un plazo más largo y respetaRetry-Afteren429. - Siguiente: la guía de inpainting y outpainting si estás editando un fotograma existente, y la guía de la API para el mapa completo de parámetros.







