Dominar el inpainting y el outpainting con la API de edición de imágenes de GPT Image 2
Modelos objetivo:
gpt-image-2,gpt-image-2-official
Endpoint de inferencia:https://api.toapis.com/v1/images/generations
Relacionado: Guía de la API GPT Image 2 · Flujos de relación de aspecto en 4K · Espejo y proxy global · Referencia oficial de inpainting
1. TL;DR y panorama de rendimiento
- Tarea: reemplazar una región de una imagen existente (inpainting) o extender el lienzo a una nueva relación de aspecto (outpainting) sin inventar una segunda API no documentada.
- Contrato: usa los ID de modelo que existen en el catálogo. El
gpt-image-2exacto aceptaprompt,sizecomo proporción,resolutioncomo1k/2k/4kyreference_imagesopcional. El inpainting con máscara está documentado engpt-image-2-officialconimage_urlsmásmask_url. - Lo que no es el contrato actual: un ID de modelo llamado
gpt-image-2-edit, unPOST /v1/images/editsmultipart síncrono, osize: "1024x1024". Esas formas aparecen en borradores antiguos y no deberían copiarse a clientes nuevos. - E/S: sube las imágenes de origen y las máscaras con
POST /v1/uploads/imagesy luego pasa la URL pública devuelta. No se acepta base64 enreference_images,image_urlsnimask_url. - Protocolo asíncrono: la llamada de envío devuelve un
idde tarea. ConsultaGET /v1/images/generations/{id}hasta que el estado seacompletedofailed. Un timeout del cliente no demuestra que la tarea haya fallado.
2. El poder de la edición programática de imágenes
Generar una imagen fija a partir de un prompt de texto es solo el primer paso. Los catálogos, anuncios y sistemas de diseño en producción suelen necesitar una revisión dirigida: cambiar un producto, limpiar un fondo o estirar una foto de producto cuadrada hasta un hero ancho, manteniendo la iluminación y la identidad del sujeto.
La familia actual GPT Image 2 de ToAPIs cubre esos trabajos en un camino, POST /v1/images/generations, con dos ID de modelo distintos:
| Tarea | ID de modelo | Cómo apuntas a la fuente | ¿Máscara? |
|---|---|---|---|
| Edición guiada por prompt o transferencia de estilo | gpt-image-2 | reference_images (lista de URL, máximo 14) | No documentada en este ID |
| Inpainting con precisión de píxel | gpt-image-2-official | image_urls (lista de URL, máximo 16) | mask_url obligatorio con la primera imagen |
| Expansión de lienzo (outpainting) | Cualquiera de los dos ID | Pasa el original como referencia y cambia size al ratio objetivo | Sin flag de outpaint dedicado |
image_urls es un alias retrocompatible de reference_images en el gpt-image-2 exacto y la pasarela lo normaliza. Los ejemplos de canal oficial de la referencia de la API usan image_urls junto con mask_url. Usa los nombres de campo de la referencia correspondientes al ID que realmente llamas.
Una máscara de inpainting utilizable es un PNG con canal alfa. Sus dimensiones en píxeles deben coincidir con la primera imagen de referencia. Los píxeles transparentes (alpha = 0) son la zona a regenerar; los píxeles opacos deben conservarse. Construye la máscara en tu pipeline (por ejemplo con Pillow), súbela y envía solo la URL.
El outpainting es un flujo de trabajo, no un endpoint separado. Si tienes una foto de producto en 1:1 y necesitas un banner 16:9, mantén el original como referencia, define size en 16:9, elige un nivel de resolution explícito e indica al modelo que mantenga el sujeto y extienda la escena. Una variante práctica consiste en componer el original sobre un lienzo transparente más grande, subir ese lienzo y tratarlo como referencia: sigue siendo /v1/images/generations, y sigue sin un flag outpaint: true.

Figura 1: un lienzo de origen y una región interna enmascarada pasan por la pasarela de ToAPIs; el camino documentado sigue siendo POST /v1/images/generations, con mask_url reservado para gpt-image-2-official.
size y resolution siguen el mismo contrato que en texto a imagen: size es una proporción como 1:1 o 16:9, y resolution es 1k, 2k o 4k. El gpt-image-2 exacto no expone un campo quality en el contrato actual del playground; quality (low / medium / high) aparece en gpt-image-2-official. Consulta la guía de flujos en 4K para ver la tabla de píxeles documentada.
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 origen por entorno. Las rutas, los ID de modelo y la cabecera Bearer no cambian.
Paso 1: sube una imagen de origen (y una máscara, si la necesitas)
curl -X POST "https://api.toapis.com/v1/uploads/images" \
-H "Authorization: Bearer $TOAPIS_API_KEY" \
-F "file=@./product.png"
La respuesta incluye data.url. Repite la llamada para una máscara PNG cuando llames a gpt-image-2-official. No incluyas base64 dentro de la solicitud de generación.
Paso 2: edición guiada por prompt en el gpt-image-2 exacto
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": "Keep the ceramic kettle and slate surface. Replace only the background with a calm marble countertop, matching the existing side light. No typography.",
"size": "1:1",
"resolution": "1k",
"n": 1,
"response_format": "url",
"reference_images": ["https://example.com/product.png"]
}'
Paso 3: inpainting con máscara en gpt-image-2-official
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-official",
"prompt": "Replace the masked region with a desert sunset, preserving the subject outline and lighting",
"size": "1:1",
"resolution": "1k",
"quality": "medium",
"image_urls": ["https://example.com/photo.png"],
"mask_url": "https://example.com/mask.png"
}'
Paso 4: helper de Python para enviar y consultar
Ajusta los nombres de campo a la referencia de la API del ID de modelo que llamas. El fragmento usa la ruta de estado de imagen documentada y los estados completed / failed.
import os
import time
import requests
API_KEY = os.environ["TOAPIS_API_KEY"]
BASE = "https://api.toapis.com"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}
def upload_image(path: str) -> str:
with open(path, "rb") as handle:
res = requests.post(
f"{BASE}/v1/uploads/images",
headers=HEADERS,
files={"file": handle},
timeout=60,
)
res.raise_for_status()
url = res.json().get("data", {}).get("url")
if not url:
raise RuntimeError(f"Unexpected upload envelope: {res.text}")
return url
def dispatch_edit(payload: dict) -> str:
res = requests.post(
f"{BASE}/v1/images/generations",
headers={**HEADERS, "Content-Type": "application/json"},
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__":
source = upload_image("product.png")
# Prompt-guided edit on exact gpt-image-2 (no mask field on this ID).
task_id = dispatch_edit(
{
"model": "gpt-image-2",
"prompt": "Keep the ceramic kettle; extend the scene into a wide 16:9 set with the same side light. No typography.",
"size": "16:9",
"resolution": "1k",
"n": 1,
"response_format": "url",
"reference_images": [source],
}
)
print("Task:", task_id)
print("Image:", poll_image_task(task_id))
Para ejecutar inpainting con máscara, sube una máscara RGBA que coincida, cambia model a gpt-image-2-official y envía image_urls más mask_url. Guarda el ID de modelo, size y resolution junto al registro de la tarea, para que un cambio posterior de SKU sea una decisión explícita.
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 | Confirma el ID de modelo, que size sea una proporción documentada, que resolution sea 1k / 2k / 4k, que las URL sean públicas y que una máscara (cuando se usa) sea un PNG del mismo tamaño con canal alfa en gpt-image-2-official |
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 como un par plano
$0.024/$0.048de "estándar vs HD". Esas cifras están obsoletas respecto al catálogo actual, que fija precios por ID de modelo y, para la comparación estándar de la landing de GPT Image 2, por nivel de resolución. - 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/4Kpara elgpt-image-2estándar. Trátalo como una comparación publicada, no como una factura contractual. Las SKU de canal oficial y los descuentos de cuenta pueden diferir; confirma la tarifa aplicable al ID exacto que llamas. - El enrutamiento (
api.toapis.comfrente atoapis.cn) es una elección de URL base, no un descuento documentado. Las ganancias de FinOps vienen de hacer borradores en1k, evitar envíos duplicados tras un timeout del cliente y elegir la SKU correcta (gpt-image-2frente agpt-image-2-official) en lugar de suponer un modelo de "edición" más barato. - 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 gpt-image-2 exacto no documenta mask_url ni /v1/images/edits; el inpainting con máscara está documentado en gpt-image-2-official; las máscaras deben ser PNG RGBA del mismo tamaño entregadas como URL; el outpainting es un cambio de size más una imagen de referencia; la facturación debe confirmarse en la cuenta para el ID de modelo exacto.
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 sube una imagen de origen conPOST /v1/uploads/images. - Prueba una edición guiada por prompt en
gpt-image-2conreference_images,size: "1:1"yresolution: "1k". - Si necesitas una máscara con precisión de píxel, cambia a
gpt-image-2-official, sube una máscara RGBA que coincida con la primera imagen y envíaimage_urlsmásmask_url. - Guarda el
idde la tarea, consultaGET /v1/images/generations/{id}con un plazo acotado y respetaRetry-Afteren429. - Siguiente: la guía de relación de aspecto en 4K si vas a subir
resolution, y la guía de la API para el mapa completo de parámetros.







