Integração à API Google Virtual Try-On: imagem da pessoa e imagem da roupa

Colocar cada uma das duas imagens no campo correto já dá um ponto de partida claro para a integração. A foto da pessoa vai em person_image_url e a imagem da roupa vai em product_image_url; colocar a foto da pessoa no campo da roupa altera o significado da entrada da tarefa.

TL;DR

Google Virtual Try-On custa $0.1075 por imagem; veja preço e orçamento. Use a interface HiAPI /v1/tasks: envie a tarefa e obtenha o taskId, depois consulte o resultado. Não é necessário prompt.

Preparação da entrada e campos

Escolha uma foto frontal de uma única pessoa, com o contorno do corpo o mais nítido possível; para a roupa, use uma imagem de produto plano ou pendurada, com fundo limpo e bordas completas. Os dois endereços permanentes de imagem no exemplo abaixo correspondem à pessoa A e à camiseta listrada em vermelho e branco e podem ser substituídos pelos seus próprios endereços públicos de imagem.

Campo	Como preencher
person_image_url	Obrigatório; URL HTTP(S) público da foto da pessoa
product_image_url	Obrigatório; URL HTTP(S) público da imagem do produto de vestuário
num_images	Inteiro; preencha explicitamente 1, atualmente apenas uma imagem é suportada

Mapear combinações de negócio para a requisição

Para experimentar roupas diferentes na mesma pessoa, mantenha person_image_url fixo e substitua product_image_url peça por peça; para mostrar a mesma roupa em pessoas diferentes, mantenha a imagem do produto fixa e substitua a imagem da pessoa. Para várias alternativas com o mesmo conjunto de imagens, mantenha as duas entradas e envie requisições separadas, sempre preenchendo num_images: 1. Recomenda-se guardar nos registros de tarefas o código do produto e a versão da imagem da pessoa; não tente adivinhar a correspondência apenas pelo nome do arquivo de resultado.

Tanto a pessoa quanto a roupa devem ter endereços HTTP(S) de imagem acessíveis publicamente; não são aceitos caminhos de disco local nem data URI como URL de imagem. O fato de você ver a imagem no navegador com sessão iniciada não significa que outros serviços consigam acessá-la; antes de enviar, verifique o link sem depender de sessão autenticada. Recomenda-se confirmar que o retorno é a própria imagem, e não uma página de álbum ou de aviso de permissão, e manter a imagem acessível durante a leitura da tarefa.

Se a foto da pessoa cobrir a barra da camisa ou se as mãos se sobrepuserem muito à roupa, considere primeiro trocar por uma foto com limites mais claros. Para a imagem da roupa, prefira uma peça única, com bordas completas, em foto plana ou pendurada, evitando usar novamente um resultado de composição em pessoa como se fosse uma imagem de produto independente. Os campos públicos não oferecem proteção local, ajuste de punho ou trava de sapatos, e não é possível expressar essas exigências adicionando campos personalizados.

Escolher imagens nítidas é um método de trabalho; aceitar ou não a imagem pela interface e a precisão da representação do produto devem ser verificadas separadamente. Este artigo não adiciona promessas de tamanho de arquivo, limite de pixels ou dimensões de saída sem evidência para o Try-On; também não se devem aplicar diretamente a ele limites de entrada de outros modelos de imagem.

Enviar tarefa: cURL

Segue um exemplo em Bash/cURL. Primeiro configure HIAPI_API_KEY no ambiente de execução; as URLs de imagem na requisição podem ser substituídas, mantendo a chave no ambiente do servidor.

curl -X POST "https://api.hiapi.ai/v1/tasks" \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "google-virtual-try-on",
  "input": {
    "person_image_url": "https://static.hiapi.ai/gallery/2026/10/9f656c8b6ecf94d5.webp",
    "product_image_url": "https://static.hiapi.ai/model-covers/2026/10/22/1792660602486-b5b70d2cfdd8dc95-1792152569828-b5b70d2cfdd8dc95-t-g1-0.webp",
    "num_images": 1
  }
}'

Um envio bem-sucedido retorna data.taskId. Guarde esse valor para consultas posteriores.

Consultar tarefa e salvar resultado

Coloque o número da tarefa em TASK_ID e consulte:

curl "https://api.hiapi.ai/v1/tasks/$TASK_ID" \
  -H "Authorization: Bearer $HIAPI_API_KEY"

Quando a tarefa tiver data.status=success, obtenha a imagem em data.output[0].url e salve. Para operações contínuas, é possível definir no nível superior da requisição de envio callback.url e callback.when: "final" para receber notificações de conclusão e deduplicar por taskId; notificações podem ser disparadas tanto em caso de sucesso quanto de falha. A consulta é adequada para depuração e verificações complementares.

Polling, callback e tratamento de timeout

Enviar e consultar são duas coisas distintas. Depois de obter data.taskId, registre-o junto com as entradas desta execução e consulte GET /v1/tasks/:id. Se ainda não atingiu o estado final, continue aguardando; não substitua a consulta por um novo POST. O intervalo de polling e o limite de espera do negócio ficam a cargo da sua aplicação; este artigo não tem base para prometer tempo médio ou prazo fixo de conclusão; o timeout de rede do exemplo também não constitui garantia de duração do serviço.

Um timeout na requisição de consulta indica apenas que essa leitura não foi concluída a tempo. Mantenha o número da tarefa e consulte novamente a mesma tarefa mais tarde. Se o envio em si der timeout e não retornar o número, há incerteza sobre se o servidor já aceitou a tarefa: guarde o horário e o conteúdo da requisição, verifique primeiro os registros de tarefas e só então decida se deve reenviar. Não interprete uma exceção do cliente diretamente como falha da tarefa nem prometa que requisições repetidas serão mescladas automaticamente.

A configuração de callback vai no nível superior do corpo da requisição, no mesmo nível de model e input, e não pode ser colocada dentro da entrada do modelo. Ao configurar callback.url, use também callback.when: "final". A notificação de conclusão pode corresponder a sucesso ou a falha, portanto ainda é preciso verificar o status ao recebê-la. Consulta e callback podem tratar a mesma tarefa; o lado do negócio deve deduplicar por taskId para evitar downloads repetidos ou disparos duplicados de trabalhos subsequentes. Aqui se descreve o método de tratamento na aplicação, sem presumir que o callback chegará necessariamente em determinado prazo.

Após data.status=success, confirme que data.output contém de fato um endereço de resultado legível e então baixe a imagem. Se retornar fail, salve a mensagem de erro e corrija a requisição conforme o conteúdo; não adivinhe, com base apenas em um status, se a causa foi imagem grande demais, falha de rede ou outro motivo específico. Em caso de status inesperado ou ausência de saída, guarde a resposta e consulte novamente, sem tratar resultado vazio como entrega bem-sucedida.

Falha de download e falha de geração também devem ser separadas. Quando a tarefa já teve sucesso mas o arquivo não foi salvo corretamente, primeiro releia ou baixe de novo o resultado existente, evitando refazer a imagem diretamente. Ao arquivar, mantenha o número da tarefa, a correspondência das entradas e o local do arquivo final, para depois conseguir identificar com precisão de qual requisição veio cada imagem. O "tempo de espera esgotado" mostrado ao usuário deve significar que a interface atual parou de esperar, e não que a tarefa do servidor foi cancelada por conta própria.

Exemplo de envio em Python

O ambiente precisa ter requests instalado. Aqui, timeout=60 é o limite de espera da requisição de rede no cliente, não o tempo de geração da imagem.

import os
import requests

payload = {'model': 'google-virtual-try-on', 'input': {'person_image_url': 'https://static.hiapi.ai/gallery/2026/10/9f656c8b6ecf94d5.webp', 'product_image_url': 'https://static.hiapi.ai/model-covers/2026/10/22/1792660602486-b5b70d2cfdd8dc95-1792152569828-b5b70d2cfdd8dc95-t-g1-0.webp', 'num_images': 1}}
response = requests.post(
    "https://api.hiapi.ai/v1/tasks",
    headers={"Authorization": f"Bearer {os.environ['HIAPI_API_KEY']}"},
    json=payload,
    timeout=60,
)
response.raise_for_status()
result = response.json()
task_id = result["data"]["taskId"]
print(task_id)

Antes do envio e verificação do resultado

A interface não precisa de prompt. Não preencha num_images com 2 ou 4; se precisar de imagens alternativas, envie requisições separadas. Antes de enviar, confirme que as duas imagens podem ser lidas publicamente e que os campos não foram trocados. Ao receber status de falha, leia a mensagem retornada e corrija a entrada; não reenvie repetidamente o mesmo conteúdo.

Aprovar a imagem retornada conforme o uso do produto

Primeiro compare o resultado lado a lado com a imagem da pessoa, verificando rosto, cabelo, postura, fundo e também calças e sapatos que não deveriam mudar. Depois confira na imagem da roupa cor, formato da gola, comprimento da manga, estampa e barra. Na camiseta listrada, verifique a continuidade das listras horizontais no peito e nas mangas; no vestido, as alças, o decote caído e as dobras próximas às mãos; na camisa, se os punhos estão dobrados e se a barra está por dentro da cintura. Essas verificações vêm das mudanças visíveis nos casos, sem garantia de que outras entradas apresentarão apenas essas mudanças.

"Arquivo baixado" e "imagem utilizável em página de produto" devem ser registrados separadamente. Mesmo após retorno de sucesso, podem ocorrer alterações além da roupa, e o status da interface não substitui automaticamente a aprovação humana. Se o defeito vier de oclusão na entrada, troque primeiro a entrada e tente novamente; se o produto precisar mostrar comprimento de manga específico ou acessório fixo, avalie primeiro se o resultado atual atende a essa restrição, sem ignorar detalhes do produto só porque a composição geral ficou natural.

Ao adicionar alternativas para o mesmo conjunto de entradas, mantenha os resultados anteriores para comparação, sem sobrescrever arquivos antigos com novos. Ao escolher, registre o motivo da aceitação ou rejeição, para facilitar o tratamento de produtos semelhantes no futuro. A imagem serve apenas para observar a aparência; tamanho real e sensação de vestir ainda exigem informações de medidas da roupa e prova em pessoa real.

Perguntas frequentes

A foto da pessoa e a imagem da roupa podem compartilhar o mesmo campo?

Não. A foto da pessoa usa person_image_url e a imagem da roupa usa product_image_url.

É preciso adicionar o parâmetro prompt?

Não. A interface não tem campo de prompt; o try-on é determinado pelas duas imagens de entrada.

Por que escrever explicitamente num_images: 1?

Atualmente apenas um resultado é suportado; escrever explicitamente permite que a quantidade de imagens da requisição corresponda diretamente ao orçamento de $0.1075 por imagem.

Basta obter o taskId para ler a imagem?

Ainda é preciso consultar a tarefa ou receber a notificação; após data.status=success na tarefa, obtenha a imagem em data.output[0].url.

Continue lendo

Preço e orçamento · Integração à API · Casos e seleção de imagens · Google Virtual Try-On

Se precisar escolher entre try-on de roupas ou edição genérica de imagem, veja a comparação entre Google Virtual Try-On e Seedream 5.0 Lite, verificando item por item roupas, sapatos e aparência da pessoa.