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.
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.
💡 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.
Item
Detalhes
ID do modelo atual
virtual-try-on-001
ID de prévia antigo
virtual-try-on-preview-08-04
Plataforma
Vertex AI no Google Cloud
Entradas
Uma imagem de pessoa, uma ou mais imagens de produtos
Fontes de imagem
Bytes em Base64 ou um URI do Cloud Storage
Variações por requisição
De 1 a 4 (sampleCount)
Tamanho da saída
Igual à 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
Crie ou escolha um projeto no Google Cloud e ative a Vertex AI API.
Instale o SDK Google Gen AI com pip install google-genai.
Autentique-se localmente com gcloud auth application-default login.
Certifique-se de que sua conta tenha uma função que permita chamar os modelos do Vertex AI.
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.
A versão REST
Se você prefere HTTP puro, ou está chamando a partir de uma linguagem sem SDK, a requisição fica assim:
A resposta volta como uma lista de predições, cada uma com uma imagem em base64. Decodifique e grave em um arquivo.
Parâmetro
O que faz
Cuidado com
sampleCount
Número de variações, de 1 a 4
Mais amostras significam mais custo por chamada
storageUri
Envia a saída para um bucket do Cloud Storage
A conta de serviço precisa de acesso de escrita
seed
Torna os resultados repetíveis
Relatos indicam que não funciona com marca d’água ativada na versão de prévia
safetySetting
Define a força do filtro
O 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.
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.
Tipo de foto
Bom
Ruim
Pessoa
De frente, pose neutra, luz suave
Braços cruzados, perfil, sombras duras
Pessoa
Parede lisa atrás
Ambiente lotado, espelhos, várias pessoas
Peça
Estendida sobre a superfície, fundo branco
Amassada na cama, parcialmente dobrada
Peça
Item inteiro no enquadramento
Gola cortada ou barra faltando
Ambas
Distância da câmera equivalente
Um 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.
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.
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ável
Correção
Mangas parecem pintadas no corpo
Braços da pessoa cruzados ou escondidos
Refaça a foto com os braços levemente afastados
A cor da peça parece errada
Foto de produto com filtro
Use uma imagem sem edição e com luz uniforme
O padrão do tecido está borrado
Imagem da peça em baixa resolução
Envie a maior resolução disponível
Camisa antiga ainda aparece na gola
Roupa de base solta ou em camadas
Use uma base justa e lisa
A saída parece cortada
A entrada estava cortada
Lembre-se de que a saída segue a proporção da entrada
O rosto parece um pouco diferente
Área do rosto pequena na foto
Aproxime-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.
Envie sua foto da pessoa, seguindo as mesmas regras acima: de frente, fundo liso, luz suave.
Envie a foto da peça, de preferência estendida sobre um fundo branco.
Execute o modelo e analise o resultado.
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:
Ediçõ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.
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.
Aqui está uma rotina simples que funciona bem para uso pessoal:
Tire uma boa foto sua e reutilize-a em todos os testes.
Escolha três peças em cores ou cortes diferentes.
Rode cada uma e compare os resultados lado a lado.
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.