Blogue

Tutorial

Como chamar minimax-h3-image de imagem para imagem com curl e Python no hiapi

Nov 13, 2026
Imagem de capa do blog hiapi.ai: composição geométrica abstrata de prismas em tom verde-pinheiro profundo, dividida em planos de cores lisas por linhas diagonais limpas
Nesta página

O que o endpoint de imagem-para-imagem espera

Antes de escrever qualquer código, ajuda entender a estrutura de uma chamada de imagem para imagem. O endpoint de imagem-para-imagem minimax-h3-image recebe sua imagem de referência (uma ou várias) e um prompt de texto, e retorna uma nova geração que segue o prompt enquanto permanece ancorada na referência.

Conceitualmente, cada requisição contém três partes:

  • Roteamento de modelo — você endereça minimax-h3-image com a tarefa image-to-image, tudo por meio de um único endpoint hiapi. Você não precisa de credenciais ou hosts separados para cada capacidade.
  • Entrada — uma string de prompt, uma ou mais imagens de referência (URL ou carga base64) e controles de geração como o nível de resolução.
  • Contrato de saída — a chamada é assíncrona. Você recebe um identificador de tarefa, então consulta o status e obtém a URL da imagem gerada quando a tarefa termina.

O último ponto é importante. Imagem para imagem não é uma chamada bloqueante que devolve os pixels na mesma resposta. Trate a chamada de submissão como "enfileirar um trabalho" e projete o cliente em torno do ciclo de vida da tarefa desde o início. Se você projetar para comportamento síncrono primeiro, terá que reescrever o código de integração depois.

Como tudo flui pela mesma interface hiapi, cabeçalhos, autenticação e envelope de resposta são consistentes entre modelos e tarefas. Aprenda uma vez para minimax-h3-image e o mesmo padrão se aplica em outros lugares da plataforma.

Uma requisição mínima executável

Comece com a menor requisição que prova que suas credenciais, endpoint e estrutura de payload estão corretos. Não corra para adicionar todos os campos opcionais de uma vez.

O corpo mínimo da requisição contém:

  • O nome do modelo minimax-h3-image
  • O tipo de tarefa image-to-image
  • Um prompt descrevendo que transformação você quer
  • Um único campo de imagem de referência
  • Um nível de resolução

Conceitualmente, o payload se parece com isto:

{
  "model": "minimax-h3-image",
  "task": "image-to-image",
  "input": {
    "prompt": "Transforme este esboço em uma renderização de produto limpa sobre fundo branco",
    "image": "https://example.com/reference.png",
    "resolution": "1024"
  }
}

Envie, confirme que um id de tarefa é retornado e então consulte manualmente uma ou duas vezes para observar as transições de estado. Se você tem um id de tarefa, conectividade e autenticação estão boas, e você pode passar a construir o cliente real. Se não, pare e leia o corpo do erro — ele geralmente aponta diretamente o campo problemático.

Salve esta requisição como teste de fumaça. Quando mudanças posteriores quebrarem seu pipeline, reexecutar esta requisição mínima dirá imediatamente se o problema está no seu payload ou no código ao redor.

Chamando com curl

curl é a maneira mais rápida de ver a requisição e a resposta brutas. Escreva o corpo JSON em um arquivo, assim você não precisa lutar com aspas do shell ao editar.

cat > payload.json <<'JSON'
{
  "model": "minimax-h3-image",
  "task": "image-to-image",
  "input": {
    "prompt": "Transforme esta foto em estilo de ilustração em aquarela",
    "image": "https://example.com/reference.png",
    "resolution": "1024"
  }
}
JSON

curl -sS -X POST "$HIAPI_BASE_URL/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  --data @payload.json

Dois cabeçalhos fazem o trabalho pesado: Authorization com o token bearer e Content-Type: application/json. Mantenha ambos longe do controle de versão — leia a chave de uma variável de ambiente em vez de colá-la no comando.

Em uma submissão bem-sucedida, capture o id de tarefa retornado e consulte-o:

curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

A resposta tem um campo de status e, quando concluída, um resultado. Use jq para extrair apenas os campos que importam:

curl -sS "$HIAPI_BASE_URL/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY" | jq '.status, .result'

Esta também é a maneira mais simples de depurar o payload: curl mostra exatamente o que você enviou e o que voltou, sem nada escondido por uma biblioteca cliente.

Chamando com Python

A versão em Python deve espelhar o fluxo do curl: submeter, capturar o id, consultar até o estado terminal, obter o resultado. Use requests e uma Session, assim reutilização de conexão e cabeçalhos padrão são tratados uma vez só.

import os
import time
import requests

BASE = os.environ["HIAPI_BASE_URL"]
KEY = os.environ["HIAPI_API_KEY"]
HEADERS = {
    "Authorization": f"Bearer {KEY}",
    "Content-Type": "application/json",
}

def submit(prompt: str, image: str, resolution: str = "1024") -> str:
    body = {
        "model": "minimax-h3-image",
        "task": "image-to-image",
        "input": {
            "prompt": prompt,
            "image": image,
            "resolution": resolution,
        },
    }
    resp = requests.post(f"{BASE}/v1/tasks", json=body, headers=HEADERS, timeout=30)
    resp.raise_for_status()
    return resp.json()["id"]

def poll(task_id: str, timeout: float = 300, interval: float = 2.0) -> dict:
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        resp = requests.get(f"{BASE}/v1/tasks/{task_id}", headers=HEADERS, timeout=30)
        resp.raise_for_status()
        data = resp.json()
        status = data.get("status")
        if status in ("succeeded", "failed"):
            return data
        time.sleep(interval)
    raise TimeoutError(f"A tarefa {task_id} não terminou em {timeout} segundos")

if __name__ == "__main__":
    task_id = submit(
        "Transforme esta imagem em um pôster vetorial plano",
        "https://example.com/reference.png",
    )
    print("Enviado:", task_id)
    result = poll(task_id)
    print(result)

Detalhes-chave: raise_for_status() transforma erros HTTP em exceções em vez de falhar silenciosamente; o laço de polling tem tanto um prazo final quanto um intervalo; o estado terminal é verificado explicitamente. Só extraia a URL da imagem do objeto de resultado depois que o status atingir o estado terminal, nunca antes.

Usando múltiplas imagens de referência

Uma única imagem de referência muitas vezes não basta. Você pode querer preservar o rosto de uma foto enquanto empresta a composição de outra, ou fundir uma textura e um contorno. O imagem-para-imagem do Minimax-h3-image suporta múltiplas entradas de referência por meio do campo plural de imagens.

Estruturalmente, o objeto input pode carregar uma única imagem de referência no campo image, e quando você tem várias, um array images:

{
  "model": "minimax-h3-image",
  "task": "image-to-image",
  "input": {
    "prompt": "Mantenha a pessoa da primeira imagem e use o estilo de fundo da segunda imagem",
    "images": [
      "https://example.com/person.png",
      "https://example.com/background.png"
    ],
    "resolution": "1024"
  }
}

A ordem importa. O índice de referência 0 é seu sujeito principal, e entradas posteriores são contexto auxiliar, então redija o prompt para corresponder à ordem em que você envia. Se o resultado ignorar uma imagem de referência, a causa usual é um prompt ambíguo, não um campo quebrado — deixe o prompt declarar explicitamente qual imagem decide qual atributo.

Regras práticas para trabalho com múltiplas referências:

  • Mantenha o número enxuto. Use apenas as imagens de referência que o prompt específico realmente precisa; adicionar extras dilui o controle.
  • Combine proporções de aspecto quando possível, para que o modelo não precise reconciliar composições conflitantes.
  • Use consistentemente URLs públicas ou base64 na mesma requisição, não misture métodos de transporte.

Envie uma requisição com duas imagens uma vez durante a integração para verificar que ambas as referências influenciam visivelmente a saída, depois construa lógica mais complexa sobre isso.

Escolhendo o nível de resolução

O campo resolution seleciona o nível de saída para imagem-para-imagem do minimax-h3-image. Não é apenas um botão estético — ele muda a quantidade de computação, a latência de resposta e o tamanho do payload que você eventualmente manipula.

Como ponderar:

  • Escolha o menor nível que atende ao cenário alvo. Miniaturas de exibição em lista não precisam do mesmo nível que um banner principal. Reduzir a resolução de saídas em alta resolução depois desperdiça tempo e dinheiro.
  • Espere que a latência cresça com a resolução. Níveis mais altos fazem mais trabalho por requisição, então seu orçamento de timeout e intervalo de polling deve refletir o nível escolhido.
  • Observe o tamanho do payload. Entradas de referência em base64 e saídas em alta resolução aumentam o volume de transferência; se você estiver movendo muitas imagens, fique de olho nos corpos de requisição e resposta.

O faturamento segue o nível de resolução que você solicita — as requisições são cobradas pelo nível em que rodam, então usar um nível grande demais para casos pequenos custa dinheiro silenciosamente. Consulte as tarifas atuais no painel de preços em vez de codificar suposições.

Uma estratégia de integração sensata: use um nível intermediário durante o desenvolvimento para ganhar velocidade, e promova os ativos críticos para um nível mais alto depois que os prompts e o conjunto de referências estiverem definidos. Mudar a resolução mais tarde invalida suas medições de latência, então faça benchmarks no nível em que você realmente pretende lançar.

Lidando com o ciclo de vida assíncrono

Toda chamada de imagem-para-imagem no hiapi segue o mesmo ciclo: submeter, capturar o id da tarefa, consultar até o estado terminal, então obter o resultado. Tornar este ciclo robusto é a maior parte do trabalho de um cliente de produção.

Submeta e registre

Trate o id da tarefa como seu identificador persistente. Registre-o assim que a resposta de submissão chegar, antes de qualquer outra coisa — se o processo travar no meio do polling, este id permite retomar em vez de gerar de novo.

Consulte com backoff

Polling fixo de dois segundos é adequado para uso interativo, mas desperdício para lotes longos. Comece com um intervalo curto e aumente gradualmente, com um teto para o intervalo máximo, para que você ainda detecte a conclusão em tempo hábil.

def next_interval(current: float, cap: float = 15.0, factor: float = 1.5) -> float:
    return min(current * factor, cap)

Respeite os estados terminais

Só saia do laço no sucesso ou na falha. Tratar qualquer resposta não vazia como "concluída" é o bug assíncrono mais comum — você acabará lendo um resultado que ainda não existe.

Defina limites para tudo

Defina timeouts para cada chamada HTTP e um prazo final geral para a tarefa. Se o prazo passar, lance um erro claro em vez de girar indefinidamente. Para erros de rede transitórios, tente novamente o polling com backoff; não resubmeta cegamente, isso causa trabalho duplicado.

Limpeza

Uma vez obtido o resultado, persista a URL da imagem ou os bytes no seu próprio armazenamento prontamente. Resultados de tarefa são identificadores temporários, não o CDN de longo prazo da sua aplicação.

Solução de problemas e checklist de produção

Estas são as falhas que os desenvolvedores encontram primeiro ao usar imagem-para-imagem do minimax-h3-image, e as verificações que as previnem.

Falhas na primeira execução

  • 401 / 403 — token bearer ausente, expirado ou com espaços em branco à esquerda ou à direita. Confirme que a variável de ambiente está exportada no shell que executa a requisição.
  • 422 ou erro de validação — verifique o corpo do erro; ele geralmente aponta o campo. Uma causa comum é colocar prompt no nível superior em vez de dentro de input.
  • JSON malformado — valide seu arquivo de payload com jq . antes de enviar.

Falhas em tempo de execução

  • A tarefa nunca termina — confirme que você está consultando o id que realmente recebeu, não um placeholder. Verifique se seu prazo final é longo o bastante para o nível de resolução escolhido.
  • Resultado vazio para uma tarefa "concluída" — leia o campo de status com precisão; estados de falha também retornam um corpo de resposta.
  • Imagem de referência ignorada — antes de culpar o modelo, reveja a redação do prompt e a ordem das imagens de referência.

Checklist antes do lançamento

  • Chave de API e URL base lidas de variáveis de ambiente, nunca commitadas no repositório.
  • Toda chamada HTTP tem timeout explícito.
  • O polling usa backoff limitado, com um prazo final geral rígido.
  • Estados terminais são tratados explicitamente; nenhum caminho cai na análise de resultado.
  • Resultados são baixados e armazenados pela sua aplicação, não hotlinkados da resposta da tarefa.
  • Prompts com múltiplas referências declaram qual imagem controla qual atributo.
  • O nível de resolução foi testado nos valores em que você pretende lançar.
  • Os logs registram o id da tarefa para que trabalhos com falha possam ser rastreados e retomados.

Sempre que algo der errado, reexecutar aquela requisição mínima anterior — ela isola se o problema está no seu payload ou no código ao redor. Com a estrutura da requisição, clientes curl e Python, tratamento de múltiplas referências e um laço de polling disciplinado, você tem tudo o que precisa para lançar com confiança o imagem-para-imagem do minimax-h3-image no hiapi.

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