Edição em Múltiplas Etapas e Retoques Direcionados
Nesta página
Atualizado em 3 de novembro de 2026. Com base na página Image Editing, no Image Prompting Guide e na referência da API de Imagens da xAI: o endpoint
/v1/images/editsnão possui parâmetromask— nem na referência, nem noxai-sdk1.21.0 — ao contrário do que afirmava a versão anterior. O retoque é direcionado através do prompt, e uma zona é protegida com precisão de píxel por uma máscara aplicada localmente, após a edição. Fontes: Image Editing · Image Prompting Guide · Images API.
Encadeamento de Edições
A edição de imagem torna-se verdadeiramente poderosa quando encadeia múltiplas modificações. O princípio, descrito pela xAI, é simples: o resultado de uma edição torna-se a entrada da seguinte, permitindo-lhe partir de uma imagem base para depois adicionar detalhes, ajustar o estilo ou corrigir, passo a passo.
import requests
import os
headers = {
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
}
def edit_image(image_url, prompt):
"""Edits an image and returns the result URL."""
response = requests.post(
"https://api.x.ai/v1/images/edits",
headers=headers,
json={
"model": "grok-imagine-image",
"prompt": prompt,
"image": {"url": image_url}
}
)
response.raise_for_status()
return response.json()["data"][0]["url"]
# Turn 1: modify the background
url_tour1 = edit_image(
"https://exemple.com/portrait.jpg",
"Replace the background with a modern office overlooking the city. "
"Keep the same person, pose, and framing."
)
# Turn 2: adjust the lighting
url_tour2 = edit_image(
url_tour1,
"Make the light warm and dim, like late afternoon. "
"Keep the same person, decor, and framing."
)
# Turn 3: add an element
url_tour3 = edit_image(
url_tour2,
"Place an open laptop on the desk, in front of the person. "
"Keep the same person, lighting, and framing."
)
print(f"Final result: {url_tour3}")
Melhores Práticas para Edição em Múltiplas Etapas
O guia da xAI aconselha a editar quando o sujeito e a composição já estão bons e apenas um a três detalhes precisam de alteração; se o próprio sujeito estiver errado, é preferível regenerar a imagem. Cada etapa começa pela modificação, seguindo-se uma frase que indica o que não se move: o sujeito, o ângulo, o enquadramento ou a posição dos objetos. Segundo o guia, duas formulações falham: uma que abre com «manter tudo», que quase nada altera, e outra que copia um prompt completo, o que recomponha a cena — o sujeito desvia-se, um objeto duplica ou transforma-se num objeto vizinho.
Ordene as etapas do geral para o específico: primeiro o fundo, a composição e a atmosfera; depois os acessórios e as correções finas, para que uma alteração majoritária tardia não desfça os pequenos retoques anteriores.
Duas precauções de segurança completam o método. Descarregue cada resultado intermédio assim que for produzido: os URLs são temporários e perder a etapa 3 de uma série de cinco obriga-o a recomeçar desde a etapa 2. Inspecione cada passo antes de encadear: um defeito introduzido na etapa 1 — um dedo distorcido, uma sombra inconsistente — permanecerá em todas as etapas subsequentes, já que cada uma parte da imagem anterior.
Direcionar uma Zona através do Prompt
A API não aceita máscaras: é o prompt que direciona. Designe a parte a modificar com a maior precisão possível — por nome, posição, material — e indique o que deve permanecer idêntico.
url_chapeau = edit_image(
url_tour3,
"Replace the person's cap with a wide-brimmed straw hat. "
"Keep the same face, hairstyle, decor, and framing."
)
Quando uma correção não resulta, o guia recomenda alterar as palavras em vez de repetir o mesmo pedido, designando a parte da imagem a corrigir e o que esta deve mostrar. Para montar várias imagens — um produto num cenário, um personagem de uma imagem para outra — a edição aceita até cinco imagens de origem (lição 7).
Proteger uma Zona com Precisão de Píxel: A Máscara Local
Se uma parte da imagem não deve mover-se um único píxel — um logótipo, um rosto, texto — aplique a máscara localmente, após a edição: mantém a zona original e aproveita da edição apenas o que está fora dessa zona. Com a Pillow, Image.composite(image1, image2, mask) copia image1 onde a máscara é branca e mantém image2 onde é preta:
from PIL import Image, ImageDraw
original = Image.open("original.jpg").convert("RGB")
edite = Image.open("edite.jpg").convert("RGB").resize(original.size)
# Mask: white = take edit, black = keep original
masque = Image.new("L", original.size, 255)
draw = ImageDraw.Draw(masque)
draw.rectangle([40, 40, 360, 160], fill=0) # protected zone, e.g., a logo
resultat = Image.composite(edite, original, masque)
resultat.save("resultat.jpg")
As três imagens devem ter o mesmo tamanho. O redimensionamento pressupõe que a edição manteve a proporção da fonte: verifique-o ou imponha-o através do parâmetro aspect_ratio do pedido. A máscara não impede o modelo de tocar na zona; permite-lhe restaurá-la posteriormente.
Pipeline de Edição Completo
Eis um exemplo de pipeline estruturado, mantendo o histórico de cada etapa:
class ImageEditor:
def __init__(self, api_key):
self.headers = {
"Authorization": f"Bearer {api_key}",
"Content-Type": "application/json"
}
self.history = []
def edit(self, image_url, prompt):
response = requests.post(
"https://api.x.ai/v1/images/edits",
headers=self.headers,
json={
"model": "grok-imagine-image",
"prompt": prompt,
"image": {"url": image_url}
}
)
response.raise_for_status()
result_url = response.json()["data"][0]["url"]
self.history.append({
"prompt": prompt,
"input": image_url,
"output": result_url
})
return result_url
Pontos-chave
- A edição em múltiplas etapas encadeia resultados: cada saída torna-se a entrada da edição seguinte
- Edite quando o sujeito e a composição estiverem bons e apenas um a três detalhes precisarem de alteração
- Cada etapa: primeiro a modificação, depois o que deve permanecer idêntico
- A API não tem parâmetro
mask: direcione através do prompt e proteja uma zona com uma máscara local aplicada após a edição - Os URLs de saída são temporários: descarregue os resultados intermédios