ToAPIs
    InícioToAPIs
    Geração de imagensGPT Image 2.6, Gemini, FLUX…Geração de vídeoSeedance, Veo, Kling, Sora…Chat e escritaGPT-5.6, Claude, DeepSeek…Voz e músicaLocuções, TTS, áudio
    NovidadeSeedance 2.5
    PreçosDocumentação da APIMCP
    BlogAlternativas
    EntrarComece grátis
    Todos os modelosPreçosDocumentação da APIMCPBlogAlternativas
    EntrarComece grátis

    Idioma

    Esc
    • Seedance 2.5Geração de vídeo
    • GPT Image 2Geração de imagens
    • GPT Image 2.6Geração de imagens
    • GPT Image 2.5Geração de imagens
    • Veo 3.1 FastGeração de vídeo
    • Kling 3.0 TurboGeração de vídeo
    • Kling V4 FlashGeração de vídeo
    • Grok Video 1.5Geração de vídeo
    • Nano Banana 2Geração de imagens
    • Seedream 5.5Geração de imagens
    • FLUXGeração de imagens
    • Sora 2Geração de vídeo
    • Todos os modelos de imagemCategoria
    • Todos os modelos de vídeoCategoria
    • GPT-5.6 SolChat e código
    • Claude Opus 4.8Chat e código
    • Claude Opus 4.7Chat e código
    • DeepSeek V4 ProDeepSeek · Texto
    • Gemini Omni 1.1 FlashGoogle · Multimodal
    1. Início
    2. Blog
    3. Tutorial
    4. Dominar inpainting e outpainting com a API de edição de imagens do GPT Image 2
    Voltar a todos os artigos
    tutorial2026-11-127 min de leitura

    Dominar inpainting e outpainting com a API de edição de imagens do GPT Image 2

    Edite imagens existentes com o contrato atual do GPT Image 2: mudanças guiadas por referência no gpt-image-2 e inpainting com máscara no gpt-image-2-official, tudo no endpoint assíncrono de gerações.

    ToAPIs Engineering & Evaluation Team
    GPT Image 2InpaintingOutpaintingImage APITutorial
    TL;DR - Principais conclusões
    • O contrato atual de imagens da ToAPIs é o POST /v1/images/generations assíncrono, não uma chamada multipart síncrona para /v1/images/edits nem um ID de catálogo chamado gpt-image-2-edit.
    • O gpt-image-2 exato aceita edições guiadas por prompt via reference_images (somente URLs públicas, até 14). O inpainting com precisão de pixel e máscara alfa está documentado no gpt-image-2-official via mask_url mais image_urls.
    • size é uma proporção como 1:1 ou 16:9; resolution é o nível 1k, 2k ou 4k. Não envie uma string de pixels como 1024x1024 em size.
    • Não existe um flag de outpaint documentado. Para ampliar um canvas, mude size para a proporção alvo, passe o original como referência e descreva a expansão no prompt.
    • Guarde o id da tarefa e consulte GET /v1/images/generations/{id}. Um timeout do cliente não prova que a tarefa falhou.

    Dominar inpainting e outpainting com a API de edição de imagens do GPT Image 2

    Modelos alvo: gpt-image-2, gpt-image-2-official
    Endpoint de inferência: https://api.toapis.com/v1/images/generations
    Relacionado: Guia da API GPT Image 2 · Fluxos de proporção em 4K · Espelho e proxy global · Referência oficial de inpainting


    1. TL;DR e visão geral de desempenho

    • Tarefa: substituir uma região de uma imagem existente (inpainting) ou estender o canvas para uma nova proporção (outpainting) sem inventar uma segunda API não documentada.
    • Contrato: use os IDs de modelo que existem no catálogo. O gpt-image-2 exato aceita prompt, size como proporção, resolution como 1k / 2k / 4k e reference_images opcional. O inpainting com máscara está documentado no gpt-image-2-official com image_urls mais mask_url.
    • O que não é o contrato atual: um ID de modelo chamado gpt-image-2-edit, um POST /v1/images/edits multipart síncrono, ou size: "1024x1024". Essas formas aparecem em rascunhos antigos e não devem ser copiadas para clientes novos.
    • E/S: suba as imagens de origem e as máscaras com POST /v1/uploads/images e depois passe a URL pública retornada. Base64 não é aceito em reference_images, image_urls nem mask_url.
    • Protocolo assíncrono: a chamada de envio retorna um id de tarefa. Consulte GET /v1/images/generations/{id} até o status ser completed ou failed. Um timeout do cliente não prova que a tarefa falhou.

    2. O poder da edição programática de imagens

    Gerar uma imagem estática a partir de um prompt de texto é apenas o primeiro passo. Catálogos, anúncios e sistemas de design em produção normalmente precisam de uma revisão direcionada: trocar um produto, limpar um fundo ou esticar uma foto de produto quadrada até um hero largo, mantendo a iluminação e a identidade do sujeito.

    A família atual GPT Image 2 da ToAPIs cobre esses trabalhos em um caminho, POST /v1/images/generations, com dois IDs de modelo diferentes:

    TarefaID de modeloComo você aponta para a origemMáscara?
    Edição guiada por prompt ou transferência de estilogpt-image-2reference_images (lista de URLs, máximo 14)Não documentada neste ID
    Inpainting com precisão de pixelgpt-image-2-officialimage_urls (lista de URLs, máximo 16)mask_url obrigatório com a primeira imagem
    Expansão de canvas (outpainting)Qualquer um dos IDsPasse o original como referência e mude size para a proporção alvoSem flag de outpaint dedicado

    image_urls é um alias retrocompatível de reference_images no gpt-image-2 exato e é normalizado pelo gateway. Os exemplos de canal oficial na referência da API usam image_urls junto com mask_url. Use os nomes de campo da referência correspondentes ao ID que você realmente chama.

    Uma máscara de inpainting utilizável é um PNG com canal alfa. As dimensões em pixels devem coincidir com a primeira imagem de referência. Pixels transparentes (alpha = 0) são a zona a regenerar; pixels opacos devem ser preservados. Construa a máscara no seu pipeline (por exemplo com Pillow), suba e envie apenas a URL.

    O outpainting é um fluxo de trabalho, não um endpoint separado. Se você tem uma foto de produto em 1:1 e precisa de um banner 16:9, mantenha o original como referência, defina size como 16:9, escolha um nível de resolution explícito e instrua o modelo a manter o sujeito e estender a cena. Uma variante prática é compor o original sobre um canvas transparente maior, subir esse canvas e tratá-lo como referência: continua sendo /v1/images/generations, e continua sem um flag outpaint: true.

    Uma moldura de ilha de máscara fluindo por um gateway hexagonal até um canvas expandido

    Figura 1: um canvas de origem e uma região interna mascarada passam pelo gateway da ToAPIs; o caminho documentado continua sendo POST /v1/images/generations, com mask_url reservado ao gpt-image-2-official.

    size e resolution seguem o mesmo contrato de texto para imagem: size é uma proporção como 1:1 ou 16:9, e resolution é 1k, 2k ou 4k. O gpt-image-2 exato não expõe um campo quality no contrato atual do playground; quality (low / medium / high) aparece no gpt-image-2-official. Veja o guia de fluxos em 4K para a tabela de pixels documentada.


    3. Implementação em produção: cURL e Python

    Os exemplos internacionais desta série usam https://api.toapis.com. A documentação oficial orienta usuários da China continental a usar https://toapis.cn. Mantenha uma origem por ambiente. Caminhos, IDs de modelo e o cabeçalho Bearer continuam iguais.

    Passo 1: suba uma imagem de origem (e uma máscara, se precisar)

    bash
    curl -X POST "https://api.toapis.com/v1/uploads/images" \
      -H "Authorization: Bearer $TOAPIS_API_KEY" \
      -F "file=@./product.png"
    

    A resposta inclui data.url. Repita a chamada para uma máscara PNG quando você chamar o gpt-image-2-official. Não inclua base64 dentro da requisição de geração.

    Passo 2: edição guiada por prompt no gpt-image-2 exato

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

    Passo 3: inpainting com máscara no 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"
      }'
    

    Passo 4: helper em Python para enviar e consultar

    Ajuste os nomes de campo à referência da API do ID de modelo que você chama. O trecho usa o caminho de status de imagem documentado e os status 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 executar inpainting com máscara, suba uma máscara RGBA correspondente, mude model para gpt-image-2-official e envie image_urls mais mask_url. Guarde o ID de modelo, size e resolution junto ao registro da tarefa, para que uma mudança posterior de SKU seja uma decisão explícita.


    4. Tratamento de erros e matriz de status

    As categorias abaixo são pontos de partida para diagnóstico, não uma garantia de códigos de erro exatos da ToAPIs. Um envio HTTP bem-sucedido ainda exige que você leia o status da tarefa.

    Status HTTPCategoria comumAção recomendada
    400Campo inválido ou combinação não suportadaConfirme o ID de modelo, que size é uma proporção documentada, que resolution é 1k / 2k / 4k, que as URLs são públicas e que uma máscara (quando usada) é um PNG do mesmo tamanho com canal alfa no gpt-image-2-official
    401Chave de API ausente ou inválidaRotacione a chave no painel da ToAPIs e confirme o cabeçalho Authorization
    429Limite de taxa ou de concorrênciaRespeite Retry-After quando presente; aplique backoff com jitter; tente novamente só quando for seguro
    5xx ou timeout de redeProblema temporário no gateway ou no upstreamVerifique o status da tarefa antes de reenviar; use uma política de retry limitada

    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. Preços e ROI com FinOps

    Custo estimado=imagens cobraˊveis bem-sucedidas×tarifa atual da conta para esse modelo, tamanho e resoluc¸a˜o\text{Custo estimado} = \text{imagens cobráveis bem-sucedidas} \times \text{tarifa atual da conta para esse modelo, tamanho e resolução}Custo estimado=imagens cobraˊveis bem-sucedidas×tarifa atual da conta para esse modelo, tamanho e resoluc¸​a˜o

    • Não reutilize preços unitários de rascunhos de planejamento como um par fixo $0.024 / $0.048 de "padrão vs HD". Esses números estão desatualizados em relação ao catálogo atual, que cobra por ID de modelo e, na comparação padrão da landing do GPT Image 2, por nível de resolução.
    • O guia do modelo GPT Image 2 mostra atualmente uma comparação na landing da ToAPIs de $0.015 / $0.020 / $0.025 por imagem em 1K / 2K / 4K para o gpt-image-2 padrão. Trate isso como uma comparação publicada, não como uma fatura contratual. SKUs de canal oficial e descontos de conta podem diferir; confirme a tarifa aplicável ao ID exato que você chama.
    • O roteamento (api.toapis.com versus toapis.cn) é uma escolha de URL base, não um desconto documentado. Os ganhos de FinOps vêm de rascunhar em 1k, evitar envios duplicados após um timeout do cliente e escolher a SKU correta (gpt-image-2 versus gpt-image-2-official), em vez de supor um modelo de "edição" mais barato.
    • Como contexto, veja o artigo de preços do GPT Image 2 e depois confira cada número no catálogo em tempo real antes de colocá-lo em uma previsão.

    6. Perguntas frequentes

    Veja o bloco FAQ do frontmatter. Resumo: o gpt-image-2 exato não documenta mask_url nem /v1/images/edits; o inpainting com máscara está documentado no gpt-image-2-official; as máscaras devem ser PNG RGBA do mesmo tamanho entregues como URL; o outpainting é uma mudança de size mais uma imagem de referência; a cobrança deve ser confirmada na conta para o ID de modelo exato.


    7. Checklist de ações

    • Crie uma chave no Portal de desenvolvedores da ToAPIs.
    • Defina uma URL base por ambiente (https://api.toapis.com ou, quando necessário, https://toapis.cn) e suba uma imagem de origem com POST /v1/uploads/images.
    • Teste uma edição guiada por prompt no gpt-image-2 com reference_images, size: "1:1" e resolution: "1k".
    • Se precisar de uma máscara com precisão de pixel, mude para gpt-image-2-official, suba uma máscara RGBA que coincida com a primeira imagem e envie image_urls mais mask_url.
    • Guarde o id da tarefa, consulte GET /v1/images/generations/{id} com um prazo limitado e respeite Retry-After em 429.
    • Em seguida: o guia de proporção em 4K se você for elevar resolution, e o guia da API para o mapa completo de parâmetros.

    Explore os modelos mencionados neste artigo

    OpenAIIMAGE

    GPT-Image-2

    Taxa atual: 3 credits /request
    Guia do modeloTestar no consoleObter chave de API
    OpenAIIMAGE

    gpt-image-2-official

    Taxa atual: Input 800 credits/1M, Output 4,800 credits/1M
    Guia do modeloTestar no consoleObter chave de API

    Artigos relacionados

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

    Gerar imagens nativas em 4K com o GPT Image 2: proporções e fluxos de upscaling

    Gere saída nativa em 4K com o contrato atual do GPT Image 2: defina size como uma proporção e resolution como 4k. Não existe um flag upscale: true documentado, e o tamanho em pixels do 4K depende da proporção que você escolher.

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

    GPT Image 2: espelho global e proxy para equipes internacionais

    Como equipes internacionais podem chamar a API GPT Image 2 por uma origem documentada da ToAPIs, reutilizar sessões e consultar tarefas de imagem assíncronas, sem depender de números de latência não verificados.

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

    Guia completo da API GPT Image 2: parâmetros, especificações oficiais e exemplos em Python

    Guia de integração para desenvolvedores da API GPT Image 2. Aprenda a ajustar parâmetros, usar resoluções HD, controlar a proporção, aplicar inpainting e implementar em Python e Node.js.

    TO
    ToAPIs Engineering & Evaluation Team
    #GPT Image 2
    ToAPIs
    InícioToAPIs
    Gateway empresarial de API de IA. Acesse GPT-5, Claude, Gemini e mais de 200 modelos por uma única API unificada.

    Modelos populares

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

    Categorias de API

    • API de imagem com IA
    • API de vídeo com IA
    • API de texto para vídeo
    • API de imagem para vídeo
    Mostrar maisMostrar menos
    • API de edição de imagens com IA
    • API de LLM e raciocínio
    • Todas as ferramentas de API →

    Alternativas

    Alternativas
    • Alternativa ao Kie.ai
    • Alternativa ao Fal.ai
    • Alternativa ao OpenRouter
    • Alternativa ao Replicate
    • Alternativa ao Wavespeed AI
    • Todas as comparações →

    Guias em destaque

    Guias em destaque
    • Preços do Seedance 2.0 e 2.5
    • Guia da API Seedance mais barata
    • Guia de integração do MiniMax H3
    • Chave de API gratuita do Seedance 2
    • Início rápido da API Seedance 2
    • Todos os artigos técnicos →

    Desenvolvedores e plataforma

    Desenvolvedores e plataforma
    • Documentação da API
    • MCP
    • Preços
    • Playground de modelos
    • LLMs.txt
    • Falar com o suporte
    • Diretório de guias de modelos
    Entidade operadora:
    鯨樞智能科技有限公司
    JINGSHU INTELLIGENT LIMITED
    Sede social:
    ROOM 5042, 5/F, YAU LEE CENTRE, NO.45, HOI YUEN ROAD, KWUN TONG, KOWLOON, HONG KONG
    PrivacidadeTermosUso aceitávelExclusão de dadosRetenção de dadosSubprocessadores e regiõesCobrança e reembolsosPolítica de CookiesMapa do siteSobre

    © 2026 ToAPIs. Todos os direitos reservados.