# Provy — API & Platform Reference (llms-full.txt)

> Documentação completa do Provy para agentes de IA, LLMs e integrações.
> Atualizado: 5 de agosto de 2026
> Versão: 1.0

---

## Visão Geral

Provy é uma plataforma de try-on virtual que usa inteligência artificial para
vestir roupas em fotos de pessoas ou manequins. O serviço funciona via API REST
e interface web.

### Como funciona

1. **B2C (Try-On Direto)**: O usuário envia uma foto de corpo inteiro + foto da
   roupa. A IA gera uma imagem fotorrealista da pessoa vestindo a peça.
   Custo: 3 créditos. Motor: Black Forest Labs VTO (~8s).

2. **B2B (Catálogo)**: O usuário cria manequins de IA (avatares) e envia fotos
   das peças. A IA veste as peças nos manequins para criar fotos de catálogo.
   Custo: 2 créditos por foto. Motor: BFL VTO (~8s).

3. **Avatares**: Geração de manequins fotorrealistas por prompt de texto.
   Custo: 1 crédito. Motor: NVIDIA NIM (~4s) ou Krea2 Turbo local (~27s).

### Arquitetura

```
Navegador → Cloudflare DNS → Cloudflare Tunnel → Nginx → Next.js (frontend)
                                     ↓
                              FastAPI (backend REST + Celery worker)
                                     ↓
                              PostgreSQL / Redis / S3 (MinIO ou Cloudflare R2)
                                     ↓
                              NVIDIA NIM (avatar) / BFL VTO (try-on)
```

---

## Autenticação

### Login com Google OAuth 2.0

POST /api/auth/google
```
Authorization: Bearer <google_id_token>
Response: { access_token: "jwt_token", token_type: "bearer" }
```

### Login com email/senha

POST /api/auth/login
```
Body: { username: "...", password: "..." }
Response: { access_token: "jwt_token", token_type: "bearer" }
```

### Registro

POST /api/auth/register
```
Body: { email: "...", password: "...", name: "..." }
```

### Todas as rotas autenticadas requerem:

```
Authorization: Bearer <jwt_token>
```

---

## API Endpoints

### Try-On B2B (Catálogo)

POST /api/garments/tryon

```
Headers:
  Authorization: Bearer <token>

Body (multipart/form-data):
  garment_image: file (jpg, png, webp — max 10MB)
  mannequin_id: uuid (opcional, usa default se não informado)
  prompt: string (opcional, instrução customizada)

Response 200:
  {
    "job_id": "uuid",
    "status": "processing",
    "estimated_time": 8
  }

Custo: 2 créditos
```

### Try-On B2C (Direto)

POST /api/garments/direct-tryon

```
Body (multipart/form-data):
  garment_image: file
  person_photo: file (foto de corpo inteiro, max 10MB)
  prompt: string (opcional)

Custo: 3 créditos
```

### Gerar Avatar

POST /api/avatars/generate

```
Body (JSON):
  {
    "prompt": "Uma mulher brasileira de 25 anos, cabelo preto, corpo atlético...",
    "style": "photographic",
    "aspect_ratio": "9:16"
  }

Estilos disponíveis:
  photographic, female, male, editorial, streetwear

Custo: 1 crédito
```

### Listar Avatares

GET /api/avatars

```
Response: [ { id, name, image_url, created_at, style } ]
```

### Listar Jobs

GET /api/jobs

```
Query: ?type=tryon|avatar|direct-tryon&status=completed|failed|processing
Response: [ { id, type, status, prompt, image_urls, created_at } ]
```

### Consultar Job

GET /api/jobs/{job_id}
GET /api/jobs/{job_id}/status

### Créditos e Pagamentos

GET /api/billing/credits
```
Response: { balance: 50, packs: [ { id, credits, price, active } ] }
```

POST /api/billing/checkout
```
Body: { pack_id: "uuid" }
Response: { checkout_url: "https://checkout.stripe.com/..." }
```

### Health Check

GET /api/health
```
Response: { status: "ok", engines: { nim: true, bfl: true, comfy: true } }
```

---

## Preços

| Pacote | Créditos | Preço (BRL) | Stripe Price ID |
|---|---|---|---|
| Teste | 5 | R$ 7,00 | price_1Ri5LyL8fs0iCsHieDfK8r1P |
| Básico | 10 | R$ 15,00 | price_1Ri5NzL8fs0iCsHiPLrBX3En |
| Plus | 50 | R$ 40,00 | price_1Ri5OdL8fs0iCsHiV5edxq1E |
| Pro | 200 | R$ 99,00 | price_1Ri5OtL8fs0iCsHiOOf52iIB |

- Pagamento via Stripe (cartão de crédito, débito, Pix)
- Créditos não expiram

---

## Produto de Jobs

### Estados do Job

- `pending`: Aguardando processamento (na fila do Celery)
- `processing`: Em execução na worker
- `completed`: Finalizado com sucesso (imagens disponíveis)
- `failed`: Erro (créditos são reembolsados)

### Estrutura do Job

```json
{
  "id": "uuid",
  "type": "tryon | avatar | direct-tryon | edit",
  "status": "pending | processing | completed | failed",
  "prompt": "string",
  "options": { "style": "...", "aspect_ratio": "...", "mannequin_id": "..." },
  "input_urls": ["https://..."],
  "image_urls": ["https://..."],
  "error": "string | null",
  "created_at": "ISO 8601",
  "completed_at": "ISO 8601 | null",
  "user_id": "uuid"
}
```

---

## Segurança

### Content Moderation
- Todas as imagens passam por filtro de conteúdo (NSFW, rosto real, menores)
- Guardrails: bloqueio de nudez, conteúdo sexual, menores de idade
- Fotos de rosto real não são armazenadas

### Compliance
- LGPD — dados armazenados no Brasil
- Senhas com hash bcrypt + salt
- JWT com expiração (access token 7 dias)
- CSRF protection via Redis state parameter (OAuth)
- Rate limiting por IP nos endpoints públicos

---

## Sitemap

```
/                    Landing page
/direct-tryon        Try-on B2C (foto própria)
/tryon               Try-on B2B (manequins)
/avatars             Gerador de avatares
/history             Histórico do usuário
/dashboard           Painel de créditos
/admin               Admin (superuser only)
/login               Login
/register            Registro
/faq                 Perguntas frequentes
/privacy             Política de privacidade
/terms               Termos de uso
```

---

## Contato

- Email: suporte@provy.app.br
- Site: https://provy.app.br
- Suporte: via chat no site
- GitHub: https://github.com/acostaapk/provy