Como usar a API de imagem para imagem do Grok Image 2.0? Uma imagem de referência e uma frase para editar a imagem

Como usar a API de imagem para imagem do Grok Image 2.0? Envie uma imagem de referência acessível publicamente mais uma instrução de edição, submeta com POST /v1/tasks, e ao consultar o resultado, data.output[0].url é a imagem editada. Preço fixo de $0,065 por imagem, 1K e 2K com o mesmo preço, sem máscara e sem camadas.

O Grok Image 2.0 já está disponível na HiAPI. Abra a página do modelo de imagem para imagem, envie uma imagem e edite. Novos usuários ganham 200 créditos ao se cadastrar, o suficiente para 1 imagem para imagem (130 créditos).

TL;DR

• O que é: grok-imagine-image-2.0/image-to-image, da xAI, edita uma única imagem de referência com instruções em linguagem natural; trocar o fundo, adicionar pequenos objetos, mudar a textura e a cor, tudo é possível.
• Quanto custa: $0,065 por imagem, 1K / 2K e low / medium com o mesmo preço; cobra por imagem gerada com sucesso e reembolso automático em caso de falha. $10 gera cerca de 153 imagens.
• Como chamar mais rápido: apenas prompt e image são obrigatórios; image é uma string de URL, não um array.

Quais são os parâmetros do imagem para imagem do Grok Image 2.0?

Campo	Obrigatório	Valores	Descrição
prompt	Sim	String	Instrução de edição
image	Sim	String	Uma URL JPG / JPEG / PNG / WebP acessível publicamente, não um array
resolution	Não	1k, 2k	Padrão 1k
quality	Não	low, medium	Padrão medium; medium tem melhores detalhes, low é mais rápido
aspect_ratio	Não	Os mesmos 14 valores do texto para imagem	Pode ser enviado, mas não tem efeito; o enquadramento da saída segue a imagem de referência

Cada requisição edita apenas uma imagem de referência, uma tarefa gera uma imagem; para várias, submeta várias tarefas executadas em paralelo. Requisições com nomes de campo ou valores fora da tabela acima retornam 400.

Duas formas: teste online e API

Teste online (1 minuto)

1. Abra a página do modelo de imagem para imagem, faça login e envie a imagem de referência.
2. Digite a instrução de edição e escolha a resolução.
3. Clique em "Executar" e, após o sucesso, compare a imagem de referência com a imagem gerada.

Integração via API (5 minutos)

1. Crie uma API Key no console.
2. Coloque a imagem de referência em um endereço acessível pela internet (seu próprio CDN ou armazenamento de objetos).
3. Submeta a tarefa com POST /v1/tasks e faça polling ou configure um callback.
4. Após o sucesso, baixe imediatamente data.output[0].url.

Keep the elderly luthier exactly as he is: his face, expression, hands, seated pose, and the checked flannel shirt he's wearing, completely unchanged. Replace only the background environment: move him from the wood-shaving workshop into a sunlit outdoor market stall with hanging string instruments and warm afternoon light, matching the new environment's light direction so it falls naturally across his face and hands.

Experimente direto um prompt de edição: mover o velho luthier da oficina de serragem para um mercado ao sol, sem alterar a pessoa. Gerar com este prompt → (o link apenas preenche o prompt; a imagem de referência deve ser enviada na página do modelo, escolha a resolução 2K)

Imagem de referência	Imagem gerada

curl e Python: fazer a primeira edição funcionar

Primeiro defina a API Key:

export HIAPI_API_KEY="sk-..."

Todas as requisições incluem Authorization: Bearer sk-<key>. A edição de imagem é assíncrona e usa a mesma interface de tarefas dos outros modelos da HiAPI. A imagem de referência é buscada pelo servidor; caminhos de arquivo local não funcionam, precisa ser uma URL acessível publicamente.

Passo 1, criar a tarefa:

curl --fail-with-body -sS -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine-image-2.0/image-to-image",
    "input": {
      "prompt": "Change the mug on the table to matte black ceramic, keep everything else in the scene identical",
      "image": "https://your-cdn.example.com/source-photo.jpg",
      "resolution": "2k"
    }
  }'

Retorna imediatamente o taskId:

{
  "code": 200,
  "message": "success",
  "data": { "taskId": "tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q" }
}

Passo 2, fazer polling até o estado final:

curl --fail-with-body -sS https://api.hiapi.ai/v1/tasks/tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Verifique data.status: success significa sucesso, fail significa falha; outros estados, continue aguardando. Exemplo de resposta de sucesso:

{
  "code": 200,
  "data": {
    "taskId": "tk-hiapi-01M01JW1C9N3VHRZAEBFEESC5Q",
    "status": "success",
    "storage": "temp",
    "output": [
      {
        "type": "image",
        "url": "https://temp.hiapi.ai/7c6ttvrbpt/01M01JW1C9N3VHRZAEBFEESC5Q-0.jpg",
        "artifactId": "76711",
        "expireAt": 1787364206
      }
    ]
  },
  "message": "success"
}

Observe storage: "temp" e expireAt: a URL da imagem gerada é temporária; baixe imediatamente após a conclusão da tarefa ou transfira para seu próprio armazenamento de objetos. O enquadramento da saída segue a imagem de referência; o exemplo omite o aspect_ratio que não tem efeito.

Versão em Python:

Primeiro instale requests (python3 -m pip install requests) e defina a HIAPI_API_KEY acima. O script faz polling por no máximo 10 minutos; após o timeout, mantenha o taskId e continue consultando.

import os
import time
import requests

API_KEY = os.environ["HIAPI_API_KEY"]
BASE = "https://api.hiapi.ai/v1"
HEADERS = {"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"}


def task_data(response):
    response.raise_for_status()
    body = response.json()
    if body.get("code") != 200:
        raise RuntimeError(f"HiAPI request failed: {body}")
    return body["data"]


def edit_image(prompt: str, image_url: str, resolution: str = "1k") -> str:
    create = requests.post(
        f"{BASE}/tasks",
        headers=HEADERS,
        json={
            "model": "grok-imagine-image-2.0/image-to-image",
            "input": {
                "prompt": prompt,
                "image": image_url,
                "resolution": resolution,
            },
        },
        timeout=30,
    )
    task_id = task_data(create)["taskId"]
    print(f"taskId: {task_id}", flush=True)
    deadline = time.monotonic() + 600

    while time.monotonic() < deadline:
        poll = requests.get(f"{BASE}/tasks/{task_id}", headers=HEADERS, timeout=30)
        data = task_data(poll)
        if data["status"] == "success":
            return data["output"][0]["url"]
        if data["status"] == "fail":
            raise RuntimeError(f"task {task_id} failed: {data}")
        time.sleep(2)
    raise TimeoutError(f"task {task_id} is still pending; query this ID instead of submitting again")


if __name__ == "__main__":
    url = edit_image(
        "Change the mug on the table to matte black ceramic, keep everything else identical",
        "https://your-cdn.example.com/source-photo.jpg",
        resolution="2k",
    )
    print(url)

O que observar antes de ir para produção?

• Coloque a imagem de referência na internet primeiro. Se a imagem enviada pelo usuário estiver em um bucket privado ou em localhost, a plataforma não consegue buscá-la e a tarefa falha de forma assíncrona; antes de submeter, confirme que o link é acessível publicamente e use um endereço de longa duração (não use links assinados que expiram).

• Escreva a instrução como "o que manter, o que alterar apenas". Escreva primeiro a parte que deve permanecer inalterada e depois a parte a alterar; quanto mais estreito o escopo da mudança, mais estável. Veja mais formas em modelos de prompt de imagem para imagem.

• Para lote, use callback, não polling em loop apertado.

  {
    "model": "grok-imagine-image-2.0/image-to-image",
    "input": { "prompt": "...", "image": "https://your-cdn.example.com/source-photo.jpg" },
    "callback": { "url": "https://your-service.example.com/hooks/hiapi", "when": "final" }
  }
  

  when: "final" notifica quando a tarefa atinge o estado final de sucesso ou falha; o receptor deve deduplicar por taskId.

• Transfira a imagem gerada imediatamente. data.output[0].url é um endereço temporário e expira conforme expireAt.

• Submeta cada tarefa apenas uma vez. Após receber a resposta, salve a correspondência entre o taskId e a tarefa de negócio; submeter repetidamente pode criar várias tarefas e cobrar por cada uma. Se a requisição de criação der timeout sem receber o ID, verifique primeiro o registro de tarefas e só então decida se deve submeter novamente.

• Especifique resolution explicitamente. O padrão é 1k; 1K e 2K têm o mesmo preço ($0,065), então para imagens finais envie "2k" diretamente.

• Tratamento de erros. Verifique primeiro o status HTTP e o code e message da resposta, depois leia data. Erros de parâmetro ou de autenticação devem ser corrigidos antes de submeter novamente; quando a tarefa retorna fail, registre o erro e pare o polling.

Leitura relacionada

• Página do modelo de texto para imagem do Grok Image 2.0: mesma família, gera novas imagens apenas com texto.
• Quanto custa a API do Grok Image 2.0?
• Integração com a API de texto para imagem do Grok Image 2.0
• Modelos de prompt de imagem para imagem do Grok Image 2.0
• Autenticação e Início rápido

Perguntas frequentes

image recebe uma URL ou um array? Uma string de URL. Passar um array gera erro de tipo. Para combinar várias imagens, use um modelo que suporte múltiplas imagens de referência.

Como resolver o erro "additional properties not allowed"? input aceita apenas prompt, image, aspect_ratio, resolution, quality. image_urls, strength, mask, seed, negative_prompt, comuns em outros modelos de edição, não estão disponíveis aqui; basta removê-los.

O navegador abre a imagem de referência, por que a tarefa ainda pode falhar? A plataforma busca a imagem no servidor; a imagem de referência deve ser acessível publicamente e sem login; links assinados precisam permanecer válidos até a conclusão da busca. Verifique permissões de acesso, formato e validade do link antes de submeter.

Posso editar várias imagens de uma vez? Não, entra uma imagem e sai uma imagem. Para lote, submeta várias tarefas executadas em paralelo.

Por que imagem para imagem é mais caro que texto para imagem? Imagem para imagem custa $0,065 e texto para imagem $0,052, 25% a mais, correspondente à capacidade de "editar com uma imagem de referência".

Por quanto tempo o endereço de saída é válido? Armazenamento temporário; o expireAt na resposta é um timestamp Unix. Baixe ou transfira imediatamente após o sucesso da tarefa.

Preciso esperar o resultado de forma síncrona? Não. A interface de criação retorna imediatamente após a tarefa entrar na fila; scripts curtos fazem polling de GET /v1/tasks/<taskId>, e em produção configure um callback.

Edite sua primeira imagem agora

Primeiro defina HIAPI_API_KEY, depois substitua o endereço image nos exemplos de curl e Python pela URL pública da sua própria imagem. Para ver o resultado primeiro, abra a página do modelo de imagem para imagem, envie a imagem e cole o prompt acima.