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
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
Authorizationcarrega 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 campoimageaponta para sua imagem de origem epromptdescreve 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 →-
Tutorial
Guia prático do gpt-6.2-sol: 5 usos de alto valor de modelos de texto nos negócios
-
Tutorial
Guia prático do gpt-6.2-astra: pontos de integração e implementação em 5 cenários de texto de alto valor
Uma lista de verificação do ponto de vista do desenvolvedor, da seleção de cenários à implementação em engenharia
-
Tutorial
Cenários práticos do Tripo H3.1: 5 usos de alto valor e pontos de implementação
De texto para 3D à reconstrução multivisão: escolha o modo e os parâmetros certos para cada cenário de negócio