Tutorial
Como usar o Google Virtual Try-On pela API do HiAPI: guia com curl e Python
Nesta página
O que o modelo google-virtual-try-on espera
Antes de escrever qualquer código, é útil entender o contrato de entrada. O modelo google-virtual-try-on é uma tarefa de composição com duas imagens: ele recebe uma imagem de pessoa/modelo e uma imagem de peça de roupa, e gera uma imagem da pessoa vestindo aquela peça.
Isso significa que sua etapa de preparação tem sempre o mesmo formato:
- Uma imagem da pessoa com o sujeito claramente visível e enquadrado de forma razoável — fotos de corpo inteiro ou de meio corpo funcionam melhor, pois o modelo precisa entender a geometria do corpo.
- Uma imagem da peça de roupa, de preferência sobre um fundo limpo ou de cor sólida, mostrando a peça que você deseja transferir para a pessoa.
As duas entradas são fornecidas como URLs de imagem, não como dados binários brutos no corpo da requisição. Isso mantém o payload pequeno e permite que sua própria camada de armazenamento (S3, GCS, CDN) continue sendo a fonte da verdade. Portanto, seu trabalho é garantir que cada URL esteja acessível publicamente antes de disparar a chamada — ou assinada com validade suficientemente longa.
Há algumas restrições práticas a planejar com antecedência:
- Resolução e proporção afetam a qualidade da saída. Miniaturas minúsculas ou entradas excessivamente recortadas tendem a produzir resultados ruins.
- Cada chamada processa apenas uma peça de roupa. Se a página do seu produto tem várias cores, faça várias chamadas em vez de tentar enfiar várias peças em uma única requisição.
- O pareamento é sua responsabilidade. O modelo não valida se a roupa "combina" com a pessoa; ele apenas compõe o que você fornece. Bons pareamentos (foto de corpo inteiro com vestido, foto de meio corpo com jaqueta) trazem melhorias claras na saída.
Trate esta etapa como um contrato de ativos: se você conseguir gerar de forma confiável dois URLs de qualidade para cada tarefa, o restante do trabalho de integração se resume a montar um pipeline direto.
Configurando sua requisição HiAPI
Todas as chamadas de modelo do HiAPI seguem o mesmo formato, então, uma vez que você tenha uma funcionando, as outras só exigem a troca de parâmetros. Veja o que o google-virtual-try-on exige.
Endpoint e método
A requisição é enviada como POST para o endpoint de chamada de modelo do HiAPI de google-virtual-try-on. Você usa a mesma URL base e o mesmo conjunto de credenciais em todos os modelos, o que é justamente o principal motivo de optar pelo roteamento via HiAPI em vez de integrar cada provedor individualmente.
Autenticação
Autentique usando a API key do HiAPI no cabeçalho Authorization, no formato padrão de bearer token:
Authorization: Bearer $HIAPI_API_KEY
Mantenha a chave no servidor. Nunca a distribua em bundles de navegador ou aplicativos móveis — o proxy pelo seu próprio backend é mais seguro e ainda oferece um ponto para adicionar limitação de taxa e logs.
Tipo de conteúdo
Envie o corpo da requisição como JSON:
Content-Type: application/json
Corpo da requisição
O corpo da requisição carrega o identificador do modelo e os dois URLs de imagem da seção anterior — a imagem da pessoa e a imagem da roupa —, além de quaisquer parâmetros opcionais expostos pelo modelo. Os nomes exatos dos parâmetros são os documentados junto ao modelo; copie literalmente em vez de adivinhar, pois erros de ortografia em nomes de campos geralmente se manifestam como erros de validação, e não como mensagens úteis.
Salve sua configuração
Coloque a URL base, o identificador do modelo e a chave em variáveis de ambiente, assim o mesmo script funciona em pré-produção e produção sem alterações:
export HIAPI_API_KEY="your-key-here"
export HIAPI_BASE_URL="https://api.hiapi.ai"
É só isso de configuração. Sem SDK, sem integração por provedor.
Uma requisição curl funcional
A forma mais rápida de confirmar se a chave e o payload estão corretos é uma única chamada curl. Veja a anatomia de uma requisição para google-virtual-try-on:
curl -X POST "$HIAPI_BASE_URL/v1/models/google-virtual-try-on" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "google-virtual-try-on",
"input": {
"model_image": "https://your-cdn.example.com/person-001.jpg",
"garment_image": "https://your-cdn.example.com/jacket-front.jpg"
}
}'
Alguns pontos de atenção:
- Os dois campos de imagem ficam dentro do objeto
input, o que mantém os parâmetros específicos do modelo isolados em um namespace e separados dos campos de roteamento. - Os URLs precisam ser acessíveis a partir do servidor, não do seu notebook. Um endereço
localhostou acessível apenas por VPN vai falhar. - Não há etapa de upload de arquivo nesta chamada. Se seus ativos ainda não estão em uma CDN, faça o upload primeiro e use o URL gerado.
Execute uma vez e inspecione o JSON bruto retornado antes de construir qualquer coisa em cima disso. Passar a saída por um formatador facilita a leitura:
curl -s -X POST "$HIAPI_BASE_URL/v1/models/google-virtual-try-on" \
-H "Authorization: Bearer $HIAPI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json | python -m json.tool
Guardar o corpo da requisição em um arquivo request.json também evita erros de aspas no shell quando o payload crescer.
A mesma requisição em Python
Para qualquer cenário além de um teste pontual, passe para Python. O exemplo abaixo usa apenas a biblioteca padrão mais requests, então pode ser colocado diretamente em um script, Lambda ou pequeno serviço, sem framework adicional.
import os
import requests
API_KEY = os.environ["HIAPI_API_KEY"]
BASE_URL = os.environ.get("HIAPI_BASE_URL", "https://api.hiapi.ai")
def try_on(person_url: str, garment_url: str, timeout: int = 120) -> dict:
payload = {
"model": "google-virtual-try-on",
"input": {
"model_image": person_url,
"garment_image": garment_url,
},
}
headers = {
"Authorization": f"Bearer {API_KEY}",
"Content-Type": "application/json",
}
response = requests.post(
f"{BASE_URL}/v1/models/google-virtual-try-on",
json=payload,
headers=headers,
timeout=timeout,
)
response.raise_for_status()
return response.json()
if __name__ == "__main__":
result = try_on(
"https://your-cdn.example.com/person-001.jpg",
"https://your-cdn.example.com/jacket-front.jpg",
)
print(result)
Notas sobre a adaptação:
- Defina um timeout explícito. A geração de imagens não é instantânea; o timeout padrão do
requestsé agressivo demais para esse tipo de chamada. Escolha um valor confortavelmente acima da sua latência p99. - Use
json=payload, nãodata=json.dumps(payload). Ele define o tipo de conteúdo para você e evita bugs de codificação dupla. - Retorne o JSON já parseado, não o objeto de resposta, assim os chamadores não dependem acidentalmente de detalhes internos do HTTP. Se precisar dos códigos de status para métricas, capture-os antes de retornar.
- Separe o cliente do fluxo de trabalho. Em um serviço real, a função acima pertence a um módulo cliente leve; a fila, o armazenamento e as repetições ficam em uma camada acima.
Se você já usa httpx ou um framework assíncrono, a conversão é mecânica — o payload e os cabeçalhos são idênticos.
Lendo a resposta
A resposta é JSON. Trate-a como um pequeno envelope que se concentra em duas coisas: se a tarefa teve sucesso e onde está a saída.
Grosso modo, você deve verificar:
- Status de transporte. 2xx significa que a requisição foi aceita e processada. 4xx significa que sua requisição estava errada; 5xx significa que algo deu errado no lado do servidor. Registre o código de status a cada chamada — é a forma de observabilidade mais barata que você pode adicionar.
- Campos do corpo da resposta. O payload carrega o resultado da geração. O resultado da imagem é retornado como um URL apontando para o ativo gerado. Os nomes exatos dos campos seguem o schema de resposta do modelo; faça o parse de forma defensiva em vez de assumir que é uma única string.
- Metadados. Qualquer campo de uso ou de tempo de execução na resposta vale a pena ser capturado. A cobrança é medida pela plataforma, então persistir metadados por requisição permite, no futuro, reconciliar seus logs com o dashboard.
Um parse robusto fica assim:
data = try_on(person_url, garment_url)
outputs = data.get("output") or {}
image_url = outputs.get("image")
if not image_url:
raise RuntimeError(f"No image in response: {data}")
Como processar o resultado
O URL retornado é o ativo gerado, não um ativo permanente. Não entregue direto ao frontend e esqueça. Em vez disso:
- Baixe e re-hospede. Busque os bytes imediatamente e grave no seu próprio bucket com uma chave endereçada por conteúdo. Isso desacopla seu produto da política de retenção do gerador.
- Registre a proveniência. Armazene os URLs de entrada, o identificador do modelo e o timestamp junto com a saída. Quando o lojista perguntar por que determinado provador ficou daquele jeito, você vai precisar reproduzir a tarefa exata.
- Normalize o formato. Redimensione e converta uma única vez, na ingestão, para o formato padrão da vitrine, em vez de processar a cada visualização de página.
Tratar a resposta como uma passagem temporária — parse, download, armazenamento, descarte — é o padrão escalável.
Modos de falha e estratégia de repetição
Nem toda falha vale a pena ser repetida. Repetir às cegas transforma um pequeno hiccup upstream em uma fila cheia de tarefas duplicadas e uma conta surpreendente.
Classifique antes de repetir
Não repita — corrija a requisição:
- Erros de validação do tipo
400: JSON malformado, campos ausentes ou com nome errado, corpo da requisição fora da estrutura esperada pelo modelo. 401/403: API key errada ou ausente, ou chave sem permissão para acessar aquele modelo. Repetir nunca resolve.404: identificador do modelo ou caminho do endpoint errado.- URL de imagem inacessível. Se o URL da pessoa ou da roupa retorna 404 ou dá timeout na busca, a geração não pode prosseguir. Valide os URLs antes de enviar.
Repita com backoff:
429: você foi limitado por taxa. Faça backoff e respeite o sinal.5xx: erro transitório de serviço ou upstream.- Falhas de rede: reset de conexão, timeout de leitura.
Repetições limitadas com jitter
Limite o número de tentativas — três é um teto comum — e use backoff exponencial com jitter aleatório, para que uma multidão de workers não repita em sincronia:
import random, time
def with_retry(fn, attempts=3, base=1.0):
for i in range(attempts):
try:
return fn()
except requests.HTTPError as e:
status = e.response.status_code if e.response is not None else None
if status is not None and 400 <= status < 500 and status != 429:
raise # client error: do not retry
if i == attempts - 1:
raise
time.sleep(base * (2 ** i) + random.uniform(0, 0.5))
Proteções de produção
- Idempotência em nível de tarefa. Faça hash do par de URLs de entrada como chave da tarefa. Se a mesma chave já está em execução ou concluída, retorne o resultado armazenado em vez de reenviar.
- Fila de mensagens mortas. Quando as repetições se esgotarem, estacione a tarefa com todo o seu contexto, em vez de descartá-la silenciosamente.
- Disjuntor. Se a taxa de erro passar do limite, pare de enviar durante um período de resfriamento, em vez de continuar martelando um serviço em dificuldade.
- Alertas por padrão, não apenas por volume. Um pico de 4xx logo após um deploy normalmente significa que alguém renomeou um campo.
Valide as entradas cedo
A maioria das "falhas do modelo" é, na verdade, entrada ruim. Faça uma pré-verificação barata: envie um HEAD para cada URL, verifique o tipo de conteúdo e as dimensões aproximadas, e rejeite ativos obviamente inutilizáveis antes de gastar uma chamada tarifada. Esse único hábito elimina a maior parte do seu tráfego de repetição.
Integrando a um pipeline real
Uma chamada curl bem-sucedida é apenas uma demonstração. Uma funcionalidade de produto confiável exige um pouco mais de estrutura ao redor.
Estruture o fluxo em etapas
Uma decomposição viável:
- Ingestão. O lojista ou usuário interno envia a imagem da pessoa e a imagem da roupa. Armazene ambas no seu armazenamento de objetos e gere URLs estáveis e assinados.
- Validação. Verifique acessibilidade, formato e dimensões. Rejeite cedo com uma mensagem clara.
- Envio. Chame
google-virtual-try-onpelo módulo cliente. Registre no banco a chave da tarefa, o identificador do modelo e os URLs de entrada. - Materialização. Em caso de sucesso, baixe a imagem gerada, converta para o seu formato padrão e grave na sua CDN com uma chave determinística.
- Publicação. Atualize o registro da tarefa para apontar para o ativo que você hospeda, e faça a vitrine ler apenas do seu próprio armazenamento.
Cada etapa pode ser repetida de forma independente, e é exatamente isso que torna o sistema todo depurável. Se a etapa 4 falhar, você não precisa rodar a geração de novo.
Mantenha o cliente leve
Coloque a chamada HTTP em um módulo pequeno e envolva-o com a política (repetições, concorrência, timeouts, logs). Quando o HiAPI adicionar um parâmetro ao modelo, ou quando você quiser testar em A/B rotas diferentes de geração de imagem, você só altera um arquivo.
Hábitos operacionais que valem a pena adotar
- Assíncrono por padrão. A geração leva segundos, às vezes mais. Envie a partir de um worker, não de um handler de requisição em que o usuário está esperando.
- Cache agressivo. O mesmo par de pessoa e roupa nunca deve ser gerado duas vezes. Endereçe a saída por conteúdo e verifique antes de enviar.
- Faça orçamento com visibilidade. Como o uso é medido pela plataforma, registre metadados por requisição e reconcilie periodicamente com o seu dashboard do HiAPI. Descubra um laço de repetição descontrolado em horas, não no fim do mês.
- Versione prompts e parâmetros. Armazene o objeto de parâmetros junto com cada tarefa, para poder reproduzir resultados após mudanças.
- Falhe de forma visível para o usuário. Um spinner de carregamento que nunca desaparece é pior do que um honesto "não conseguimos gerar isto, tente outra foto".
Próximos passos
O mesmo formato de requisição se aplica a outros modelos de imagem do HiAPI, então o cliente que você construir aqui será o modelo para o restante do seu pipeline. Assim que a chamada com duas imagens estiver estável, explore o catálogo de modelos para ver o que mais se encaixa no seu fluxo de trabalho — os padrões de autenticação, tratamento de erros e armazenamento se aplicam igualmente.
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