Inpainting

Marcar uma área com uma máscara e repintar somente essa área; todo o restante permanece como estava.

Não vai escrever código? Consulte Gerar imagens nas suas próprias ferramentas.

POST/v1/images/editsParâmetros comuns

Antes de começar

Você precisa de	Detalhes
Chave de API	Crie uma no console da OfoxAI e substitua `YOUR_OFOX_API_KEY` no código
Ambiente	O cURL precisa do `jq` para decodificar a imagem; o Python precisa de `pip install openai`, além de `pip install pillow` para gerar a máscara; Node.js 18 ou superior, sem dependências
Imagens	Coloque um `input.png` e um `mask.png` do mesmo tamanho no diretório atual. Ainda não tem uma máscara? O passo 1 abaixo mostra como criar uma
Timeout	Defina o timeout do cliente em 600 segundos. Alta qualidade, tamanhos grandes ou edição podem levar vários minutos

Valores usados no código

URL da APIhttps://api.ofox.io/v1

ID do modeloopenai/gpt-image-2.5-flare

Chave de APISubstitua YOUR_OFOX_API_KEY no código pela sua chave

Dependências Pythonpip install openai pillowpillow é usado para criar a máscara

Requisitos da máscara

Original

Máscaracentro transparente, opaco no restante

→

Resultadosomente a área transparente é repintada

Ilustração, não é um resultado gerado de fato

Um PNG com canal alfa. JPEG e PNG opaco não funcionam.
Exatamente o mesmo tamanho da imagem original.
Pixels transparentes são repintados; pixels opacos mantêm o original.
Só funciona no endpoint de edição. Enviada para texto para imagem, é ignorada.

Passos

Criar uma máscara

Pule este passo se você já tiver uma.

Este trecho lê input.png do diretório atual, torna transparente o quadrado central de 40% e salva o resultado como mask.png.

make_mask.py


from PIL import Image, ImageDraw
 
src = Image.open("input.png")
mask = Image.new("RGBA", src.size, (0, 0, 0, 255))          # fully opaque = keep everything
w, h = src.size
ImageDraw.Draw(mask).rectangle(                              # transparent area = what gets repainted
    (int(w * 0.3), int(h * 0.3), int(w * 0.7), int(h * 0.7)), fill=(0, 0, 0, 0)
)
mask.save("mask.png")

Enviar a requisição

Todos os exemplos abaixo foram executados sem alterações. O resultado é salvo como output.png no diretório atual.

cURL

Terminal


# mask.png: same size as input.png, with an alpha channel; transparent area = what gets repainted
curl -s https://api.ofox.io/v1/images/edits \
  -H "Authorization: Bearer YOUR_OFOX_API_KEY" \
  -F "model=openai/gpt-image-2.5-flare" \
  -F "image=@input.png" \
  -F "mask=@mask.png" \
  -F "prompt=An orange cat sitting in the center, background and everything else unchanged" \
  -F "quality=low" \
  -o response.json
 
jq -r '.data[0].b64_json' response.json | base64 --decode > output.png

Como escrever o prompt

Descreva a imagem inteira como ela deve ficar depois, e não apenas o que deve ser adicionado.

	Prompt	Resultado medido
✅	Um gato laranja sentado no centro, fundo e todo o restante inalterados	Um gato no centro; o restante inalterado
❌	Desenhe um gato na área transparente	O modelo tratou “transparente” como conteúdo e desenhou um fundo quadriculado

Resultado medido

Fora da máscara, a imagem quase não muda: a diferença média de pixels em relação ao original fica abaixo de 2/255.

Para comparação, editar a mesma imagem sem máscara alterou a mesma área em 120/255.

Solução de problemas

Sintoma	Causa	Solução
Erro `Invalid image file or mode`	A máscara não é um PNG com canal alfa	Gere-a novamente com o código do passo 1 acima
A imagem inteira mudou	A máscara não teve efeito: foi enviada ao endpoint de texto para imagem, ou a máscara é totalmente opaca	Verifique se você está chamando `/v1/images/edits` e se a máscara tem uma área transparente
Apareceu um fundo quadriculado	O prompt mencionou “a área transparente”	Descreva a imagem inteira, como em Como escrever o prompt

Para outros erros, consulte a tabela completa de erros.

Documentação oficial

A documentação da OpenAI descreve o comportamento ao chamar a OpenAI diretamente. Ao chamar pela OfoxAI, os resultados medidos nestas páginas prevalecem. Por exemplo, não é necessário fixar um provedor para edição.