Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Editar imagens existentes (inpainting, outpainting)

Aula 3 de 12 Atualizada a 2 de novembro de 2026 Programador
Nesta página
  1. Editar imagens existentes
  2. Como funciona a máscara
  3. Inpainting: Substituir um elemento
  4. Outpainting: Estender a imagem
  5. Edição iterativa
  6. Restrições principais

Atualizado em 2 de novembro de 2026 — Modelos de imagem. O gpt-image-1, modelo para o qual este curso foi originalmente escrito, foi descontinuado em 23 de outubro de 2026. Além disso, os modelos gpt-image-1.5, gpt-image-1-mini e chatgpt-image-latest serão retirados em 1 de dezembro de 2026. Os exemplos agora utilizam o gpt-image-2.5-sunburst, que oferece a maior precisão para edição; o gpt-image-2.5-flare é mais rápido para geração geral. Ambos os modelos suportam também as definições de qualidade xhigh e max. Os modelos GPT Image devolvem sempre imagens em base64: o parâmetro response_format, utilizado pelos modelos DALL·E mais antigos, já não é aceite e foi removido do código. Fonte: Image generation (OpenAI).

Editar imagens existentes

O método client.images.edit() modifica uma imagem existente utilizando uma máscara para definir a área a regenerar. Isto resulta em dois casos de uso distintos, que vale a pena nomear com precisão, pois exigem máscaras diferentes. O inpainting preenche ou substitui uma área interior — pode alterar o céu numa paisagem, o ecrã de um computador ou a cor de uma parede. O outpainting, por outro lado, estende a imagem para além das suas fronteiras originais, como transformar um retrato quadrado num banner panorâmico.

Como funciona a máscara

A máscara é uma imagem PNG com as mesmas dimensões da imagem de origem. As áreas transparentes (alfa = 0) indicam onde o modelo deve gerar novo conteúdo; as áreas opacas permanecem intocadas. Esta convenção é contra-intuitiva à primeira vista: naturalmente quer «pintar» o que deseja alterar, mas na realidade precisa de abrir um buraco na máscara. A chamada à API em si permanece simples, exigindo apenas os dois ficheiros e uma descrição do que deve aparecer.

import base64
from openai import OpenAI

client = OpenAI()

response = client.images.edit(
    model="gpt-image-2.5-sunburst",
    image=open("desk_photo.png", "rb"),
    mask=open("desk_mask.png", "rb"),
    prompt="A computer screen displaying a modern analytics dashboard"
)

with open("edited_desk.png", "wb") as f:
    f.write(base64.b64decode(response.data[0].b64_json))

Não precisa de um editor gráfico para criar esta máscara. A biblioteca Pillow pode gerar uma em poucas linhas: comece com uma camada totalmente opaca com as dimensões da origem e, em seguida, desenhe a forma que deseja tornar transparente. O script abaixo cria uma janela retangular no centro da imagem.

from PIL import Image, ImageDraw

# Carregar a imagem de origem para obter as suas dimensões
source = Image.open("desk_photo.png")
width, height = source.size

# Criar uma máscara totalmente opaca (preta)
mask = Image.new("RGBA", (width, height), (0, 0, 0, 255))
draw = ImageDraw.Draw(mask)

# Desenhar uma área transparente (a área a editar)
# Retângulo no centro da imagem
x1, y1 = width // 4, height // 4
x2, y2 = 3 * width // 4, 3 * height // 4
draw.rectangle([x1, y1, x2, y2], fill=(0, 0, 0, 0))

mask.save("desk_mask.png")
print(f"Mask created: {width}x{height}, editable area in center")

Inpainting: Substituir um elemento

Assim que repetir esta operação, faz sentido encapsular a criação da máscara e a chamada à API numa única função, parametrizada pela região a modificar. O prompt deve então descrever apenas o conteúdo esperado dentro da área mascarada, nunca o resto da imagem. O exemplo abaixo aplica esta função a uma fotografia de paisagem, modificando apenas os 400 pixels superiores — o céu — para lhe conferir uma atmosfera tempestuosa.

from openai import OpenAI
from PIL import Image, ImageDraw
import base64

client = OpenAI()

def inpaint_region(image_path, region, prompt, output_path):
    """
    Substituir uma região retangular numa imagem.
    region: tuple (x1, y1, x2, y2) em pixels
    """
    # Criar a máscara
    source = Image.open(image_path)
    mask = Image.new("RGBA", source.size, (0, 0, 0, 255))
    draw = ImageDraw.Draw(mask)
    draw.rectangle(region, fill=(0, 0, 0, 0))
    mask.save("temp_mask.png")

    # Chamar a API
    response = client.images.edit(
        model="gpt-image-2.5-sunburst",
        image=open(image_path, "rb"),
        mask=open("temp_mask.png", "rb"),
        prompt=prompt
    )

    # Guardar o resultado
    with open(output_path, "wb") as f:
        f.write(base64.b64decode(response.data[0].b64_json))
    print(f"Edited image saved: {output_path}")


# Exemplo: Substituir o céu numa foto de paisagem
inpaint_region(
    image_path="landscape.png",
    region=(0, 0, 1024, 400),  # Parte superior = o céu
    prompt="Dramatic sky with purple storm clouds at sunset",
    output_path="landscape_sky_edited.png"
)

Outpainting: Estender a imagem

Ampliar uma imagem requer um passo extra, pois a API não consegue gerar conteúdo «ao lado» de um ficheiro diretamente. Deve primeiro criar uma tela maior, colar a original nela e fornecer uma máscara que proteja exatamente a área ocupada por essa original. Toda a lógica assenta no cálculo das novas dimensões e da posição de colagem com base na direção solicitada.

from openai import OpenAI
from PIL import Image
import base64
from io import BytesIO

client = OpenAI()

def outpaint(image_path, direction, extra_pixels, prompt, output_path):
    """
    Estender uma imagem numa dada direção.
    direction: 'right', 'bottom', 'left', 'top'
    extra_pixels: número de pixels a adicionar
    """
    source = Image.open(image_path).convert("RGBA")
    w, h = source.size

    # Calcular novas dimensões
    if direction == "right":
        new_size = (w + extra_pixels, h)
        paste_pos = (0, 0)
    elif direction == "bottom":
        new_size = (w, h + extra_pixels)
        paste_pos = (0, 0)
    elif direction == "left":
        new_size = (w + extra_pixels, h)
        paste_pos = (extra_pixels, 0)
    elif direction == "top":
        new_size = (w, h + extra_pixels)
        paste_pos = (0, extra_pixels)

    # Criar a tela estendida (transparente = área a gerar)
    extended = Image.new("RGBA", new_size, (0, 0, 0, 0))
    extended.paste(source, paste_pos)

    # A máscara: transparente em todo o lado exceto onde a imagem original está colocada
    mask = Image.new("RGBA", new_size, (0, 0, 0, 0))
    opaque = Image.new("RGBA", (w, h), (0, 0, 0, 255))
    mask.paste(opaque, paste_pos)

    # Guardar temporariamente
    extended.save("temp_extended.png")
    mask.save("temp_mask_outpaint.png")

    response = client.images.edit(
        model="gpt-image-2.5-sunburst",
        image=open("temp_extended.png", "rb"),
        mask=open("temp_mask_outpaint.png", "rb"),
        prompt=prompt
    )

    with open(output_path, "wb") as f:
        f.write(base64.b64decode(response.data[0].b64_json))
    print(f"Extended image saved: {output_path}")


# Estender um retrato para a direita
outpaint(
    image_path="portrait.png",
    direction="right",
    extra_pixels=512,
    prompt="Natural continuation of the scene, same lighting and background",
    output_path="portrait_extended.png"
)

Note a redação do prompt de extensão: «continuação natural da cena, mesma iluminação e fundo». No outpainting, não está a descrever um novo sujeito; está a pedir ao modelo que estenda o que já vê. Um prompt excessivamente criativo produziria uma emenda visível entre o original e a área adicionada.

Edição iterativa

Nada o impede de encadear múltiplas edições na mesma imagem, utilizando cada saída como entrada para o passo seguinte. Esta é a forma mais fiável de construir uma composição complexa: trate primeiro o fundo, depois o primeiro plano, com uma máscara dedicada para cada passagem, em vez de esperar que um único prompt resolva tudo de uma vez.

import base64
from openai import OpenAI

client = OpenAI()

def edit_step(image_path, mask_path, prompt, output_path):
    response = client.images.edit(
        model="gpt-image-2.5-sunburst",
        image=open(image_path, "rb"),
        mask=open(mask_path, "rb"),
        prompt=prompt
    )
    with open(output_path, "wb") as f:
        f.write(base64.b64decode(response.data[0].b64_json))
    return output_path

# Passo 1: Modificar o fundo
step1 = edit_step(
    "scene.png", "mask_background.png",
    "Lush tropical forest background",
    "scene_step1.png"
)

# Passo 2: Adicionar um elemento ao primeiro plano
step2 = edit_step(
    step1, "mask_foreground.png",
    "A colorful macaw parrot perched on a branch",
    "scene_step2.png"
)

print(f"Final result: {step2}")

Restrições principais

Quatro regras técnicas governam o sucesso da chamada. Violar qualquer uma delas resulta num erro imediato, e não num resultado degradado.

  • A imagem de origem e a máscara devem ter as mesmas dimensões
  • Ambos os ficheiros devem estar no formato PNG
  • O tamanho máximo por ficheiro é de 4 MB
  • A máscara utiliza o canal alfa para definir as áreas editáveis

Uma observação empírica soma-se a estas restrições: os resultados são mais consistentes quando a área mascarada representa menos de 50% da imagem. Para além disso, o modelo tem contexto insuficiente para fundir corretamente, e obterá frequentemente melhores resultados dividindo a sua modificação em duas edições sucessivas.

Coloque isto em prática com uma foto da sua secretária ou qualquer imagem livre de direitos: escreva um script que gere automaticamente uma máscara sobre o quarto superior da imagem, substitua essa área por um céu estrelado e guarde o resultado localmente.