Blogue

Tutorial

Como usar o Google Virtual Try-On pela API do HiAPI: guia com curl e Python

Nov 10, 2026
Prismas geométricos planos e abstratos, divididos em planos verde-sálvia e verde-pinheiro sobre um fundo verde-escuro; arte de capa para um tutorial de desenvolvedor.
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 localhost ou 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ão data=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:

  1. 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.
  2. 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.
  3. 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:

  1. 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.
  2. Validação. Verifique acessibilidade, formato e dimensões. Rejeite cedo com uma mensagem clara.
  3. Envio. Chame google-virtual-try-on pelo módulo cliente. Registre no banco a chave da tarefa, o identificador do modelo e os URLs de entrada.
  4. 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.
  5. 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 →

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