Como chamar grok-imagine/image-to-image via API da HiAPI: guia com curl e Python

O que grok-imagine/image-to-image oferece aos desenvolvedores

grok-imagine/image-to-image é um endpoint de transformação de imagens: você fornece uma imagem de referência e um prompt, e ele retorna uma nova imagem que segue o prompt mantendo ao mesmo tempo uma ligação visual com a imagem de referência. Pense nisso como geração guiada, não como geração do zero. O id do modelo que você chama na HiAPI é grok-imagine/image-to-image, e o restante da requisição serve para descrever as mudanças que você deseja.

Sempre que a saída precisar preservar algo do material existente — uma foto de produto cujo fundo precisa ser trocado, um esboço de personagem que precisa ser renderizado, uma composição que precisa de uma mudança de estilo —, escolha este endpoint em vez de uma chamada de texto para imagem. Texto para imagem serve para quando você não tem imagem-fonte e só tem uma descrição; image-to-image serve para quando a imagem-fonte em si faz parte da especificação.

Como a HiAPI expõe isso como uma única interface unificada, seu trabalho de integração se resume a montar uma só estrutura de requisição e tratar uma só estrutura de resposta. Você não precisa de um SDK separado para cada família de modelos nem reaprender a autenticação para cada endpoint.

Anatomia da requisição: modelo, imagem de referência e prompt

Toda chamada válida tem quatro partes conceituais. Acertar cada uma antes de escrever código economiza a maior parte do trabalho de depuração depois.

Id do modelo

O campo model carrega a string grok-imagine/image-to-image. Trate-o como uma constante no seu cliente, não como um literal espalhado pelo código — se um dia você quiser experimentar outros modelos da HiAPI, vai querer ter um único lugar para alterar.

Imagem de referência

A imagem de referência é a âncora. Como fornecê-la depende do transporte escolhido: pode ser uma URL que a API consiga buscar ou dados base64 embutidos, útil para imagens geradas na hora ou que não têm acesso público. Prefira URL para material que você já hospeda; prefira dados embutidos para uploads de usuários que ainda não foram persistidos em nenhum local público. Em qualquer transporte, valide a imagem antes de enviar: formato suportado, tamanho não nulo e dimensões suficientemente significativas.

Prompt

O prompt descreve a transformação, não a cena inteira. Se a imagem de referência já contém o sujeito, descreva o que deve mudar — estilo, iluminação, fundo, material — e deixe o que não muda subentendido. Especificar demais o que já está visível na imagem de referência costuma conflitar com o condicionamento da imagem em vez de ajudar.

Tratamento da proporção

A parte restante é como o tamanho da saída é determinado, tema da próxima seção. Separe essas quatro partes no código que monta a requisição, para que cada uma possa ser validada e registrada de forma independente.

Usando a opção auto aspect

A opção auto aspect faz a API escolher o tamanho da saída por você, em vez de você fixar largura e altura explícitas. Quando ativada, o serviço deduz uma proporção adequada a partir do contexto da requisição — principalmente da imagem de referência —, fazendo a forma da saída ficar mais coerente com a sua entrada em vez de ser forçada a um enquadramento padrão.

Isso é mais importante do que parece. Se você fixar um tamanho que não bate com a proporção da imagem de referência, obtém artefatos parecidos com letterbox, cortes estranhos do sujeito ou uma composição que ignora o enquadramento da imagem-fonte. O auto aspect evita esse tipo de descompasso deixando a geometria seguir a entrada.

Quando manter o auto ativado

• A imagem de referência vem de usuários, com formas variadas.
• Você está prototipando e ainda não sabe qual tamanho serve ao caso de uso.
• A saída entra em um pipeline que de qualquer forma vai cortar ou redimensionar.

Quando fixar o tamanho explicitamente

• Você tem um slot fixo na UI ou em um destino de impressão e precisa de geometria de saída exata.
• Você está gerando um lote de imagens que devem ficar visualmente consistentes em tamanho.

Uma prática útil: manter auto aspect ativado durante o desenvolvimento, verificar os tamanhos que a API retorna para entradas reais e só então decidir se fixa o tamanho para produção. Registre os metadados da imagem retornada junto com a requisição, para que essa decisão se baseie em evidências e não em suposições.

Requisição curl pronta para uso

A requisição abaixo está completa exceto pelos espaços reservados, indicados entre colchetes angulares. Substitua pelos seus valores e ela poderá ser executada diretamente.

curl -X POST "https://api.hiapi.ai/v1/images/generations" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-imagine/image-to-image",
    "prompt": "<descreva a transformação desejada>",
    "image": "<URL publicamente acessível da sua imagem de referência>",
    "aspect_ratio": "auto"
  }'

Espaços reservados a substituir

• $HIAPI_API_KEY —— leia sua chave de uma variável de ambiente em vez de colá-la no comando. Se a variável não estiver definida, a requisição falha com erro de autenticação e a chave nunca vai parar no histórico do seu shell.
• <descreva a transformação desejada> —— uma instrução breve e específica, como mudança de estilo ou de fundo.
• <URL publicamente acessível da sua imagem de referência> —— uma URL que o serviço consiga buscar sem autenticação. Se o seu material for privado, use dados base64 embutidos.

Lendo a resposta

Na primeira execução, passe a saída por um formatador JSON para ver a estrutura da resposta com clareza. Fique atento a duas coisas: o conteúdo da imagem (que pode ser uma URL ou dados codificados, dependendo do modo de resposta) e o identificador da tarefa quando a chamada é tratada de forma assíncrona. Durante o desenvolvimento, guarde a resposta bruta completa nos logs — quando algo parecer errado, essa é a forma mais rápida de responder "o que foi realmente retornado".

A mesma requisição em Python

A versão em Python deve corresponder campo a campo à requisição curl. O valor de mantê-las alinhadas é que um bug reproduzido em uma versão pode ser confirmado na outra, sem adivinhação de tradução.

import os
import requests

API_URL = "https://api.hiapi.ai/v1/images/generations"
MODEL = "grok-imagine/image-to-image"

def generate_from_reference(prompt: str, image_url: str) -> dict:
    payload = {
        "model": MODEL,
        "prompt": prompt,
        "image": image_url,
        "aspect_ratio": "auto",
    }
    response = requests.post(
        API_URL,
        headers={
            "Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}",
            "Content-Type": "application/json",
        },
        json=payload,
        timeout=120,
    )
    response.raise_for_status()
    return response.json()

Onde colocar o tratamento de erros

Envolva a chamada, não o chamador. response.raise_for_status() converte respostas não 2xx em exceções, então um único try/except em torno de generate_from_reference cobre tanto falhas de transporte quanto rejeições da API. Se você quiser registrar de forma estruturada o motivo da falha, inspecione response.status_code e o corpo do erro dentro da função antes de lançar a exceção.

Mantenha o cliente enxuto

Leia a chave da API uma vez na inicialização, defina timeouts explícitos e retorne o JSON já analisado em vez do objeto de resposta bruto. O chamador não deveria precisar conhecer detalhes de HTTP. Nos testes, aponte API_URL para um servidor stub, assim você valida a lógica de montagem da requisição sem gastar chamadas reais de geração.

Respostas síncronas e assíncronas

Algumas requisições de image-to-image terminam rápido o bastante para retornar o resultado na mesma resposta HTTP. Outras são tratadas como jobs: a chamada inicial retorna um identificador e a imagem fica disponível mais tarde. Seu cliente não deve assumir nenhum dos dois.

Como distinguir os dois

Verifique o corpo da resposta após cada chamada. Se ele contém diretamente o conteúdo da imagem, você está no caminho síncrono — extraia e retorne. Se contém um identificador de job ou tarefa, você está no caminho assíncrono e precisa consultar até o job atingir um estado terminal.

Estruture o código para os dois

Uma pequena função de despacho mantém os dois caminhos fora da lógica de negócio:

def resolve_result(response_json: dict) -> dict:
    if "image" in response_json or "data" in response_json:
        return response_json
    job_id = response_json.get("id") or response_json.get("job_id")
    if job_id:
        return poll_until_done(job_id)
    raise RuntimeError(f"Unrecognized response shape: {response_json}")

Regras de polling que evitam problemas

• Use backoff exponencial com limite superior, em vez de um loop apertado.
• Defina um tempo máximo total de espera e falhe de forma limpa ao ultrapassá-lo.
• Trate todo estado não terminal como "continue esperando"; apenas dois estados são finais: sucesso e falha.
• Registre o id do job a cada polling, para que um job travado possa ser rastreado só pelos logs.

A abordagem de despacho significa que, ao alternar entre comportamento síncrono e assíncrono, o código que chama resolve_result nunca precisa mudar.

Depurando códigos de erro comuns

A maioria das chamadas que falham neste endpoint se enquadra em poucas categorias. Percorra a lista abaixo em ordem — ela vai da causa mais comum à mais rara.

Falhas de autenticação

Se a resposta indicar um problema de autenticação, a chave está ausente, malformada ou não foi enviada. Verifique se a variável de ambiente está realmente preenchida no processo que faz a chamada e se o cabeçalho é exatamente Authorization: Bearer <key>. Uma chave que funciona no seu shell mas não no serviço geralmente significa que o ambiente do serviço é diferente do ambiente do seu shell.

Erros de validação da imagem de referência

Rejeições relacionadas à imagem geralmente significam uma entre quatro coisas: a URL não é acessível publicamente, o formato não é suportado, o conteúdo é grande demais ou a imagem é pequena ou está corrompida. Teste a URL no navegador sem credenciais — se ela não carregar ali, a API também não conseguirá buscá-la. Para base64 embutido, confirme que a codificação é base64 puro e sem prefixo data-URL (a menos que o parâmetro espere isso).

Erros de prompt e de parâmetros

Um prompt vazio ou grande demais, ou um valor de parâmetro desconhecido, gera uma resposta de validação. Registre o conteúdo exato enviado junto com o erro — boa parte das falhas é erro de digitação no nome do campo, não no valor.

Limite de taxa

Uma resposta de limite de taxa significa recuar, não tentar novamente na hora. Siga a orientação de retry dos cabeçalhos da resposta, adicione jitter e limite o número de tentativas. Retentar sem backoff transforma um limite temporário em um limite contínuo.

Erros do lado do servidor

Respostas 5xx são do lado do serviço. Tente novamente um número limitado de vezes com backoff; se persistir, capture o id da requisição e o timestamp da resposta e reduza a concorrência durante a investigação.

Checklist de produção antes do lançamento

Uma requisição que funciona é o começo, não o fim. Antes de este endpoint receber tráfego real, confirme os itens abaixo.

Valide as entradas na fronteira

Antes de a requisição sair do seu serviço, verifique formato e tamanho da imagem de referência, comprimento do prompt e valores dos parâmetros. Rejeitar entradas ruins localmente é mais rápido e barato do que uma ida e volta, e gera mensagens de erro mais claras para o usuário.

Só retente requisições que podem ser retentadas com segurança

Use backoff exponencial com jitter para falhas de transporte, limites de taxa e respostas 5xx. Não retente erros de validação ou autenticação — eles vão falhar do mesmo jeito e apenas aumentarão a carga.

Registre o suficiente para reconstruir uma falha

Registre o id do modelo, um hash ou forma truncada do prompt, o identificador da imagem de referência (não o conteúdo completo), o status da resposta, o id do job (se houver) e o id da requisição. Esse conjunto costuma bastar para responder "o que aconteceu" sem armazenar conteúdo sensível.

Mantenha as chaves fora do código

Leia a chave da API de variáveis de ambiente ou de um gerenciador de segredos, nunca de um literal no código-fonte. Rotacione as chaves periodicamente e revogue imediatamente se houver suspeita de vazamento.

Acompanhe o comportamento de custo

A cobrança deste endpoint é movida pela geração, então as alavancas principais são volume de requisições, retentativas e frequência de polling. Evite tempestades de retentativa, aplique backoff no polling e armazene em cache resultados para a mesma transformação pedida repetidamente, por prompt e imagem de referência. Consulte o painel de preços da HiAPI para ver as tarifas atuais em vez de fixar suposições no código.

Teste os caminhos infelizes

Escreva testes para URL de imagem inválida, resposta de limite de taxa e job assíncrono que nunca termina. Esses três cobrem as falhas mais propensas a chegar à produção sem ser notadas.

Com montagem de requisição, despacho de resposta e tratamento de erros prontos, grok-imagine/image-to-image passa a ser uma parte rotineira do seu pipeline, e não um caso especial.