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

Endpoint /v1/images/edits: Edite as Suas Imagens

Aula 5 de 14 Atualizada a 2 de novembro de 2026 Iniciante
Nesta página
  1. Edição de Imagens com a API Grok
  2. Estrutura do Pedido de Edição
  3. Por Que Utilizar requests em Vez do SDK da OpenAI?
  4. Parâmetros do Endpoint de Edição
  5. Tipos de Edições Possíveis
  6. Prática Guiada
  7. Pontos-chave

Atualizado a 2 de novembro de 2026 — Imagine. O modelo grok-imagine-image-quality foi removido a 2 de novembro de 2026 (os seus pedidos são agora processados pelo Imagine 2.0 com qualidade low): os exemplos atuais utilizam grok-imagine-image (Imagine 1.0) e grok-imagine-image-2.0 (Imagine 2.0, com qualidade low, medium ou auto). Com o SDK da OpenAI, os parâmetros aspect_ratio, resolution e quality devem ser passados através de extra_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.

5
Imagens de origem máximas
2
Formatos de entrada
JSON
Content-Type obrigatório
∞
Ciclos de edição

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) ou grok-imagine-image-2.0 (Imagine 2.0, que também aceita quality)
  • prompt (obrigatório): descrição da modificação a aplicar
  • image: objeto contendo o URL de uma única imagem de origem
  • images: array de objetos para múltiplas imagens de origem (mutuamente exclusivo com image)
  • mask: objeto contendo o URL da máscara da área a editar
  • n: número de variantes a gerar (1 a 10)
  • response_format: url ou b64_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 requests em 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