Editar imagens existentes (inpainting, outpainting)
Nesta página
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 modelosgpt-image-1.5,gpt-image-1-miniechatgpt-image-latestserão retirados em 1 de dezembro de 2026. Os exemplos agora utilizam ogpt-image-2.5-sunburst, que oferece a maior precisão para edição; ogpt-image-2.5-flareé mais rápido para geração geral. Ambos os modelos suportam também as definições de qualidadexhighemax. Os modelos GPT Image devolvem sempre imagens em base64: o parâmetroresponse_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.