Uma API de provador virtual recebe duas imagens, uma foto de uma pessoa e uma foto do produto, e retorna uma nova foto dessa pessoa vestindo o item. Este guia mostra como implementar essa funcionalidade em um app web, aplicativo mobile ou loja virtual sob medida, usando a [Genlook Try-On API](https://genlook.app/developers). O mesmo fluxo funciona para roupas, calçados, óculos, joias, relógios, bolsas e chapéus.
_Transparência: a Genlook desenvolveu esta API. Se você ainda está avaliando opções, nosso [comparativo de 10 APIs de provador virtual](/blog/melhores-apis-provador-virtual-2026-comparativo) coloca todos os resultados lado a lado._
## O que você precisa
- Uma chave de API. Crie sua conta em [platform.genlook.app](https://platform.genlook.app). Contas novas ganham 10 créditos grátis, o suficiente para testar todo o fluxo.
- Um backend. A chave precisa ficar guardada no seu servidor, nunca exposta no navegador ou no código-fonte de um app mobile.
- Uma foto da pessoa: formato JPEG, PNG, WebP ou HEIC de até 10 MB, de frente e com a parte do corpo que usará o produto bem visível.
- Uma imagem do produto: a mesma foto que já está na página do seu catálogo. Fotos em fundo branco (packshot), flat lay ou com modelo de estúdio funcionam perfeitamente. Não é necessário nenhum modelo 3D.
## Como funciona o fluxo
Toda integração segue estes três passos simples:
1. **Faça o upload da foto da pessoa** via `POST /images/upload`. Você receberá um `imageId` que poderá reutilizar em todos os testes com essa mesma foto.
2. **Crie a simulação de provador** com `POST /try-on`. Envie as informações do produto diretamente na requisição (imagem, título e descrição) junto com o `imageId`. Não é necessário sincronizar seu catálogo antes.
3. **Receba o resultado**: faça polling em `GET /generations/:id`, use a função `waitFor()` do SDK ou escute o webhook `generation.completed`. O tempo médio de resposta é de aproximadamente 8 segundos.
Se preferir fazer tudo em uma única requisição, o endpoint `POST /try-on/sync` mantém a conexão aberta até a imagem ficar pronta e devolve o resultado diretamente. Uma ótima opção para scripts e funções serverless.
## Seu primeiro teste em TypeScript
O SDK oficial é o [`@genlook/api`](https://genlook.app/docs/tryon-api/sdk). Ele é compatível com Node 20+, Deno, Bun e runtimes de borda (edge).
```ts
import { Genlook } from "@genlook/api";
import { readFile } from "node:fs/promises";
const client = new Genlook({ apiKey: process.env.GENLOOK_API_KEY! });
// 1. Envie a foto da pessoa uma única vez e guarde o imageId.
const { imageId } = await client.images.upload(
await readFile("./person.jpg"),
{ mimeType: "image/jpeg" },
);
// 2. Gere a simulação. O produto é informado diretamente na chamada.
const { generationId } = await client.tryOn.create({
products: [{
externalId: "linen-shirt-12",
title: "Camisa de linho casual",
description: "Modelagem oversized, ombros caídos, caimento abaixo do quadril.",
images: [{ source: { url: "https://cdn.example.com/linen-shirt.jpg" } }],
}],
person: { image: { source: { id: imageId } } },
});
// 3. Aguarde o resultado final.
const result = await client.generations.waitFor(generationId);
console.log(result.resultImageUrl);
```
## A mesma chamada em cURL ou Python
Embora não exista um SDK específico para Python, nossa API REST pode ser consumida em qualquer linguagem. Abaixo está o exemplo em uma única chamada usando o endpoint síncrono:
```bash
curl -X POST "https://api.genlook.app/tryon/v1/try-on/sync" \
-H "x-api-key: $GENLOOK_API_KEY" \
-H "Content-Type: application/json" \
--max-time 100 \
-d '{
"products": [{
"externalId": "linen-shirt-12",
"title": "Camisa de linho casual",
"description": "Modelagem oversized, ombros caídos, caimento abaixo do quadril.",
"images": [{ "source": { "url": "https://cdn.example.com/linen-shirt.jpg" } }]
}],
"person": { "image": { "source": { "id": "<imageId>" } } }
}'
```
```python
import os, requests
BASE = "https://api.genlook.app/tryon/v1"
headers = {"x-api-key": os.environ["GENLOOK_API_KEY"]}
with open("person.jpg", "rb") as f:
image_id = requests.post(f"{BASE}/images/upload", headers=headers,
files={"file": ("person.jpg", f, "image/jpeg")}).json()["imageId"]
result = requests.post(f"{BASE}/try-on/sync", headers=headers, timeout=100, json={
"products": [{
"externalId": "linen-shirt-12",
"title": "Camisa de linho casual",
"description": "Modelagem oversized, ombros caídos, caimento abaixo do quadril.",
"images": [{"source": {"url": "https://cdn.example.com/linen-shirt.jpg"}}],
}],
"person": {"image": {"source": {"id": image_id}}},
}).json()
print(result["resultImageUrl"])
```
A requisição síncrona aguarda por até 90 segundos. Se o processamento demorar mais do que isso, você receberá um status `202` com o `generationId` para acompanhar via polling.
## Óculos, joias, calçados e outros acessórios
Você não precisa especificar a categoria do item. A API analisa visualmente o produto e posiciona a peça no local correto: óculos no rosto, brincos nas orelhas, colar no pescoço e sapatos nos pés. A chamada é idêntica à de uma camiseta.
Dois pontos importantes:
- **Combinações de look (outfits) funcionam apenas com roupas.** É possível enviar até 4 peças de vestuário em uma só simulação, como camisa, calça e jaqueta. Óculos, chapéus, sapatos, bolsas e joias devem ser gerados individualmente.
- **A foto do cliente precisa mostrar a área onde a peça é usada.** Uma selfie mostrando apenas rosto e ombros serve para óculos ou brincos, mas não vai funcionar para sapatos.
## Aplicativos mobile (iOS, Android, Flutter, React Native)
Como nunca devemos compilar a chave de API diretamente no app, a arquitetura mobile sempre se comunica por meio do seu backend:
1. O app tira ou seleciona uma foto e a envia para o seu backend.
2. Seu backend faz o upload para a API e inicia o processo de try-on.
3. Seu backend recebe a URL gerada e a repassa ao app (ou avisa quando o webhook disparar).
4. O app exibe a imagem final na tela.
Como o seu servidor só precisa realizar requisições HTTP normais, a linguagem ou framework do seu aplicativo é totalmente indiferente.
## Custos e planos
Cada simulação consome 1 crédito, e falhas de processamento são estornadas automaticamente. No modelo pré-pago (pay as you go), o custo é de $0,04 por simulação, com pacotes a partir de $5 que nunca expiram. Planos mensais reduzem esse valor para $0,02 por geração (Starter: $20 por 1.000 créditos) ou até $0,015 no plano Scale ($300 por 20.000 créditos). O [simulador de preços](https://genlook.app/developers#pricing) na página de desenvolvedores ajuda a estimar seu custo mensal com base no seu volume previsto.
## Erros comuns para evitar
- **Chamar a API direto do frontend.** Qualquer usuário poderá inspecionar e roubar sua chave. Passe sempre pelo seu backend.
- **Usar títulos genéricos no produto.** O título e a descrição orientam a IA sobre o que é a peça e como é o seu caimento. "Cardigan curto de lã com caimento amplo" gera um resultado muito mais preciso do que "Item 4417".
- **Reenviar a foto do produto todas as vezes.** Na primeira vez que um produto é testado, a imagem passa por uma análise que leva alguns segundos a mais. Nas próximas chamadas, envie apenas o `externalId` para aproveitar a análise em cache.
- **Armazenar fotos por mais tempo que o necessário.** Defina o parâmetro `keepForDays` como 1, 3 ou 7 no momento do upload e forneça seu próprio `externalUserId`. Assim, você pode apagar todas as fotos de um cliente com uma única chamada quando solicitado.
- **Gastar créditos durante o desenvolvimento da interface.** Envie um produto com o título `mock`: a API devolverá a foto da pessoa intacta, com resposta imediata e custo zero, ideal para testar seu layout.
<Faq>
<FaqItem question="Existe alguma API que gera a foto de uma pessoa vestindo uma peça de roupa específica?">
Sim. Uma API de provador virtual faz exatamente isso: você envia a foto da pessoa e a foto do produto, e ela retorna a imagem da pessoa vestindo o item. Com a Genlook, isso leva apenas uma chamada no endpoint síncrono (ou duas com polling) e cerca de 8 segundos.
</FaqItem>
<FaqItem question="Preciso ter modelos 3D dos meus produtos?">
Não. A API funciona diretamente com fotos convencionais de catálogo, as mesmas que você já utiliza na sua loja virtual.
</FaqItem>
<FaqItem question="Posso usar essas imagens para fins comerciais?">
Sim. A Genlook é uma API comercial projetada especificamente para ambientes de produção em lojas e aplicativos. Modelos acadêmicos como IDM-VTON e CatVTON possuem licenças que proíbem o uso comercial.
</FaqItem>
<FaqItem question="Minha loja usa Shopify, WooCommerce ou PrestaShop. Preciso usar a API?">
Não necessariamente. Nosso app, plugin ou módulo oficial adiciona o provador virtual às páginas de produto sem exigir nenhuma linha de código. A API é indicada para lojas com arquitetura própria (headless), aplicativos mobile e produtos digitais personalizados.
</FaqItem>
</Faq>
Shopify
WooCommerce
API