HiAPI
Pt
Blogue

Tutorial

Como usar grok-imagine-quality/image-to-image pela API hiapi: curl, Python e requisições funcionais

Jul 11, 2026
Como usar grok-imagine-quality/image-to-image pela API hiapi: curl, Python e requisições funcionais

Este guia mostra como transformar imagens existentes usando grok-imagine-quality/image-to-image (o nível de maior fidelidade da família Grok Imagine) através da API de tarefas unificada da hiapi. Você enviará a imagem de origem e um prompt de texto, consultará o resultado por polling e baixará a imagem gerada. Cada estrutura de requisição e resposta abaixo foi validada contra a API ao vivo.

O que você precisa

  • Uma chave de API hiapi — crie uma no painel.
  • Uma a três URLs de imagem publicamente acessíveis para usar como origem. A plataforma busca e normaliza sua mídia de entrada no lado do servidor, portanto caminhos de arquivo locais e payloads base64 não funcionam — hospede a imagem em um local acessível pela API primeiro.

É só isso. Sem SDK; a API de tarefas é HTTPS + JSON comum.

Modo de requisição

grok-imagine-quality/image-to-image roda no endpoint de tarefas assíncronas: você cria uma tarefa via POST /v1/tasks e depois consulta GET /v1/tasks/<taskId> (ou registra um callback) até a conclusão.

O esquema de entrada é estrito — campos desconhecidos são rejeitados com 400:

Campo Tipo Obrigatório Descrição
prompt string ✅ O que fazer com a imagem de origem
image_urls string[] ✅ 1–3 URLs públicas de imagens de origem/referência
aspect_ratio string – Um dos seguintes: 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 string – 1k ou 2k — minúsculo (1K retorna 400)
output_format string – jpeg, png ou webp

Observe o que não existe: sem size, sem n, sem seed, sem botões de strength ou consistency. O quanto a saída segue a imagem de origem é controlado pelo seu prompt e pelas imagens de referência que você passa — veja o FAQ abaixo.

Exemplo mínimo funcional (curl)

Criar uma 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-quality/image-to-image",
    "input": {
      "prompt": "Turn this product photo into a clean studio shot on a light gray background with soft shadows",
      "image_urls": ["https://your-cdn.example.com/source.jpg"],
      "aspect_ratio": "1:1",
      "resolution": "2k",
      "output_format": "png"
    }
  }'

Uma criação bem-sucedida retorna um ID de tarefa:

{
  "code": 200,
  "data": {
    "taskId": "task_xxxxxxxxxxxx"
  }
}

Consulta até a tarefa atingir um estado terminal:

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

Durante a execução, data.status está em andamento; ao concluir, torna-se success e a imagem fica em data.output:

{
  "code": 200,
  "data": {
    "taskId": "task_xxxxxxxxxxxx",
    "status": "success",
    "output": [
      {
        "url": "https://.../result.png?...&expireAt=...",
        "expireAt": 1760000000
      }
    ]
  }
}

⚠️ A URL de saída é temporária (observe expireAt). Baixe os bytes imediatamente após o sucesso da tarefa e armazene no seu próprio armazenamento — não faça hotlink da URL de resultado.

Se a tarefa falhar, data.status é fail e data.error carrega code e message.

Python: criar, consultar, baixar

Um script completo usando apenas requests:

import time
import requests

API_BASE = "https://api.hiapi.ai/v1/tasks"
API_KEY = "sk-<your-key>"

HEADERS = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}

def create_task(prompt: str, image_urls: list[str]) -> str:
    payload = {
        "model": "grok-imagine-quality/image-to-image",
        "input": {
            "prompt": prompt,
            "image_urls": image_urls,   # 1-3 public URLs
            "aspect_ratio": "1:1",
            "resolution": "2k",         # lowercase: "1k" or "2k"
            "output_format": "png",
        },
    }
    r = requests.post(API_BASE, headers=HEADERS, json=payload, timeout=60)
    data = r.json()
    task_id = (data.get("data") or {}).get("taskId")
    if not task_id:
        raise RuntimeError(f"create failed: {data}")
    return task_id

def wait_task(task_id: str, timeout_s: int = 600, poll_interval: int = 5) -> dict:
    deadline = time.time() + timeout_s
    while time.time() < deadline:
        r = requests.get(f"{API_BASE}/{task_id}", headers=HEADERS, timeout=30)
        task = r.json().get("data") or {}
        status = task.get("status")
        if status == "success":
            return task
        if status == "fail":
            err = task.get("error") or {}
            raise RuntimeError(f"task failed: {err.get('code')} {err.get('message')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} still running after {timeout_s}s")

if __name__ == "__main__":
    task_id = create_task(
        prompt="Turn this product photo into a clean studio shot on a light gray background",
        image_urls=["https://your-cdn.example.com/source.jpg"],
    )
    print("task:", task_id)

    task = wait_task(task_id)
    url = task["output"][0]["url"]

    # The output URL expires -- download immediately and persist yourself
    img = requests.get(url, timeout=120).content
    with open("result.png", "wb") as f:
        f.write(img)
    print(f"saved result.png ({len(img)} bytes)")

Considerações para produção

Use callback em vez de polling

Para qualquer cenário além de scripts únicos, registre um callback e pule o laço de polling. Adicione um objeto callback de nível superior (no mesmo nível de model e input):

{
  "model": "grok-imagine-quality/image-to-image",
  "input": { "...": "..." },
  "callback": {
    "url": "https://your-app.example.com/hooks/hiapi",
    "when": "final"
  }
}

when suporta apenas "final" — você recebe exatamente um POST quando a tarefa atinge um estado terminal (success ou fail). Regra de ouro:

  • Polling é bom para CLI, notebooks e jobs em lote, onde o processo já permanece vivo. Consulte a cada 3–5 segundos; não martele com intervalos de subsegundos.
  • Callback é melhor para backends web: sem conexões pendentes, sem threads de trabalho presas durante a geração. Rebusque GET /v1/tasks/<taskId> no servidor para validar o payload, em vez de confiar cegamente no corpo do webhook.

Idempotência

A criação de tarefa não é idempotente por si só — se seu processo falhar após POST /v1/tasks mas antes de persistir o taskId, uma nova tentativa criará (e cobrará) uma segunda tarefa. Persista o taskId no seu próprio armazenamento usando seu ID de job interno como chave antes de começar a esperar, e ao reiniciar recupere consultando o taskId armazenado em vez de recriar.

Tratamento de erros

Erros que você realmente encontrará:

  • 401 permission_denied — chave de API inválida ou sem acesso a este modelo. O corpo da resposta inclui um request_id que você pode enviar ao suporte:

    {
  "error": {
    "code": "permission_denied",
    "message": "This API key cannot use the selected model. ...",
    "request_id": "2026...",
    "type": "hiapi_error"
  }
}

  • 400 INVALID_REQUEST — violação de esquema, com mensagem precisa. Exemplos reais deste modelo:

    • prompt: missing required field "prompt" — você esqueceu um campo obrigatório.
    • image_urls: maxItems: got 12, want 3 — imagens de referência demais (máximo 3).
    • resolution: value must be one of '1k', '2k' — você enviou 1K/4K.
    • additional properties 'seed' not allowed — você passou um campo que este modelo não aceita.

  • Estado terminal fail — a tarefa foi aceita mas a geração falhou (por exemplo, a URL de origem não pôde ser buscada). Verifique data.error.message, corrija a entrada e crie uma nova tarefa.

Use retry com backoff para 5xx e erros de rede; não repita 400 — eles falharão da mesma forma até você corrigir o payload.

Escolhendo o nível de qualidade (e o que fazer com "consistência"?)

A família Grok Imagine na hiapi é dividida em IDs de modelo separados por nível e modalidade. Para imagem para imagem, você pode escolher:

O nível é o ID do modelo — não há parâmetro quality dentro de input (enviá-lo retorna 400 additional properties 'quality' not allowed). O preço por imagem de ambos os níveis está na página de preços.

Leitura relacionada

Perguntas frequentes

Existe parâmetro de consistência ou intensidade? Não. O esquema de entrada aceita apenas prompt, image_urls, aspect_ratio, resolution e output_format; qualquer outra coisa é rejeitada com 400. Para controlar o quanto a saída segue a imagem de origem, declare explicitamente no prompt o que deve ser preservado ("mantenha o produto e o rótulo exatamente iguais, mude apenas o fundo") e passe até 3 imagens de referência via image_urls.

Posso fazer upload de arquivos locais ou enviar base64? Não diretamente — image_urls aceita URLs, e a plataforma as busca no servidor. Faça upload do arquivo para qualquer armazenamento publicamente acessível (S3, R2, CDN) e passe essa URL.

Quantas imagens de origem posso passar? 1 a 3. Um array vazio falha com minItems: got 0, want 1; mais de 3 falha com maxItems.

Quais resoluções e proporções são suportadas? resolution é 1k ou 2k (somente minúsculo). aspect_ratio suporta 14 valores de 2:1 a 1:2, incluindo auto, 16:9, 1:1, 9:16 e as proporções para celular 9:19.5/9:20.

Quanto tempo dura a URL de saída? Cada saída traz um timestamp expireAt. Trate os resultados como efêmeros: baixe os bytes imediatamente após o sucesso da tarefa e armazene você mesmo.

Como gerar múltiplas variações? Não há parâmetro n — crie uma tarefa por variação. As tarefas rodam independentemente, então você pode enviar várias em paralelo.

Se minha chave está correta, o que significa 401 permission_denied? A chave existe mas não pode usar este modelo (plano ou escopo de permissão). Verifique as permissões de modelo da chave no painel ou entre em contato com o suporte usando o request_id no corpo do erro.

Etiquetasimagem-para-imagemTutorialAPI

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