API do Google Try On: exemplo de código, requisitos de foto e correções para o que não funciona

Um olhar prático sobre a API de Virtual Try-On do Google: um exemplo de código funcional em Python e REST, os requisitos de foto para as imagens da pessoa e da peça de roupa, e uma lista de correções por sintoma para erros, resultados vazios e provas com caimento ruim.

API do Google Try On: exemplo de código, requisitos de foto e correções para o que não funciona
Cristian Da Conceicao

Você envia duas fotos para a API de Virtual Try-On do Google, uma da pessoa e outra da peça de roupa, e espera uma imagem limpa dessa pessoa vestindo a roupa. Às vezes é exatamente isso que volta. Outras vezes você recebe um 403, uma lista vazia ou um suéter que se fundiu ao jeans. A diferença geralmente depende de três coisas: o código, as fotos e alguns ajustes que ninguém lê até algo quebrar.

Este artigo percorre as três. Você recebe um exemplo em Python que funciona, uma requisição REST que pode colar em um terminal, os requisitos de foto que decidem se o resultado parece real, e uma lista de correções por sintoma para os momentos de "não está funcionando". Como o modelo do Google não pode ser executado no PicassoIA, há também uma seção sobre como obter resultados parecidos com modelos que podem.

O que a API realmente faz

O Virtual Try-On do Google é um modelo no Vertex AI. Você envia uma imagem de uma pessoa e uma ou mais imagens de produtos, e ele devolve novas imagens da mesma pessoa vestindo o produto. Ele não gera um modelo aleatório. Ele edita a sua foto, mantendo o rosto, a pose, o fundo e as proporções, e troca a roupa.

Desenvolvedor em uma mesa de madeira escrevendo código para uma API de imagens

💡 Modelo mental rápido: pense nele como um endpoint de edição, não de texto para imagem. Não há um prompt criativo para ajustar. A qualidade do resultado é decidida quase inteiramente pelas duas fotos que você envia.

IDs e versões do modelo

É aqui que as pessoas travam pela primeira vez. A referência atual em inglês do Google lista virtual-try-on-001 como o modelo suportado, e ele está marcado como disponível para uso geral. Páginas antigas e várias cópias traduzidas da documentação ainda mencionam virtual-try-on-preview-08-04, a versão de prévia. Se você copiar um trecho de um tutorial antigo e o seu projeto não conseguir chamar esse ID de prévia, verá um erro do tipo "modelo não encontrado", que parece um bug, mas é na verdade um problema de nomenclatura.

ItemDetalhes
ID do modelo atualvirtual-try-on-001
ID de prévia antigovirtual-try-on-preview-08-04
PlataformaVertex AI no Google Cloud
EntradasUma imagem de pessoa, uma ou mais imagens de produtos
Fontes de imagemBytes em Base64 ou um URI do Cloud Storage
Variações por requisiçãoDe 1 a 4 (sampleCount)
Tamanho da saídaIgual à proporção e resolução da imagem de entrada

Onde o PicassoIA entra

O modelo de Virtual Try-On do Google não está no PicassoIA. Se você quer rodar prévias de looks virtuais hoje sem um projeto no Google Cloud, as alternativas estão descritas mais abaixo, incluindo o P Image Try On, criado exatamente para essa tarefa.

Exemplo de código em Python

Aqui está um fluxo mínimo e funcional. Ele pressupõe que você já tenha um projeto no Google Cloud com o Vertex AI ativado e faturamento configurado.

Configuração antes da primeira chamada

  1. Crie ou escolha um projeto no Google Cloud e ative a Vertex AI API.
  2. Instale o SDK Google Gen AI com pip install google-genai.
  3. Autentique-se localmente com gcloud auth application-default login.
  4. Certifique-se de que sua conta tenha uma função que permita chamar os modelos do Vertex AI.
  5. Escolha uma região. Use a mesma região no seu cliente e em qualquer URL REST.

A chamada em Python

from google import genai
from google.genai.types import Image, ProductImage, RecontextImageSource

client = genai.Client(
    vertexai=True,
    project="your-project-id",
    location="us-central1",
)

result = client.models.recontext_image(
    model="virtual-try-on-001",
    source=RecontextImageSource(
        person_image=Image.from_file(location="person.jpg"),
        product_images=[
            ProductImage(product_image=Image.from_file(location="sweater.jpg"))
        ],
    ),
)

with open("tryon-result.png", "wb") as f:
    f.write(result.generated_images[0].image.image_bytes)

Algumas observações sobre este trecho:

  • vertexai=True diz ao SDK para usar o Vertex AI em vez do endpoint do Gemini para consumidores. Se você esquecer, a autenticação falha de formas confusas.
  • product_images é uma lista, então a estrutura permite várias peças, mas comece com um único item até que o fluxo básico funcione.
  • Os nomes de métodos e classes do SDK mudam entre as versões. Se uma importação falhar, consulte a referência atual do SDK para os nomes exatos em vez de depurar o seu código.

Suéter de tricô bordô dobrado, fotografado de cima sobre uma superfície branca

A versão REST

Se você prefere HTTP puro, ou está chamando a partir de uma linguagem sem SDK, a requisição fica assim:

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://us-central1-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/us-central1/publishers/google/models/virtual-try-on-001:predict" \
  -d '{
    "instances": [{
      "personImage": { "image": { "bytesBase64Encoded": "PERSON_BASE64" } },
      "productImages": [
        { "image": { "bytesBase64Encoded": "GARMENT_BASE64" } }
      ]
    }],
    "parameters": { "sampleCount": 1 }
  }'

A resposta volta como uma lista de predições, cada uma com uma imagem em base64. Decodifique e grave em um arquivo.

ParâmetroO que fazCuidado com
sampleCountNúmero de variações, de 1 a 4Mais amostras significam mais custo por chamada
storageUriEnvia a saída para um bucket do Cloud StorageA conta de serviço precisa de acesso de escrita
seedTorna os resultados repetíveisRelatos indicam que não funciona com marca d’água ativada na versão de prévia
safetySettingDefine a força do filtroO padrão é block_medium_and_above, e block_none exige acesso especial

💡 Dica: a versão de prévia também listava parâmetros como baseSteps e addWatermark. Não presuma que existam no virtual-try-on-001. Envie apenas os parâmetros mostrados na referência atual e acrescente os demais um de cada vez.

Requisitos de foto que importam

A referência do Google não publica uma lista organizada de tamanhos de pixel e limites de arquivo que eu pudesse confirmar, então trate as regras abaixo como requisitos práticos, extraídos de como os modelos de try-on se comportam, e não como limites oficiais. O que é oficial: a saída mantém a mesma proporção e resolução da sua imagem de entrada, então um upload pequeno e cortado gera um resultado pequeno e cortado.

Homem em pé, de frente para uma parede branca lisa, com o corpo inteiro visível

A foto da pessoa

A imagem da pessoa é a base. Tudo o que o modelo preserva, ele preserva a partir daqui.

  • Corpo inteiro ou a parte superior do corpo bem visível, dependendo da peça. Uma jaqueta precisa de ombros e braços visíveis. Calças precisam de pernas.
  • Pose de frente, com os braços levemente afastados do tronco. Braços cruzados escondem as mangas e confundem a edição.
  • Fundo liso e sem excesso de elementos. Fundos cheios fazem as bordas se confundirem com o cenário.
  • Luz uniforme e suave. Sombras fortes sobre o peito acabam sendo incorporadas à nova peça.
  • Roupa de base ajustada. Um moletom largo por baixo de uma camisa justa faz o modelo adivinhar a forma do corpo.
  • Apenas uma pessoa. Fotos em grupo produzem resultados imprevisíveis.
  • Alta resolução, porque a saída herda essa resolução.

A foto da peça de roupa

A imagem do produto deve parecer uma foto de catálogo, não um instantâneo tirado no chão de um quarto.

  • Peça estendida sobre a superfície (flat lay) ou manequim fantasma sobre um fundo branco ou neutro.
  • Peça totalmente visível, sem mangas ou barras cortadas.
  • Sem vincos, porque as rugas são tratadas como parte do desenho.
  • Cor verdadeira, já que filtros pesados alteram o tom.
  • Um item por imagem. Uma modelo vestindo a peça na foto do produto pode funcionar, mas uma foto limpa e plana é o começo mais seguro.

Mãos segurando uma jaqueta amarelo-mostarda em um cabide de madeira diante de uma parede lisa

Tipo de fotoBomRuim
PessoaDe frente, pose neutra, luz suaveBraços cruzados, perfil, sombras duras
PessoaParede lisa atrásAmbiente lotado, espelhos, várias pessoas
PeçaEstendida sobre a superfície, fundo brancoAmassada na cama, parcialmente dobrada
PeçaItem inteiro no enquadramentoGola cortada ou barra faltando
AmbasDistância da câmera equivalenteUm close extremo e outro de longe

💡 Atalho: fotografe sua pessoa de teste contra uma parede vazia perto de uma janela, com a câmera na altura dos olhos e a cerca de dois metros de distância. Essa única montagem elimina a maior parte das reclamações de "caimento ruim" antes de qualquer código rodar.

Não está funcionando? Correções por sintoma

Quando algo quebra, parta do tipo de erro em vez de adivinhar. A maioria dos problemas cai em um de três grupos.

Mulher frustrada em uma mesa, massageando a têmpora enquanto olha para um notebook

Erros de permissão e de modelo

Sintoma: 403 ou "permission denied". A Vertex AI API não está ativada no projeto, o faturamento está faltando ou sua conta não tem uma função que permita chamar os modelos. Ative a API, confirme o faturamento e depois verifique a função.

Sintoma: 404 ou "model not found". Quase sempre é o ID do modelo. Troque para virtual-try-on-001 e confirme se a região no seu cliente é a mesma da requisição. Um ID de modelo que funciona em uma configuração de região pode falhar em outra.

Sintoma: 401 ou token expirado. Execute gcloud auth application-default login novamente. Os tokens de acesso da CLI expiram, e um script que funcionou de manhã pode falhar à tarde.

Sintoma: 429 ou "quota exceeded". Você atingiu um limite de taxa ou de cota. Adicione uma nova tentativa com backoff exponencial, reduza sampleCount e confira a página de cotas no console do Cloud. Não encontrei números publicados que eu pudesse confirmar, então o console é o lugar para ver os seus limites reais.

Resultados vazios e bloqueios de segurança

Sintoma: a chamada funciona, mas a lista de predições está vazia ou sem imagens. Geralmente é o filtro de segurança. A configuração padrão bloqueia de nível médio para cima, e fotos de pessoas de roupa de banho, roupa íntima ou roupas justas podem acioná-lo mesmo quando a intenção é inofensiva. Experimente uma roupa de base mais neutra na foto da pessoa e uma foto da peça que não pareça reveladora. Não conte com block_none, porque o Google restringe o acesso a ele.

Sintoma: 400 ou "invalid argument". Verifique o formato do payload. O base64 deve ser bytes puros, sem o prefixo data:image/png;base64,. personImage aceita uma imagem, productImages aceita uma lista. Um objeto de encapsulamento ausente no campo da imagem é o erro de digitação clássico.

Sintoma: o seed não faz nada ou gera erro. Na versão de prévia, o seed não podia ser combinado com marca d’água. Se você precisa de saída repetível, remova o parâmetro de marca d’água ou retire o seed, e teste com o ID do modelo atual.

Close de uma pessoa digitando em um notebook com anotações de depuração na mesa

Caimento ruim e resultado estranho

Se a API roda sem erros, mas a imagem parece errada, a causa quase sempre está em uma das fotos.

O que você vêCausa provávelCorreção
Mangas parecem pintadas no corpoBraços da pessoa cruzados ou escondidosRefaça a foto com os braços levemente afastados
A cor da peça parece erradaFoto de produto com filtroUse uma imagem sem edição e com luz uniforme
O padrão do tecido está borradoImagem da peça em baixa resoluçãoEnvie a maior resolução disponível
Camisa antiga ainda aparece na golaRoupa de base solta ou em camadasUse uma base justa e lisa
A saída parece cortadaA entrada estava cortadaLembre-se de que a saída segue a proporção da entrada
O rosto parece um pouco diferenteÁrea do rosto pequena na fotoAproxime-se ou use uma resolução maior

💡 Ordem de depuração que economiza tempo: teste com a foto de pessoa mais limpa e a foto de peça mais limpa que você tiver. Se funcionar, seu código está bom e o problema são suas fotos reais. Se falhar, o problema está na configuração, não nas imagens.

Como obter resultados parecidos no PicassoIA

O Virtual Try-On do Google ainda não está no PicassoIA; para resultados parecidos hoje, experimente o P Image Try On, criado para colocar uma peça de roupa em uma foto de pessoa sem nenhum projeto na nuvem, configuração de faturamento ou código.

Mulher tirando uma selfie de corpo inteiro em frente a um espelho em um quarto ensolarado

Passos com o P Image Try On

  1. Abra a página do modelo P Image Try On no PicassoIA.
  2. Envie sua foto da pessoa, seguindo as mesmas regras acima: de frente, fundo liso, luz suave.
  3. Envie a foto da peça, de preferência estendida sobre um fundo branco.
  4. Execute o modelo e analise o resultado.
  5. Se o caimento estiver ruim, troque por uma foto base mais limpa e rode de novo. Pequenas mudanças na foto importam mais do que qualquer outra coisa.

Dicas de parâmetros: mantenha as fotos da pessoa e da peça com qualidade parecida, evite filtros pesados e teste uma peça por vez. Se um resultado estiver próximo, mas não perfeito, use-o como ponto de partida para uma edição em vez de começar do zero.

Outros modelos que valem a pena testar

Às vezes um modelo dedicado de try-on não é a ferramenta certa, por exemplo quando você quer trocar o fundo, ajustar a iluminação ou corrigir um detalhe depois da troca. Estes funcionam bem como complementos:

ModeloMelhor para
Nano Banana ProEdições de imagem de alta qualidade a partir de uma foto de referência e uma instrução em linguagem simples
Nano BananaEdições rápidas e trocas de look com um prompt curto
PicassoIA Image Editor ProEdições de foto ilimitadas, como limpar o fundo ou mudar a cor de uma peça

Um fluxo prático: faça a troca de roupa com o P Image Try On e depois refine o resultado com o PicassoIA Image Editor Pro, por exemplo removendo uma sombra perdida ou corrigindo um vinco.

Casos de uso reais

Lojas online

Lojas de moda usam try-on para reduzir devoluções e dar aos clientes uma noção melhor do caimento. A API serve para lojas que já têm fotos de catálogo limpas e podem executá-la como uma etapa no backend. A cliente envia uma foto, seu servidor chama o modelo, e a prévia aparece na página do produto.

Cliente segurando um smartphone em direção a uma arara de roupas dentro de uma boutique iluminada

Alguns pontos práticos para donos de loja:

  • Fotografe todos os produtos do mesmo jeito, para que as entradas de peças sejam consistentes.
  • Explique aos clientes como tirar a foto com uma imagem de exemplo simples ao lado do botão de envio.
  • Trate os resultados vazios com elegância, mostrando uma mensagem pedindo outra foto, em vez de uma tela de erro.
  • Armazene os resultados em cache, porque chamadas repetidas custam dinheiro.

Prévias de moda pessoais

Nem todo mundo tem uma loja. Se você só quer ver como uma jaqueta pode ficar antes de comprar, uma rota sem código é mais rápida do que montar um projeto na nuvem. Tire uma foto limpa, pegue a imagem do produto na página de uma loja e rode um modelo de try-on pelo navegador.

Mãos organizando fotos de moda impressas e amostras de tecido sobre uma mesa de nogueira

Aqui está uma rotina simples que funciona bem para uso pessoal:

  1. Tire uma boa foto sua e reutilize-a em todos os testes.
  2. Escolha três peças em cores ou cortes diferentes.
  3. Rode cada uma e compare os resultados lado a lado.
  4. Guarde as duas melhores e descarte o resto.

💡 Lembrete: uma prévia de try-on mostra uma aproximação. O caimento do tecido, a elasticidade e o ajuste no mundo real ainda dependem da peça, então trate a imagem como um guia de cor e estilo, não como uma checagem exata de tamanho.

Experimente suas prévias de look

A API Google Try On é poderosa quando você tem um projeto na nuvem, fotos limpas e um motivo para automatizar. Quando a configuração, a cota ou o filtro de segurança atrapalham, você não precisa parar de experimentar. Abra o P Image Try On no PicassoIA, envie uma foto com parede lisa e uma peça estendida sobre a superfície, e veja o resultado em poucos minutos. Depois use o Nano Banana Pro ou o PicassoIA Image Editor Pro para refinar os detalhes.

Teste três peças, duas configurações de iluminação e um fundo limpo, e compare. Você vai perceber rapidamente quais hábitos de foto realmente importam. Pronto para testar mais? Veja todos os modelos disponíveis em picassoia.com/en/all-models e comece a criar suas próprias imagens hoje.

Compartilhe este artigo

Escolha seu idioma

FreeCrie imagens e vídeos com IAGrátis, sem cartão de créditoGerações grátis para começarSeedance 2.5 Lite incluídoComece grátis agora