HiAPI
Pt
Blogue

Tutorial

Como usar grok-imagine image-to-image pela API hiapi: curl, Python e uma requisição funcional

Jul 11, 2026
Como usar grok-imagine image-to-image pela API hiapi: curl, Python e uma requisição funcional

grok-imagine/image-to-image recebe uma ou mais imagens de referência e um prompt de texto e retorna uma imagem editada — você pode estilizar fotos de produtos, substituir o fundo ou fundir até três imagens de referência em uma única saída. No hiapi, ele é executado por meio da API de tarefas unificada: crie uma tarefa, faça polling (ou receba um callback) e baixe o resultado. Este guia percorre a estrutura exata da requisição, com exemplos de curl e Python prontos para copiar, colar e executar.

O que você vai construir + pré-requisitos

Objetivo: enviar uma imagem de referência e um prompt, obter a URL de uma imagem editada e baixá-la — primeiro de forma interativa por polling, depois com uma versão de produção usando callback.

Você só precisa de uma coisa: uma chave de API hiapi. Obtenha-a no seu painel — ela se parece com sk-... e vai no cabeçalho Authorization: Bearer em cada chamada.

Suas imagens de referência devem ser URLs publicamente acessíveis (o modelo as busca no lado do servidor), então hospede-as primeiro no seu CDN ou armazenamento de objetos.

Exemplo mínimo executável (curl)

Criar a tarefa:

curl -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer sk-<your-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/image-to-image",
    "input": {
      "prompt": "Transforme esta foto de produto em uma foto de estúdio limpa sobre fundo branco contínuo com sombras suaves",
      "image_urls": ["https://your-cdn.com/product.jpg"]
    }
  }'

Há dois campos obrigatórios — prompt e image_urls — e isso já é uma requisição completa. A resposta contém o ID da tarefa em data.taskId:

{
  "data": {
    "taskId": "<task-id>"
  }
}

Consultar o resultado por polling:

curl https://api.hiapi.ai/v1/tasks/<task-id> \
  -H "Authorization: Bearer sk-<your-key>"

Enquanto a tarefa está em execução, data.status informa o progresso. Quando ele se torna success, a URL da imagem fica em data.output[0].url. Se for fail, data.error contém o código de erro e a mensagem.

Um detalhe importante: as URLs de saída são assinadas e expiram (o payload inclui expireAt). Baixe o arquivo imediatamente após a tarefa ter sucesso — nunca armazene nem faça hotlink das URLs de saída brutas.

curl -o result.png "<data.output[0].url>"

O mesmo exemplo em Python

import time
import requests

API = "https://api.hiapi.ai/v1/tasks"
HEADERS = {"Authorization": "Bearer sk-<your-key>"}

payload = {
    "model": "grok-imagine/image-to-image",
    "input": {
        "prompt": (
            "Transforme esta foto de produto em uma foto de estúdio limpa "
            "sobre fundo branco contínuo com sombras suaves"
        ),
        "image_urls": ["https://your-cdn.com/product.jpg"],
        "aspect_ratio": "auto",
        "resolution": "1k",
        "output_format": "png",
    },
}

# 1. Create the task
resp = requests.post(API, json=payload, headers=HEADERS, timeout=60)
resp.raise_for_status()
task_id = resp.json()["data"]["taskId"]
print("task:", task_id)

# 2. Poll until it reaches a terminal state
while True:
    task = requests.get(f"{API}/{task_id}", headers=HEADERS, timeout=30).json()["data"]
    if task["status"] == "success":
        image_url = task["output"][0]["url"]
        break
    if task["status"] == "fail":
        raise RuntimeError(f"task failed: {task.get('error')}")
    time.sleep(5)

# 3. Download immediately — output URLs expire
with open("result.png", "wb") as f:
    f.write(requests.get(image_url, timeout=120).content)
print("saved result.png")

O schema completo de entrada

Campo Obrigatório Tipo Descrição
prompt ✅ string O que alterar / aparência desejada
image_urls ✅ array de URLs 1–3 imagens de referência, devem ser publicamente acessíveis
aspect_ratio opcional enum auto, 2:1, 20:9, 19.5:9, 16:9, 4:3, 3:2, 1:1, 2:3, 3:4, 9:16, 9:19.5, 9:20, 1:2
resolution opcional enum 1k ou 2k — minúsculas
output_format opcional enum jpeg, png ou webp

O schema é estrito: qualquer campo que ele não reconheça é rejeitado com 400. Não há size, não há seed, não há n — se você estiver portando código de outro modelo que usa dimensões em pixels (por exemplo, size: "1024x1024"), use aspect_ratio + resolution aqui. Cada tarefa retorna uma imagem; para obter variantes, envie várias tarefas.

Múltiplas referências: até 3 imagens de entrada

image_urls aceita até três imagens de referência, e o modelo as funde — por exemplo, uma imagem de produto mais uma imagem de fundo e mais uma referência de estilo. Se enviar mais de três, a API rejeita a requisição diretamente:

invalid input: image_urls: maxItems: got 4, want 3

Coloque a imagem mais importante (normalmente o sujeito) em primeiro lugar e explique no prompt o que cada imagem de referência contribui.

Proporção automática

aspect_ratio: "auto" faz o modelo derivar a proporção da saída a partir da sua imagem de referência, em vez de forçar um enquadramento fixo — para fotos de produto e edições em que você quer preservar a composição, esse é o padrão adequado. Defina uma proporção explícita apenas quando o destino exigir (por exemplo, 9:16 para um espaço de stories, 16:9 para um banner de destaque).

Considerações para produção

Use callback em vez de polling

Para cargas em lote ou em servidor, dispense o loop de polling — registre um callback ao criar a tarefa e o hiapi fará POST do resultado final para o seu endpoint:

{
  "model": "grok-imagine/image-to-image",
  "input": {
    "prompt": "...",
    "image_urls": ["https://your-cdn.com/product.jpg"]
  },
  "callback": {
    "url": "https://your-server.com/hooks/hiapi",
    "when": "final"
  }
}

when aceita apenas "final" — você recebe uma chamada quando a tarefa chega a success ou fail, e não eventos de progresso intermediários.

Regra prática: polling para ferramentas interativas (há um usuário acompanhando; um loop com sleep de 5 segundos funciona), callback para pipelines (dezenas de tarefas em execução; você não quer um poller para cada tarefa). Seu handler de callback ainda deve baixar a saída imediatamente — a URL que ele recebe expira como qualquer outra.

Idempotência e retentativas

A API de tarefas separa "envio" de "resultado", o que torna a retentativa segura algo direto:

  • Persista o taskId no momento em que o create retorna. Se o seu processo cair depois, recupere fazendo polling do ID armazenado — não recrie.
  • Só tente novamente quando a chamada create falhar sem retornar um taskId (erro de rede, 5xx). Reenviar uma requisição que já retornou um ID gera uma segunda tarefa cobrada separadamente.
  • Trate status: "fail" como estado final. Corrija a entrada (ou encaminhe para um plano B) e envie uma nova tarefa; tarefas com falha não são reiniciadas.

Erros comuns

O que você vê Significado Como corrigir
401 — permission_denied Chave incorreta, ou chave sem acesso a este modelo Verifique a chave no painel
400 INVALID_REQUEST — missing required field "prompt" / "image_urls" Entrada obrigatória ausente Os dois campos são obrigatórios
400 INVALID_REQUEST — additional properties '...' not allowed Campo desconhecido (por exemplo, size, seed, n) Schema estrito — use apenas os campos da tabela acima
400 INVALID_REQUEST — image_urls: maxItems Mais de 3 imagens de referência Reduza para 3
404 — task not found taskId errado no GET ou pertencente a outra conta Verifique o ID armazenado
status: "fail" durante o polling Aceita, mas a geração falhou Leia data.error, ajuste a entrada e reenvie

Note que falhas de autenticação retornam 401, com "code": "permission_denied" no corpo do erro — vale a pena casar isso explicitamente, porque também cobre o caso de uma chave que existe mas não tem acesso a este modelo.

Próximos passos

Perguntas frequentes

Quantas imagens de referência posso enviar? Até 3 em image_urls. A API rejeita mais de forma rígida (maxItems: got N, want 3).

Posso definir o tamanho da saída em pixels? Não. Não existe campo size — você controla a forma com aspect_ratio (14 valores de enum) e a nitidez com resolution (1k ou 2k, minúsculas). Qualquer outra coisa retorna 400.

O que aspect_ratio: "auto" faz? Faz o modelo seguir a proporção da imagem de referência em vez de forçar um enquadramento fixo — é a escolha comum para edições que precisam preservar a composição.

Quanto tempo as URLs de resultado são válidas? São URLs assinadas com validade (o expireAt no payload de saída). Baixe os bytes o quanto antes depois que a tarefa tiver sucesso; não faça hotlink delas.

Devo usar polling ou callback? Para uso interativo, polling a cada ~5 segundos basta. Para pipelines em lote, envie callback: {"url": ..., "when": "final"} e trate um POST por tarefa — "final" é o único gatilho suportado.

Posso obter várias variantes em uma chamada? Não — não existe parâmetro n. Envie uma tarefa por variante; elas rodam em paralelo de qualquer forma.

Qual é a diferença em relação a grok-imagine-quality/image-to-image? A mesma estrutura de requisição, com um nível de renderização de maior fidelidade (e maior custo). Valide no nível padrão e depois rode o que for manter no nível de qualidade; compare o custo por imagem na página de preços.

EtiquetasAPI de ImagemTutorial

Artigos relacionados

Ver todos os artigos →

Comece a criar com artefactos de IA persistentes

Obtenha a sua chave de API e chame modelos de imagem, vídeo e áudio através de uma única API baseada em tasks.

Ler a documentação da API