GPT Image 2: espejo global y proxy para equipos internacionales
Modelo objetivo:
gpt-image-2
Endpoint de inferencia:https://api.toapis.com/v1/images/generations
Relacionado: Guía de la API GPT Image 2 · Precios de GPT Image 2 · Guía de la API GPT-Image-2.6
1. TL;DR y panorama de rendimiento
- Tarea: apuntar los clientes internacionales a una sola pasarela de imágenes de ToAPIs, en lugar de abrir una sesión de larga distancia nueva contra un origen del proveedor para cada solicitud a
gpt-image-2. - Contrato: usa el ID de modelo
gpt-image-2enPOST /v1/images/generations. Los campos documentados actuales incluyenprompt(hasta 32,000 caracteres),sizecomo relación de aspecto como1:1o16:9(no una cadena de píxeles1024x1024) yresolutioncomo1k,2ko4k. - Regiones: la documentación oficial de ToAPIs indica a los usuarios de China continental usar
https://toapis.cncomo URL base. Los ejemplos internacionales de esta serie de blog usanhttps://api.toapis.com. Las rutas, los ID de modelo y la cabecera Bearer no cambian; solo cambia el origen. - Protocolo asíncrono: la generación de imágenes devuelve un
idde tarea. ConsultaGET /v1/images/generations/{task_id}(oGET /v1/tasks/{task_id}) hasta que el estado seacompletedofailed. El tiempo de reloj en el cliente no es lo mismo que el tiempo de generación, y un timeout del cliente no demuestra que la tarea haya fallado. - Lo que este artículo no afirma: no publica una lista de POP, un tiempo de handshake ni un objetivo de latencia de extremo a extremo sin verificar. Mídelos en tu propia ruta. El detalle de parámetros y las comparativas de SKU están en la guía de la API y en la guía de 2.6.
2. Enrutar equipos internacionales a través de la pasarela de ToAPIs
Los equipos fuera de la región de origen del proveedor suelen notar dos retrasos distintos: el tiempo para establecer una conexión y el tiempo que el modelo pasa realmente renderizando. Meterlos en un único número de "la API es lenta" hace que se optimice lo equivocado. El primero es un problema de red que puedes abordar usando un origen documentado de ToAPIs más cercano y reutilizando una sesión HTTP en caliente. El segundo es el tiempo de generación, que observas después de que se acepte la tarea.
ToAPIs expone una ruta unificada de generación de imágenes. La documentación oficial documenta actualmente https://toapis.com e indica a los usuarios de China continental reemplazar ese origen por https://toapis.cn. Las guías de esta serie, incluida la guía de la API GPT Image 2, envían las mismas rutas a https://api.toapis.com. Elige una URL base por entorno, guárdala como configuración y no codifiques una mezcla de orígenes en el mismo servicio.

Figura 1: mantén los clientes en un único origen documentado de ToAPIs, reutiliza la sesión y trata la generación de imágenes como una tarea asíncrona en lugar de un viaje síncrono de larga distancia.
Hábitos prácticos de enrutamiento que no dependen de cifras de latencia no publicadas:
- Un origen por entorno. Un servicio en Singapur y otro en Fráncfort pueden compartir el mismo ID de modelo y payload. No deberían inventar sus propias URL de proveedor.
- Reutiliza conexiones. Activa HTTP keep-alive (y HTTP/2 donde tu cliente ya lo soporte) para que el establecimiento de TLS no se repita en cada envío o consulta.
- Desacopla el envío de la espera. Guarda el
idde la tarea de inmediato. Consulta con un intervalo acotado, o mejor usa un webhook de tareas y mantén la consulta como respaldo. - No cachees "prompts idénticos" como atajo de facturación. No hay garantía documentada de ToAPIs de que un prompt repetido se sirva desde una caché del edge o sea gratuito. Si se envían dos tareas, preve pagar dos tareas, salvo que los términos de tu cuenta digan otra cosa.
El contrato de solicitud actual también se queda obsoleto con facilidad. Algunos fragmentos antiguos envían size como 1024x1024 y un flag quality: "standard". La referencia actual de la API de gpt-image-2 y el contrato del frontend de ToAPIs usan size para la relación de aspecto (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 o auto) y resolution para el nivel (1k, 2k, 4k). El gpt-image-2 exacto no expone un campo quality en el contrato actual del playground; quality aparece en ID como gpt-image-2-vip. Confirma el ID que realmente llamas.
Las imágenes de referencia van en reference_images (solo URL públicas, hasta 14). image_urls se acepta como alias retrocompatible y se normaliza a reference_images. No envíes base64; sube primero. Para proporciones personalizadas, más opciones de calidad o comportamiento de SKU oficial, consulta la guía de la API y la guía del modelo.
3. Implementación en producción: cURL y Python
Paso 1: envío con cURL
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": "Minimalist product still of a matte ceramic pour-over kettle on slate, soft side light, no typography",
"size": "1:1",
"resolution": "1k",
"n": 1,
"response_format": "url"
}'
Paso 2: helper de Python para enviar y consultar
Ajusta los nombres de campo y el envoltorio de respuesta a la referencia de la API de tu cuenta. El fragmento usa la ruta de estado de imagen documentada y los estados completed / failed. Cambia BASE a https://toapis.cn solo para un entorno de China continental que deba usar ese origen.
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 = "1:1",
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 = 180) -> 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__":
task_id = dispatch_image(
"Minimalist product still of a matte ceramic pour-over kettle on slate, soft side light, no typography"
)
print("Task:", task_id)
print("Image:", poll_image_task(task_id))
Guarda la URL base, el ID de modelo, size y resolution junto al registro de la tarea. Si más adelante cambias un cliente de gpt-image-2 a gpt-image-2-vip o a una SKU de 2.6, cambia una variable a la vez y vuelve a leer la guía correspondiente: 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. Una consulta HTTP correcta 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 el ID de modelo, que size sea una proporción documentada, que resolution sea 1k / 2k / 4k y que las imágenes de referencia sean URL en lugar de base64 |
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; usa una política de reintentos acotada |
5. Precios y ROI con FinOps
- No reutilices precios unitarios de borradores de planificación ni de artículos antiguos. Las tarifas del catálogo, los multiplicadores por resolución y el tratamiento de tareas fallidas varían según la SKU y la cuenta. Algunos ID de GPT Image 2.x se facturan por imagen; la guía de 2.6 documenta la facturación por tokens para esa generación. Confirma la tarifa aplicable al ID de modelo exacto que llamas.
- El enrutamiento no cambia por sí mismo el precio del modelo. Usar
api.toapis.comotoapis.cnes una elección de URL base. No es un descuento documentado. Las ganancias de FinOps vienen de evitar envíos duplicados tras un timeout del cliente, hacer borradores en1ky elegir la SKU correcta. - Los contratos oficiales del proveedor suelen añadir restricciones regionales de facturación, compromisos o mínimos de prepago. La facturación de ToAPIs suele ser de pago por uso: confirma los términos activos en tu cuenta.
- Para una discusión de tarifas más profunda, usa el artículo de precios de GPT Image 2 como contexto 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: cambiar el origen de ToAPIs no cambia el ID de modelo ni la forma documentada de la solicitud; los usuarios de China continental deben seguir la nota sobre toapis.cn en la documentación oficial; las tareas de imagen son asíncronas; size es una relación de aspecto y resolution es el nivel; no hay una caché del edge gratuita documentada para prompts repetidos.
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 congpt-image-2,size: "1:1"yresolution: "1k". - Guarda el
idde la tarea, consultaGET /v1/images/generations/{id}con un plazo acotado y respetaRetry-Afteren429. - Siguiente: la guía de la API GPT Image 2 para los parámetros, la guía de 2.6 si vas a cambiar de SKU, y el recorrido de créditos gratis si vas a abrir una cuenta nueva.







