ToAPIs
    InicioToAPIs
    Generación de imágenesGPT Image 2.6, Gemini, FLUX…Generación de videoSeedance, Veo, Kling, Sora…Chat y redacciónGPT-5.6, Claude, DeepSeek…Voz y músicaLocuciones, TTS, audio
    NovedadSeedance 2.5
    PreciosDocumentación de APIMCP
    BlogAlternativas
    Iniciar sesiónEmpieza gratis
    Todos los modelosPreciosDocumentación de APIMCPBlogAlternativas
    Iniciar sesiónEmpieza gratis

    Idioma

    Esc
    • Seedance 2.5Generación de video
    • GPT Image 2Generación de imágenes
    • GPT Image 2.6Generación de imágenes
    • GPT Image 2.5Generación de imágenes
    • Veo 3.1 FastGeneración de video
    • Kling 3.0 TurboGeneración de video
    • Kling V4 FlashGeneración de video
    • Grok Video 1.5Generación de video
    • Nano Banana 2Generación de imágenes
    • Seedream 5.5Generación de imágenes
    • FLUXGeneración de imágenes
    • Sora 2Generación de video
    • Todos los modelos de imagenCategoría
    • Todos los modelos de videoCategoría
    • GPT-5.6 SolChat y código
    • Claude Opus 4.8Chat y código
    • Claude Opus 4.7Chat y código
    • DeepSeek V4 ProDeepSeek · Texto
    • Gemini Omni 1.1 FlashGoogle · Multimodal
    1. Inicio
    2. Blog
    3. Tutorial
    4. Dominar el inpainting y el outpainting con la API de edición de imágenes de GPT Image 2
    Volver a todos los artículos
    tutorial2026-11-127 min de lectura

    Dominar el inpainting y el outpainting con la API de edición de imágenes de GPT Image 2

    Edita imágenes existentes con el contrato actual de GPT Image 2: cambios guiados por referencias en gpt-image-2 e inpainting con máscara en gpt-image-2-official, todo sobre el endpoint asíncrono de generaciones.

    ToAPIs Engineering & Evaluation Team
    GPT Image 2InpaintingOutpaintingImage APITutorial
    TL;DR - Puntos clave
    • El contrato actual de imágenes de ToAPIs es el POST /v1/images/generations asíncrono, no una llamada multipart síncrona a /v1/images/edits ni un ID de catálogo llamado gpt-image-2-edit.
    • El gpt-image-2 exacto admite ediciones guiadas por prompt mediante reference_images (solo URL públicas, hasta 14). El inpainting con precisión de píxel y máscara alfa está documentado en gpt-image-2-official vía mask_url más image_urls.
    • size es una relación de aspecto como 1:1 o 16:9; resolution es el nivel 1k, 2k o 4k. No envíes una cadena de píxeles como 1024x1024 en size.
    • No existe un flag de outpaint documentado. Para ampliar un lienzo, cambia size al ratio objetivo, pasa el original como referencia y describe la expansión en el prompt.
    • Guarda el id de la tarea y consulta GET /v1/images/generations/{id}. Un timeout del cliente no demuestra que la tarea haya fallado.

    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-2 exacto acepta prompt, size como proporción, resolution como 1k / 2k / 4k y reference_images opcional. El inpainting con máscara está documentado en gpt-image-2-official con image_urls más mask_url.
    • Lo que no es el contrato actual: un ID de modelo llamado gpt-image-2-edit, un POST /v1/images/edits multipart síncrono, o size: "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/images y luego pasa la URL pública devuelta. No se acepta base64 en reference_images, image_urls ni mask_url.
    • Protocolo asíncrono: la llamada de envío devuelve un id de tarea. Consulta GET /v1/images/generations/{id} hasta que el estado sea completed o failed. 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:

    TareaID de modeloCómo apuntas a la fuente¿Máscara?
    Edición guiada por prompt o transferencia de estilogpt-image-2reference_images (lista de URL, máximo 14)No documentada en este ID
    Inpainting con precisión de píxelgpt-image-2-officialimage_urls (lista de URL, máximo 16)mask_url obligatorio con la primera imagen
    Expansión de lienzo (outpainting)Cualquiera de los dos IDPasa el original como referencia y cambia size al ratio objetivoSin 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.

    Un marco de isla de máscara que fluye a través de una pasarela hexagonal hacia un lienzo expandido

    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)

    bash
    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

    bash
    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

    bash
    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.

    python
    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 HTTPCategoría habitualAcción recomendada
    400Campo inválido o combinación no admitidaConfirma 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
    401Clave de API ausente o inválidaRota la clave en el panel de ToAPIs y confirma la cabecera Authorization
    429Límite de tarifa o de concurrenciaRespeta Retry-After cuando esté presente; aplica backoff con jitter; reintenta solo cuando sea seguro
    5xx o timeout de redProblema temporal de la pasarela o del upstreamComprueba el estado de la tarea antes de reenviar; usa una política de reintentos acotada

    WaitTime=min⁡(MaxWait,BaseInterval×2attempt)+Uniform(0,1)\text{WaitTime} = \min(\text{MaxWait}, \text{BaseInterval} \times 2^{\text{attempt}}) + \text{Uniform}(0, 1)WaitTime=min(MaxWait,BaseInterval×2attempt)+Uniform(0,1)


    5. Precios y ROI con FinOps

    Costo estimado=imaˊgenes facturables exitosas×tarifa actual de la cuenta para ese modelo, taman˜o y resolucioˊn\text{Costo estimado} = \text{imágenes facturables exitosas} \times \text{tarifa actual de la cuenta para ese modelo, tamaño y resolución}Costo estimado=imaˊgenes facturables exitosas×tarifa actual de la cuenta para ese modelo, taman˜o y resolucioˊn

    • No reutilices precios unitarios de borradores de planificación como un par plano $0.024 / $0.048 de "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.025 por imagen en 1K / 2K / 4K para el gpt-image-2 está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.com frente a toapis.cn) es una elección de URL base, no un descuento documentado. Las ganancias de FinOps vienen de hacer borradores en 1k, evitar envíos duplicados tras un timeout del cliente y elegir la SKU correcta (gpt-image-2 frente a gpt-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.com o, cuando sea necesario, https://toapis.cn) y sube una imagen de origen con POST /v1/uploads/images.
    • Prueba una edición guiada por prompt en gpt-image-2 con reference_images, size: "1:1" y resolution: "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ía image_urls más mask_url.
    • Guarda el id de la tarea, consulta GET /v1/images/generations/{id} con un plazo acotado y respeta Retry-After en 429.
    • 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.

    Explora los modelos mencionados en este artículo

    OpenAIIMAGE

    GPT-Image-2

    Tarifa actual: 3 credits /request
    Guía del modeloProbar en la consolaObtener clave de API
    OpenAIIMAGE

    gpt-image-2-official

    Tarifa actual: Input 800 credits/1M, Output 4,800 credits/1M
    Guía del modeloProbar en la consolaObtener clave de API

    Artículos relacionados

    tutorial2026-11-12T10:00:00+08:007 min de lectura

    Generar imágenes nativas en 4K con GPT Image 2: relaciones de aspecto y flujos de escalado

    Genera salida nativa en 4K con el contrato actual de GPT Image 2: define size como una relación de aspecto y resolution como 4k. No existe un flag upscale: true documentado, y el tamaño en píxeles del 4K depende de la proporción que elijas.

    TO
    ToAPIs Engineering & Evaluation Team
    #GPT Image 2
    tutorial2026-11-11T10:00:00+08:007 min de lectura

    GPT Image 2: espejo global y proxy para equipos internacionales

    Cómo los equipos internacionales pueden llamar a la API de GPT Image 2 mediante un origen documentado de ToAPIs, reutilizar sesiones y consultar tareas de imagen asíncronas, sin depender de cifras de latencia no verificadas.

    TO
    ToAPIs Engineering & Evaluation Team
    #GPT Image 2
    tutorial2026-10-23T10:00:00+08:004 min de lectura

    Guía completa de la API GPT Image 2: parámetros, especificaciones oficiales y ejemplos en Python

    Guía de integración para desarrolladores de la API GPT Image 2. Aprende a ajustar parámetros, usar resoluciones HD, controlar la relación de aspecto, aplicar inpainting e implementar en Python y Node.js.

    TO
    ToAPIs Engineering & Evaluation Team
    #GPT Image 2
    ToAPIs
    InicioToAPIs
    Pasarela empresarial de API de IA. Accede a GPT-5, Claude, Gemini y más de 200 modelos mediante una única API unificada.

    Modelos populares

    • Seedance 2.5 API
    • Seedance 2.0 API
    • Veo 3.1 Fast API
    • Kling 3.0 Turbo API
    Mostrar másMostrar menos
    • GPT Image 2 API
    • Claude Opus 4.8 API
    • Nano Banana 2 API
    • Seedance 2 Mini API
    • Todos los modelos

    Categorías de API

    • API de imagen con IA
    • API de vídeo con IA
    • API texto a vídeo
    • API imagen a vídeo
    Mostrar másMostrar menos
    • API de edición de imágenes con IA
    • API de LLM y razonamiento
    • Todas las herramientas API →

    Alternativas

    Alternativas
    • Alternativa a Kie.ai
    • Alternativa a Fal.ai
    • Alternativa a OpenRouter
    • Alternativa a Replicate
    • Alternativa a Wavespeed AI
    • Todas las comparativas →

    Guías destacadas

    Guías destacadas
    • Precios de Seedance 2.0 y 2.5
    • Guía de la API Seedance más económica
    • Guía de integración de MiniMax H3
    • Clave de API gratuita de Seedance 2
    • Inicio rápido de la API Seedance 2
    • Todos los artículos técnicos →

    Desarrolladores y plataforma

    Desarrolladores y plataforma
    • Documentación de API
    • MCP
    • Precios
    • Área de pruebas de modelos
    • LLMs.txt
    • Contactar con soporte
    • Directorio de guías de modelos
    Entidad operadora:
    鯨樞智能科技有限公司
    JINGSHU INTELLIGENT LIMITED
    Domicilio social:
    ROOM 5042, 5/F, YAU LEE CENTRE, NO.45, HOI YUEN ROAD, KWUN TONG, KOWLOON, HONG KONG
    PrivacidadTérminosUso aceptableEliminación de datosConservación de datosSubencargados y regionesFacturación y reembolsosPolítica de cookiesMapa del sitioAcerca de

    © 2026 ToAPIs. Todos los derechos reservados.