Blogue

Tutorial

Como chamar qwen-image-3.0-pro/image-to-image pela API do HiAPI: curl, Python e uma requisição funcional

Um roteiro de integração que cobre o padrão de tarefas assíncronas, clientes curl e Python, e tratamento de erros

Nov 10, 2026
Imagem de capa: folhas de papel empilhadas de forma desalinhada, como uma impressão com desregistro de cores, superfície em branco-creme com bordas em preto-carvão e uma folha inserida em vermelho-ferrugem, com uma sombra projetada reta no canto inferior direito.
Nesta página

Por que a geração de imagem a partir de imagem (image-to-image) é uma tarefa assíncrona

Quando você chama um modelo de geração de imagem a partir de imagem, não está pedindo uma conclusão de texto que retorna em streaming em algumas centenas de milissegundos. O modelo precisa carregar sua imagem de origem, executar o pipeline completo de geração difusa condicionado por ela e codificar a saída. Isso pode levar de alguns segundos a dezenas de segundos, e a duração varia com a resolução e as configurações. Manter uma conexão HTTP aberta durante toda essa janela não compensa para nenhuma das partes: proxies expiram, balanceadores de carga descartam sockets ociosos e suas próprias threads de trabalho ficam presas a uma requisição que talvez ainda falhe mais tarde.

Por isso o endpoint adota o modelo de "enviar primeiro, consultar depois". Sua primeira requisição envia uma tarefa e retorna imediatamente um identificador de tarefa. A geração da imagem ocorre por trás desse identificador. Em seguida, você faz requisições independentes e leves para verificar o status da tarefa até que ela informe conclusão, momento em que a resposta carrega o resultado solicitado.

Isso tem consequências práticas que você deve incorporar ao design desde o início:

  • Enviar não é concluir. Uma chamada de envio bem-sucedida significa apenas que a plataforma aceitou sua tarefa, nada mais. No código, trate esses dois estados de forma distinta.
  • O ID da tarefa é seu único identificador. Persista-o. Se seu processo travar entre o envio e a consulta, o ID da tarefa é a base para retomar sem reenviar (e pagar novamente) o mesmo trabalho.
  • A consulta é leve, mas não gratuita. As verificações de status são leves, mas um loop apertado ainda gera tráfego e pode acionar limites de taxa. Espaçe as consultas.
  • Falhas chegam de forma assíncrona. Uma imagem corrompida ou parâmetros rejeitados podem aparecer como erro no nível da tarefa, e não como erro HTTP no envio. Seu código de polling precisa ler o status da tarefa, não apenas o código de status.

Com esse modelo em mente, a integração fica direta: uma chamada cria o trabalho, um loop espera por ele e há um tratamento deliberado para os três casos que podem dar errado.

Antes de escrever código: o que você precisa ter

Antes de abrir o terminal, reúna algumas coisas das quais cada chamada deste guia depende.

Credenciais do HiAPI

Você precisa de uma chave de API do HiAPI. Trate-a como segredo: carregue-a de uma variável de ambiente, em vez de colá-la em um script que você pode acabar commitando. Os exemplos abaixo a leem como HIAPI_API_KEY. A URL base da API e o identificador exato do modelo qwen-image-3.0-pro/image-to-image são as duas constantes que você vai referenciar o tempo todo.

Uma imagem de origem

A geração a partir de imagem precisa de uma entrada. Tenha uma pronta e decida como fornecê-la:

  • como uma URL publicamente acessível, ou
  • como um ativo já enviado ou um payload codificado, dependendo da forma que o endpoint aceita.

Antes de escrever a chamada, consulte o schema de requisição do modelo para confirmar o nome exato do campo e os formatos de imagem de origem aceitos. Fornecer uma imagem de origem que o endpoint não aceita é a causa mais comum de rejeição de tarefas, e evitá-la de antemão é muito mais fácil do que depurá-la a partir de uma mensagem de erro.

Um cliente capaz de consultar

Como a chamada é assíncrona, a ferramenta que você usa para enviar requisições também precisa conseguir disparar requisições subsequentes repetidamente. O curl é bom para o primeiro teste rápido; qualquer uso mais duradouro deve ser um script. Não há URL de callback para configurar nem webhook para hospedar — a consulta é o mecanismo, então planeje um loop.

Um lugar para ver o resultado

Decida de antemão como é "concluído" para você: uma URL que você abre no navegador ou os bytes que você grava em disco. Saber isso antes de começar torna óbvio, de imediato, quando a integração está realmente funcionando.

Com essas quatro coisas em mãos, a primeira requisição fica curta.

Enviar uma requisição funcional com curl

A forma mais rápida de confirmar que sua chave, o endpoint e o ciclo de vida da tarefa funcionam é uma sessão curl em duas etapas. Primeiro envie; depois consulte.

Etapa 1: enviar a tarefa

curl -sS -X POST "$HIAPI_BASE_URL/qwen-image-3.0-pro/image-to-image" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "https://example.com/source.jpg",
    "prompt": "restyle as a soft watercolor illustration"
  }'

Item a item:

  • -X POST — o envio é uma operação de criação.
  • O cabeçalho Authorization carrega sua chave. Exportar a variável de ambiente em vez de digitá-la inline evita que ela fique no histórico do shell.
  • Content-Type: application/json — o corpo da requisição é JSON.
  • -d — o payload JSON. O campo image aponta para sua imagem de origem e prompt descreve a transformação a aplicar. Os nomes dos parâmetros e as opções aceitas vêm do schema de requisição do modelo; verifique lá em vez de adivinhar.

A resposta de um envio bem-sucedido é um objeto de tarefa. Ele contém um identificador — chame-o de ID da tarefa — e um campo de status, que deve indicar que a tarefa foi enfileirada ou está em execução. Anote o ID da tarefa; tudo o que vem depois depende dele.

Etapa 2: consultar a tarefa

export TASK_ID="<the id from the submit response>"

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

A cada chamada, leia o campo de status. Quando ele indicar pendente ou em execução, espere alguns segundos e verifique de novo. Quando indicar sucesso, a resposta contém a imagem gerada — normalmente uma URL acessível ou dados codificados. Quando indicar falha, a resposta traz uma descrição do erro explicando o motivo.

O ciclo de vida inteiro é isso: um envio e depois verificações de status até o estado terminal. Qualquer coisa que você construa depois é apenas uma versão mais conveniente desses dois comandos, com espera e tratamento de erros.

Implementar a mesma chamada em Python

Repetir essas duas etapas de curl manualmente cansa rápido, e copiar e colar o loop de polling em cada script é exatamente como bugs sutis se espalham. Empacote o padrão de envio e consulta em uma função reutilizável.

import os
import time
import requests

BASE_URL = os.environ["HIAPI_BASE_URL"]
API_KEY = os.environ["HIAPI_API_KEY"]
MODEL_PATH = "/qwen-image-3.0-pro/image-to-image"
HEADERS = {"Authorization": f"Bearer {API_KEY}"}


def submit_task(source_image: str, prompt: str) -> str:
    resp = requests.post(
        BASE_URL + MODEL_PATH,
        headers={**HEADERS, "Content-Type": "application/json"},
        json={"image": source_image, "prompt": prompt},
        timeout=30,
    )
    resp.raise_for_status()
    return resp.json()["id"]


def wait_for_task(task_id: str, poll_interval: float = 3.0,
                  max_wait: float = 300.0) -> dict:
    deadline = time.monotonic() + max_wait
    while time.monotonic() < deadline:
        resp = requests.get(
            f"{BASE_URL}/tasks/{task_id}",
            headers=HEADERS,
            timeout=30,
        )
        resp.raise_for_status()
        task = resp.json()
        status = task["status"]
        if status == "succeeded":
            return task
        if status == "failed":
            raise RuntimeError(f"task {task_id} failed: {task.get('error')}")
        time.sleep(poll_interval)
    raise TimeoutError(f"task {task_id} did not finish within {max_wait}s")


def generate(source_image: str, prompt: str) -> dict:
    task_id = submit_task(source_image, prompt)
    return wait_for_task(task_id)

Há algumas escolhas deliberadas que vale destacar:

  • Separar envio e espera. Se o envio falhar, você sabe antes de qualquer consulta acontecer. Se mais tarde você quiser enviar em um processo e coletar em outro, a costura já existe.
  • Cada requisição tem timeout. Uma requisição sem timeout pode travar indefinidamente, que é justamente o modo de falha que uma API assíncrona deveria ajudar você a evitar.
  • O loop de polling tem intervalo e prazo total. Sem prazo, uma tarefa presa em execução entra em loop para sempre. Sem intervalo, você bombardeia o endpoint.
  • As strings de status são comparadas de forma explícita. Qualquer status que não seja sucesso nem falha cai na próxima iteração, o que é o comportamento padrão correto para estados intermediários.

Chame como qualquer função: generate(source_url, "make the background a dusk cityscape"). O objeto retornado é o payload da tarefa em estado terminal; extraia dele a referência da imagem.

Tratar erros e tarefas com falha

Os erros em fluxos de trabalho assíncronos se dividem em três categorias, e cada uma exige uma resposta diferente.

Rejeições no nível da requisição

São as respostas HTTP de erro comuns da chamada de envio — credenciais incorretas ou ausentes, JSON malformado, parâmetros não suportados, imagem de origem inacessível. Elas chegam antes de qualquer tarefa existir.

A resposta correta quase sempre é parar e apresentar a mensagem. Repetir um payload malformado só desperdiça cota e tempo. Registre o código de status e o corpo da resposta literalmente; a mensagem de validação geralmente aponta o campo problemático. Dois casos merecem tratamento especial: falhas de autenticação devem falhar rápido e alto, porque indicam um problema de configuração; respostas de limite de taxa podem ser repetidas após um backoff.

Falhas no nível da tarefa

Aqui o envio teve sucesso, o ID da tarefa existe, mas o trabalho falhou. A resposta da consulta informa o estado de falha com um erro.

Essa categoria cobre problemas do próprio modelo: imagem de origem que decodifica mas não é utilizável, prompt rejeitado, geração atingindo um limite interno. Como esses problemas estão especificamente ligados à entrada, repetir cegamente tende a reproduzir a mesma falha. Decida caso a caso: um erro interno temporário pode valer uma nova tentativa; uma imagem de origem rejeitada nunca vale. Registre o ID da tarefa junto com o erro para poder correlacioná-lo a uma solicitação de suporte.

Consultas que nunca terminam

O envio teve sucesso, a tarefa existe, a consulta está em execução — mas o estado terminal nunca chega. Isso não é um erro retornado pela plataforma; é uma premissa no seu código que precisa expirar.

Proteja-a com um prazo, como mostra o exemplo em Python. Quando o prazo dispara, pare de consultar. Não retorne silenciosamente um resultado pela metade; lance ou retorne um resultado explícito de timeout para que o chamador decida. Preserve o ID da tarefa — a tarefa pode até concluir depois do seu prazo, e você pode querer coletá-la mais tarde sem reenviar.

Regra prática para as três categorias: trate o status da tarefa como a única fonte de verdade. O código de status HTTP diz se a requisição foi aceita; os campos de status e erro da tarefa dizem se o trabalho teve êxito. Leia ambos, e as falhas se tornam diagnosticáveis em vez de misteriosas.

Preparar o código para produção

A função acima é uma integração funcional, não um serviço completo. Antes de ela lidar com tráfego real, reforce quatro pontos.

Timeouts em toda parte

Defina timeouts explícitos de conexão e leitura para cada chamada — envio, consulta e qualquer busca subsequente da imagem resultante. Depois, defina um prazo total para todo o ciclo de vida da tarefa. O timeout na camada HTTP protege uma requisição individual; o prazo da tarefa protege a operação inteira.

Retentativas com critério

Só repita o que é seguro repetir. Limites de taxa durante a consulta e erros de rede temporários se qualificam. Payloads rejeitados não. Para falhas no nível da tarefa, repetir significa enviar uma nova tarefa, o que é uma operação diferente e mais cara do que repetir uma verificação de status — trate isso como uma decisão deliberada, de preferência com limite.

Logs que incluem o ID da tarefa

Registre o ID da tarefa no envio e em cada transição de status subsequente, junto com informações de tempo. O intervalo entre o envio e o primeiro estado terminal é a métrica que você vai realmente querer quando as coisas parecerem lentas. Quando um usuário relatar um resultado ruim, o ID da tarefa é a chave para transformar um relato vago em um registro rastreável.

Manter o polling fora do caminho da requisição

Se sua função roda dentro de um handler web, um loop de polling síncrono mantém a requisição aberta durante todo o tempo de geração — exatamente o problema que o design assíncrono busca evitar. Em vez disso, envie no handler, retorne o ID da tarefa ao chamador e execute a espera em um worker em segundo plano, em uma fila ou em uma tarefa agendada. Então o cliente consulta o seu serviço, não o modelo.

Construído nessa ordem, a integração deixa de ser "funciona na minha máquina" e passa a ser algo com que você pode contar: envie, persista o identificador, espere com limites e deixe o status da tarefa — e não a esperança — dizer quando parar.

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