Adicione Provador Virtual ao Seu App com uma API

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. 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 coloca todos os resultados lado a lado.

O que você precisa

Uma chave de API. Crie sua conta em 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:

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.
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.
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. Ele é compatível com Node 20+, Deno, Bun e runtimes de borda (edge).

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:

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>" } } }
  }'

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:

O app tira ou seleciona uma foto e a envia para o seu backend.
Seu backend faz o upload para a API e inicia o processo de try-on.
Seu backend recebe a URL gerada e a repassa ao app (ou avisa quando o webhook disparar).
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 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

Dúvidas respondidas.

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.

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.

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.

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.