Endpoint /v1/images/edits: Edite as Suas Imagens
Nesta página
Atualizado a 2 de novembro de 2026 — Imagine. O modelo
grok-imagine-image-qualityfoi removido a 2 de novembro de 2026 (os seus pedidos são agora processados pelo Imagine 2.0 com qualidadelow): os exemplos atuais utilizamgrok-imagine-image(Imagine 1.0) egrok-imagine-image-2.0(Imagine 2.0, com qualidadelow,mediumouauto). Com o SDK da OpenAI, os parâmetrosaspect_ratio,resolutionequalitydevem ser passados através deextra_body, e a edição requer o uso do SDK da xAI ou de um pedido HTTP direto.
Edição de Imagens com a API Grok
Para além da geração, a API da xAI disponibiliza um endpoint dedicado à edição de imagens existentes: POST /v1/images/edits. Este endpoint permite-lhe modificar, transformar ou melhorar imagens, descrevendo as alterações desejadas num simples prompt de texto.
Estrutura do Pedido de Edição
A edição funciona de forma semelhante à geração, com uma diferença que altera completamente a forma como escreve os seus prompts: o prompt descreve a modificação, e não a imagem final. Dizer «uma mulher com óculos de sol» regenera uma imagem inteira; dizer «adicionar óculos de sol» mantém a fotografia e intervém apenas nesse ponto. Esta é a confusão mais comum na primeira tentativa e explica a maioria dos resultados dececionantes.
import requests
import os
headers = {
"Authorization": f"Bearer {os.getenv('XAI_API_KEY')}",
"Content-Type": "application/json"
}
payload = {
"model": "grok-imagine-image",
"prompt": "Adicionar um chapéu vermelho à personagem",
"image": {
"url": "https://exemple.com/photo-personnage.jpg"
}
}
response = requests.post(
"https://api.x.ai/v1/images/edits",
headers=headers,
json=payload
)
result = response.json()
edited_url = result["data"][0]["url"]
Por Que Utilizar requests em Vez do SDK da OpenAI?
Eis a armadilha técnica desta lição, que deve conhecer antes de perder uma hora com isto: a compatibilidade com o SDK da OpenAI, que funciona perfeitamente para geração, para na edição. O endpoint de edição da xAI utiliza um formato JSON, enquanto o método images.edit() do SDK envia dados no formato multipart/form-data. Esta incompatibilidade de tipo de conteúdo significa que deve utilizar a API REST diretamente com a biblioteca requests para realizar edições.
# NÃO FUNCIONA com a API da xAI
# client.images.edit(...) # Envia multipart, não JSON
# FUNCIONA: chamada REST direta
requests.post(
"https://api.x.ai/v1/images/edits",
headers=headers,
json=payload
)
Parâmetros do Endpoint de Edição
model(obrigatório):grok-imagine-image(Imagine 1.0) ougrok-imagine-image-2.0(Imagine 2.0, que também aceitaquality)prompt(obrigatório): descrição da modificação a aplicarimage: objeto contendo o URL de uma única imagem de origemimages: array de objetos para múltiplas imagens de origem (mutuamente exclusivo comimage)mask: objeto contendo o URL da máscara da área a editarn: número de variantes a gerar (1 a 10)response_format:urloub64_json
Tipos de Edições Possíveis
As cinco categorias abaixo não partilham a mesma taxa de sucesso, e é útil saber isto antes de prometer um resultado. A adição de elementos e a mudança de ambiente funcionam muito bem porque se baseiam no conteúdo existente. A remoção é mais delicada — o modelo tem de reconstruir o que estava por trás do elemento removido — e é aqui que a máscara se torna essencial, ao delimitar com precisão a área a recalcular.
- Adição de elementos: «Adicionar óculos de sol à personagem»
- Remoção: «Remover o fundo e substituí-lo por um fundo branco»
- Transformação de estilo: «Converter esta fotografia numa ilustração em aguarela»
- Modificação de ambiente: «Mudar a cena de dia para noite»
- Correção: «Melhorar a iluminação e aumentar o contraste»
# Exemplo: alterar o estilo de uma imagem
payload = {
"model": "grok-imagine-image",
"prompt": "Transformar esta fotografia numa ilustração no estilo de banda desenhada franco-belga",
"image": {
"url": "https://exemple.com/photo-ville.jpg"
}
}
Prática Guiada
Experimente editar uma imagem em vários passos. Comece com uma modificação simples e refine depois:
# Passo 1: modificar o fundo
payload_step1 = {
"model": "grok-imagine-image",
"prompt": "Substituir o fundo por um pôr do sol sobre o oceano",
"image": {"url": "https://exemple.com/portrait.jpg"}
}
Pontos-chave
- O endpoint de edição é
POST /v1/images/edits - Utilize
requestsem Python, não o SDK da OpenAI (incompatibilidade de formato) - Pode fornecer até 5 imagens de origem por pedido
- O prompt descreve a modificação desejada em linguagem natural
- Ambos os modelos (Imagine 1.0 e Imagine 2.0) estão disponíveis para edição; com o SDK da OpenAI,
images.edit()não é suportado pela xAI: utilize o SDK da xAI ou um pedido HTTP