Documentação Provei

Integre a composição de imagens por IA diretamente nas suas aplicações

v2.0.0

Documentação da API

As duas rotas POST de composição recebem multipart/form-data e devolvem uma imagem binária. A rota GET /api/v2/widget-measurements/match recebe apenas parâmetros de query e devolve JSON de capacidades. O runtime do widget obtém a identidade e o recibo antes de chamar as composições.

Início rápido

Passo 1

Tenha o user_id do perfil

O campo user_id identifica o perfil usado no snippet. Ele não é uma API key nem substitui a origem autorizada e o recibo de identidade.

Passo 2

Cadastre produtos

Cada produto precisa existir no catálogo com a reference_url que será enviada na composição.

Passo 3

Envie multipart/form-data

Envie imagem, reference_url e user_id e receba a imagem resultante em binário.

Importante

Créditos e assinatura

O lojista ainda precisa ter assinatura ativa e créditos disponíveis para gerar composições.

Autenticação e escopo

Estas são rotas públicas mediadas pelo widget: o navegador não envia API key. O runtime autorizado emite ou renova o identity_receipt e o envia nas composições; não trate os exemplos como APIs servidor-a-servidor independentes.

Antes de qualquer composição, o handler confere o UUID do owner, a origem da página, o provisionamento e o produto ativo. Fashion e Óculos também exigem o UUID exato de product_id; Home encontra o tipo permitido pela URL normalizada e nunca aceita product_type do cliente.

As composições Fashion, Óculos e Home usam multipart, resposta binária, Idempotency-Key e timeout de cliente de 120 segundos. A rota de Medidas é um GET sem body, sem multipart e sem idempotência: ela retorna JSON de capacidades.

http

Idempotency-Key: home-operation-unique-001
Content-Type: multipart/form-data (gerado automaticamente pelo cliente HTTP)
Campos obrigatórios: environment_image, reference_url, user_id, identity_receipt

Rate limit e headers de resposta

Quando a requisição é aceita, a API devolve headers de limite e pode definir um cookie interno de identidade. Quando o visitante é bloqueado, a resposta 429 inclui o payload JSON abaixo.

http

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1776945600
Retry-After: 3600
Set-Cookie: reverbs_widget_rate_limit_id=...; Path=/; Max-Age=31536000; HttpOnly; SameSite=None; Secure

{
  "success": false,
  "code": "VISITOR_RATE_LIMITED",
  "message": "Limite de gerações atingido. Tente novamente quando o período for renovado.",
  "limit": 10,
  "remaining": 0,
  "reset_at": "2026-04-23T12:00:00.000Z"
}

Endpoints

O guia cobre Fashion, Óculos, Home (Móveis, Revestimentos e Pisos) e Measurements, com leituras e instalação do runtime de óculos.

Try-on de moda

Fashion

Recebe a foto da pessoa, o UUID do produto Fashion ativo e o recibo emitido pelo runtime autorizado. Devolve a imagem gerada em binário.

Endpoint

POSThttps://app.provei.ai/api/v2/widget-fashion/try-on

Requisição

Estas são rotas públicas mediadas pelo widget. O navegador não envia API key; cada rota valida a origem e aplica suas próprias verificações de identidade e produto antes de processar.

Clientes cURL, Node.js e Python devem informar essa mesma origem explicitamente (por exemplo, Origin: https://loja.com.br); uma origem não autorizada é rejeitada antes da composição.

Content-Type: multipart/form-data (gerado automaticamente pelo cliente HTTP)

Campos (form-data)

Campo	Tipo	Obrigatório	Descrição
`user_image`	file	Sim	Foto da pessoa em PNG, JPEG ou WebP com no máximo 4 MiB. O limite de 5 MiB vale para o corpo multipart completo.
`reference_url`	string	Sim	URL enviada para a composição. O handler localiza o produto Fashion ativo pelo product_id; quando a URL não coincide com a URL canônica cadastrada, a requisição não é rejeitada por esse desencontro e a URL informada segue para o serviço de composição.
`product_id`	string (UUID)	Sim	UUID exato do produto Fashion ativo pertencente ao user_id. Ele seleciona o produto consultado pelo handler; não é comparado à reference_url para rejeitar um desencontro.
`user_id`	string (UUID)	Sim	UUID do perfil proprietário usado pelo widget. A rota valida o formato, ownership, origem autorizada e provisionamento.
`identity_receipt`	string	Sim	Recibo de identidade assinado emitido ou renovado pelo runtime do widget autorizado. Não é uma API key.
`visitor_id`	string	Não	Identificador opcional do visitante para controle de rate limit.
`session_id`	string	Não	Identificador opcional da sessão do visitante para o rate limit.
`customer_identity_hash`	string	Não	Hash opcional de identidade persistente quando a integração já possui um identificador do cliente.

Resposta de sucesso

201Imagem binária com Content-Type propagado do serviço de composição (image/png, image/jpeg ou image/webp).

Observações

A chamada é mediada pelo widget: o runtime verifica o owner e a origem, e emite/renova o identity_receipt antes de enviar a operação.
product_id seleciona o produto Fashion ativo. Quando reference_url coincide com a URL canônica normalizada, o handler usa a URL canônica; caso contrário, encaminha a URL informada ao serviço de composição sem rejeitar o desencontro.
Erros JSON de composição usam `{ success: false, message: string }`; o rate limit local pode acrescentar code, limit, remaining e reset_at.

Exemplos de integração

curl -X POST https://app.provei.ai/api/v2/widget-fashion/try-on \
  -H "Origin: https://loja.com.br" \
  -H "Idempotency-Key: fashion-operation-unique-001" \
  -F "user_image=@/caminho/foto-pessoa.jpg" \
  -F "reference_url=https://loja.com.br/produto/camiseta-azul" \
  -F "product_id=123e4567-e89b-12d3-a456-426614174000" \
  -F "user_id=550e8400-e29b-41d4-a716-446655440000" \
  -F "identity_receipt=SIGNED_WIDGET_RECEIPT" \
  --output resultado.bin

Erros possíveis

Status	Mensagem	O que fazer
`400`	Content-Length declarado inválido, body ausente/ilegível ou Idempotency-Key ausente/acima de 255 caracteres.	Envie um body multipart legível e uma chave opaca única por composição. Um multipart que falhe na interpretação do formData pode resultar em 500.
`401`	Guard: identity_receipt inválido/ausente; serviço upstream: chave de API inválida, revogada ou indisponível no servidor.	Recarregue o runtime autorizado para emitir/renovar o recibo; a API key é resolvida apenas no servidor.
`402`	O serviço upstream confirmou créditos insuficientes.	Confirme o saldo de créditos da conta antes de iniciar uma nova composição.
`403`	Guard: origem não autorizada para o owner; serviço upstream: assinatura inativa.	Confira a origem cadastrada e o estado da assinatura; não tente substituir o guard por uma API key no browser.
`404`	Fashion não está provisionado para o owner ou product_id não identifica um produto Fashion ativo.	Confirme o UUID do perfil/produto e o provisionamento Fashion. Um desencontro entre reference_url e a URL canônica, sozinho, não gera este status.
`413`	O corpo multipart completo excede o limite de 5 MiB da rota Fashion.	Reduza a foto e o overhead do multipart; a imagem individual também deve ter até 4 MiB.
`422`	Campo inválido: imagem ausente/incompatível, reference_url vazia, UUID do produto/owner inválido ou identity_receipt acima de 4096 caracteres.	Corrija os campos validados do multipart e reenvie a requisição.
`429`	Visitante bloqueado por rate limit. O payload inclui `code: "VISITOR_RATE_LIMITED"`.	Leia Retry-After e os headers X-RateLimit-* antes de permitir nova tentativa.
`500`	Erro interno ao interpretar a requisição ou preparar a composição.	Confira o multipart e tente novamente; não trate esse retorno como confirmação de que a composição foi processada.
`503`	O serviço de composição está temporariamente indisponível.	Aguarde alguns instantes antes de reenviar.
`504`	O processamento excedeu o tempo limite de 120 segundos.	Configure o cliente para aguardar até 120 segundos e trate a operação como uma nova tentativa.

Try-on de óculos

Óculos

Recebe selfie enviada ou foto estática da câmera frontal mobile e gera uma imagem de IA. Não é vídeo contínuo nem AR ao vivo.

Endpoint

POSThttps://app.provei.ai/api/v2/widget-glasses/try-on

Requisição

Estas são rotas públicas mediadas pelo widget. O navegador não envia API key; cada rota valida a origem e aplica suas próprias verificações de identidade e produto antes de processar.

Clientes cURL, Node.js e Python devem informar essa mesma origem explicitamente (por exemplo, Origin: https://loja.com.br); uma origem não autorizada é rejeitada antes da composição.

Origin autorizado e Idempotency-Key obrigatórios. FormData gera o Content-Type/boundary. Não envie API key, credenciais de IA ou imagens de referência do catálogo.

Campos (form-data)

Campo	Tipo	Obrigatório	Descrição
`user_image`	file	Sim	Foto da pessoa em PNG, JPEG ou WebP com no máximo 4 MiB. O limite de 5 MiB vale para o corpo multipart completo.
`reference_url`	string	Sim	URL equivalente à referência canônica do produto glasses ativo. O servidor normaliza a comparação e rejeita desencontro com 404; não encaminha uma URL arbitrária como Fashion.
`product_id`	string (UUID)	Sim	UUID exato do produto glasses ativo pertencente ao user_id. Obtenha-o pela correspondência de URL do catálogo.
`user_id`	string (UUID)	Sim	UUID do perfil proprietário usado pelo widget. A rota valida o formato, ownership, origem autorizada e provisionamento.
`identity_receipt`	string	Sim	Recibo de identidade assinado emitido ou renovado pelo runtime do widget autorizado. Não é uma API key.
`visitor_id`	string	Não	Identificador opcional do visitante para controle de rate limit.
`session_id`	string (UUID)	Não	UUID opcional da sessão, usado no rate limit e encaminhado à composição.
`customer_identity_hash`	string	Não	Hash opcional de identidade persistente quando a integração já possui um identificador do cliente.

Resposta de sucesso

201201 com imagem binária (Content-Type upstream), X-Image-Code e headers de rate limit quando aplicáveis; não retorna URL pública.

Observações

Setup: customer_vertical=eyewear, catálogo product_type=glasses e acesso runtime/UI glasses. Vertical e tipo de catálogo não concedem entitlement.
Instale o snippet-glasses na storefront autorizada. O runtime usa mode=glasses, emite/renova identity_receipt e consulta config/match antes da geração; essas leituras não admitem composição.
product_id deve identificar produto glasses ativo do mesmo owner. reference_url deve equivaler à URL canônica normalizada; desencontro retorna 404, ao contrário de Fashion.
O runtime normaliza a selfie preservando frame inteiro e proporções, sem o recorte Fashion. Imagem até 4 MiB; multipart completo até 5 MiB.
Origem, entitlement, recibo assinado e produto são validados antes do rate limit e da chamada de IA. Assinatura, créditos e admissão upstream continuam obrigatórios; o navegador não escolhe provider nem modelo.
Idempotency-Key: valor não vazio de até 255 caracteres, criado uma vez por nova geração. Reenvios da mesma operação conservam chave e payload; timeout/erro não comprovam ausência de efeito e não autorizam trocar a chave automaticamente.
Download usa a imagem privada/local retornada. Compartilhamento usa a URL do produto da loja; não publica selfie, imagem gerada ou blob URL.
Erros usam JSON { success: false, message }; rate limit local pode acrescentar code, limit, remaining e reset_at. Nunca interprete erro JSON como imagem.

Exemplos de integração

# Substitua pelos dados reais da instalação e recibo do runtime autorizado.
# Preserve GLASSES_OPERATION_ID e os mesmos campos em reenvios.
curl --fail-with-body --max-time 125 \
  "https://app.provei.ai/api/v2/widget-glasses/try-on" \
  -H "Origin: https://loja.com.br" \
  -H "Idempotency-Key: ${GLASSES_OPERATION_ID}" \
  -F "[email protected];type=image/jpeg" \
  -F "reference_url=https://loja.com.br/produto/oculos-preto" \
  -F "product_id=${GLASSES_PRODUCT_ID}" \
  -F "user_id=${GLASSES_OWNER_ID}" \
  -F "identity_receipt=${WIDGET_IDENTITY_RECEIPT}" \
  --output resultado.bin

Erros possíveis

Status	Mensagem	O que fazer
`400`	Content-Length declarado inválido, body ausente/ilegível ou Idempotency-Key ausente/acima de 255 caracteres.	Envie um body multipart legível e uma chave opaca única por composição. Um multipart que falhe na interpretação do formData pode resultar em 500.
`401`	Guard: identity_receipt inválido/ausente; serviço upstream: chave de API inválida, revogada ou indisponível no servidor.	Recarregue o runtime autorizado para emitir/renovar o recibo; a API key é resolvida apenas no servidor.
`402`	O serviço upstream confirmou créditos insuficientes.	Confirme o saldo de créditos da conta antes de iniciar uma nova composição.
`403`	Guard: origem não autorizada para o owner; serviço upstream: assinatura inativa.	Confira a origem cadastrada e o estado da assinatura; não tente substituir o guard por uma API key no browser.
`404`	Acesso glasses ausente, produto inexistente/inativo/de outro owner ou tipo, ou reference_url não canônica.	Confirme provisionamento glasses e produto ativo do owner; use a URL canônica cadastrada.
`413`	Corpo multipart completo acima de 5 MiB.	Normalize a selfie inteira para até 4 MiB, sem recortar o rosto, e reduza o overhead multipart.
`422`	Campo inválido: imagem ausente/incompatível, reference_url vazia, UUID do produto/owner inválido ou identity_receipt acima de 4096 caracteres.	Corrija os campos validados do multipart e reenvie a requisição.
`429`	Visitante bloqueado por rate limit. O payload inclui `code: "VISITOR_RATE_LIMITED"`.	Leia Retry-After e os headers X-RateLimit-* antes de permitir nova tentativa.
`500`	Erro interno ao interpretar a requisição ou preparar a composição.	Confira o multipart e tente novamente; não trate esse retorno como confirmação de que a composição foi processada.
`503`	O serviço de composição está temporariamente indisponível.	Aguarde alguns instantes antes de reenviar.
`504`	O processamento excedeu o tempo limite de 120 segundos.	Timeout não prova ausência de efeito. Reenvie a mesma operação com a mesma chave e payload; não inicie nova geração automaticamente.
`409`	Conflito de idempotência/admissão retornado pelo serviço de composição.	Não contorne o conflito trocando a chave; mantenha a identidade da operação e confira o payload.

Composição de Móveis

Móveis

Recebe a foto do ambiente, a URL de referência e o recibo emitido pelo runtime autorizado. O servidor encontra o tipo canônico furniture, revestimento ou pisos pela URL; o cliente não escolhe product_type.

Endpoint

POSThttps://app.provei.ai/api/v2/widget/compose

Requisição

Estas são rotas públicas mediadas pelo widget. O navegador não envia API key; cada rota valida a origem e aplica suas próprias verificações de identidade e produto antes de processar.

Clientes cURL, Node.js e Python devem informar essa mesma origem explicitamente (por exemplo, Origin: https://loja.com.br); uma origem não autorizada é rejeitada antes da composição.

Headers obrigatórios: Origin (origem autorizada) e Idempotency-Key. Não envie API key, product_type nem imagens de referência do catálogo.

Campos (form-data)

Campo	Tipo	Obrigatório	Descrição
`environment_image`	file	Sim	Foto do ambiente em PNG, JPEG ou WebP com no máximo 4 MiB. O mesmo campo serve para Móveis, Revestimentos e Pisos.
`reference_url`	string (HTTPS URL)	Sim	URL da página do produto ativo. O servidor normaliza a URL, encontra uma única linha do catálogo e resolve o modo provisionado.
`user_id`	string (UUID)	Sim	UUID do perfil usado na instalação do widget. Não concede acesso sozinho: origem autorizada, ownership e recibo também são verificados.
`identity_receipt`	string	Sim	Recibo de identidade assinado emitido ou renovado pelo runtime do widget autorizado. Não envie uma API key.
`mask_image`	file (PNG)	Não	Máscara PNG opcional apenas para o modo furniture (Móveis). Para Revestimentos e Pisos, o servidor rejeita este campo.
`visitor_id`	string	Não	Identificador opcional de visitante para o rate limit.
`session_id`	string	Não	Identificador opcional de sessão para o rate limit.
`customer_identity_hash`	string	Não	Hash opcional de identidade persistente para o rate limit.

Resposta de sucesso

201Imagem binária com Content-Type propagado do serviço de composição (image/png, image/jpeg ou image/webp).

Observações

Para furniture (Móveis), mask_image é opcional e deve ser PNG; para revestimento e pisos, uma máscara é rejeitada.
visitor_id, session_id e customer_identity_hash são opcionais e ajudam o controle de rate limit.
A URL deve encontrar uma única linha ativa e um modo Home provisionado. Correspondência ausente ou ambígua retorna erro; referências do catálogo são resolvidas no servidor.
Erros de composição 400, 401, 402, 409, 413, 422, 500, 503 e 504 usam JSON `{ success: false, message: string }`; o rate limit local pode acrescentar code, limit, remaining e reset_at. O guard pode responder 403/404 antecipadamente com `{ error: string }`.

Exemplos de integração

curl -X POST https://app.provei.ai/api/v2/widget/compose \
  -H "Origin: https://loja.com.br" \
  -H "Idempotency-Key: home-operation-unique-001" \
  -F "environment_image=@/caminho/foto-ambiente.jpg" \
  -F "reference_url=https://loja.com.br/produto/sofa-marrom" \
  -F "user_id=550e8400-e29b-41d4-a716-446655440000" \
  -F "identity_receipt=SIGNED_WIDGET_RECEIPT" \
  -F "mask_image=@/caminho/mascara.png" \
  --output resultado.bin

Erros possíveis

Status	Mensagem	O que fazer
`400`	Body/multipart inválido, ou Idempotency-Key ausente ou acima de 255 caracteres.	Envie multipart/form-data legível e uma chave opaca única por composição.
`401`	Guard: identity_receipt inválido/ausente; serviço upstream: chave de API inválida, revogada ou indisponível no servidor.	Recarregue o runtime autorizado para obter um recibo válido; a API key permanece no servidor.
`402`	O serviço upstream confirmou créditos insuficientes.	Confirme o saldo de créditos da conta antes de iniciar uma nova composição.
`403`	Guard: origem não autorizada para o owner; serviço upstream: assinatura inativa.	Confirme a origem registrada e o estado da assinatura antes de reenviar.
`404`	Nenhum produto ativo corresponde à URL normalizada, ou o modo Home não está provisionado.	Use a URL canônica do produto e confirme o provisionamento de Móveis, Revestimentos ou Pisos.
`409`	Mais de um produto ativo corresponde à URL normalizada.	Corrija a duplicidade do catálogo antes de gerar a composição.
`413`	O corpo multipart completo excede o limite permitido de 9 MiB.	Reduza a imagem do ambiente e remova campos desnecessários antes de reenviar.
`422`	ID do owner ausente, imagem/referência inválida, imagem acima de 4 MiB, imagem de referência indisponível ou máscara incompatível com o modo.	Corrija o multipart; para Revestimentos e Pisos, não envie mask_image.
`429`	Visitante bloqueado por rate limit. O payload inclui `code: "VISITOR_RATE_LIMITED"`.	Leia Retry-After e os headers X-RateLimit-* antes de permitir nova tentativa.
`500`	Ocorreu um erro temporário.	Registre o contexto e tente novamente conforme sua política.
`503`	O serviço de composição está temporariamente indisponível.	Aguarde alguns instantes antes de reenviar.
`504`	O processamento excedeu o tempo limite de 120 segundos.	Configure o cliente para aguardar até 120 segundos e trate a operação como uma nova tentativa.

Guia de Medidas

Medidas

Consulta as capacidades de medidas para o produto da URL. A rota retorna JSON e não recebe body, multipart, API key ou Idempotency-Key.

Endpoint

GEThttps://app.provei.ai/api/v2/widget-measurements/match

Requisição

Estas são rotas públicas mediadas pelo widget. O navegador não envia API key; cada rota valida a origem e aplica suas próprias verificações de identidade e produto antes de processar.

Clientes cURL, Node.js e Python devem informar essa mesma origem explicitamente (por exemplo, Origin: https://loja.com.br); uma origem não autorizada é rejeitada antes da composição.

GET com `userId` (UUID), `url` (URL absoluta) e `Origin` (origem autorizada). Nenhum body, multipart ou header de idempotência.

Parâmetros (query string)

Campo	Tipo	Obrigatório	Descrição
`userId`	string (UUID)	Sim	UUID do perfil proprietário. A rota verifica origem, ownership e se há pelo menos uma ação de medidas provisionada.
`url`	string (URL)	Sim	URL da página do produto. Query string, hash e a barra final são normalizados antes do matching.

Resposta de sucesso

200JSON em união de capacidade: `eligible: true` expõe os booleanos de ação e pode trazer grade/`sizes`; `eligible: false` traz `reason`.

Observações

Resposta 200 eligible: true expõe as capacidades e pode omitir `comparisonSizeLabels`, `recommendationAvailability` e `measurementGrid` quando não aplicáveis; `sizes` pode ser vazio.
Resposta 200 eligible: false traz `reason`. Erros 400 usam `{ error, details }`; guard e erro interno usam `{ error }`.

Exemplos de integração

curl "https://app.provei.ai/api/v2/widget-measurements/match?userId=550e8400-e29b-41d4-a716-446655440000&url=https%3A%2F%2Floja.com.br%2Fproduto%2Fcamiseta-azul" \
  -H "Origin: https://loja.com.br"

Erros possíveis

Status	Mensagem	O que fazer
`200 eligible: false`	A resposta de capacidade não encontrou uma ação utilizável para esta URL.	Leia `reason`: "service_disabled", "no_measurements", "product_inactive", "not_a_product_page", "no_comparable_sizes", "measurement_basis_unclassified", "display_only_table" ou "insufficient_common_dimensions".
`200 eligible: true`	O produto tem pelo menos uma capacidade disponível; `sizes` pode ser vazio quando só há visualização ou recomendação.	Use os booleanos `canShowSizeGuide`, `canRecommendSize`, `canVisualizeRecommendedSize` e `canCompareSizes` para escolher a ação.
`400`	Parâmetros inválidos: userId ausente/inválido ou url ausente/inválida na query string.	Envie um UUID válido em userId e uma URL absoluta codificada em url.
`403`	A origem da página não está autorizada para o owner.	Faça a chamada a partir de uma origem registrada para o perfil.
`404`	O perfil ou uma ação de medidas não está provisionado para esta consulta.	Confirme o UUID e o provisionamento de Tamanho Ideal, Guia de Medidas ou Comparar tamanhos.
`500`	Erro interno ao buscar configuração ou correspondência.	Tente novamente; o endpoint não expõe detalhes internos no payload.

Transporte e respostas

Timeout de 120 segundos: esse limite e a leitura como binário valem somente para os POSTs de composição Fashion, Óculos e Home. Configure o cliente HTTP para aguardar 120 segundos e leia a resposta comoarrayBuffer, bytes ou blob.
Medidas retorna JSON: o GET não recebe multipart, body ou Idempotency-Key. Uma resposta elegível pode trazer grade e sizes vazio quando a capacidade disponível é apenas de visualização/recomendação.
Rate limit: nas composições, envie visitor_id, session_id ou customer_identity_hash quando disponíveis e respeite Retry-After/X-RateLimit-* em 429.
Origem e identidade: o runtime autorizado emite ou renova o recibo; não substitua esse fluxo por API key ou por uma chamada independente do widget.

Referência interativa OpenAPI

Abaixo está a referência interativa carregada de /api/reference. Ela inclui as composições e leituras do widget deste guia e também os caminhos legados intencionalmente expostos para clientes e produtos; os conjuntos de endpoints não são idênticos.

Ver JSON OpenAPI Abrir tela cheia

Onde encontrar mais detalhes

Consulte /api/docs para explorar a referência interativa. Este guia documenta as rotas do widget e seus contratos mediados pelo runtime; a referência também mantém as APIs legadas de clientes e produtos porque elas são expostas intencionalmente.