# API de Voz da Agência Papo

API para **gerar fala com vozes clonadas** (incluindo a voz da Jéssica, da Papo) e **transcrever áudio e vídeo em português**. Roda numa GPU própria da Papo, com o motor VoiceStudio.

Esta página é pública e não contém segredos. Todas as rotas abaixo exigem a chave da API.

## Autenticação

- **URL base:** `https://desktop-7rmetgc.tail6b7885.ts.net`
- **Cabeçalho obrigatório em toda chamada:** `Authorization: Bearer <CHAVE>`
- A chave **não está aqui**. Ela é entregue separadamente e deve ficar numa variável de ambiente, por exemplo `PAPO_VOZ_API_KEY`. Nunca coloque a chave em código, em log ou em URL.

## Rotas disponíveis

Só existem estas quatro. Qualquer outra responde 403.

| Método | Rota | Para quê |
|---|---|---|
| POST | `/generate` | Gerar fala (retorna WAV) |
| POST | `/v1/audio/transcriptions` | Transcrever áudio ou vídeo (formato compatível com a API da OpenAI) |
| GET | `/profiles` | Listar as vozes disponíveis |
| GET | `/health` | Ver se o serviço está no ar |

## Gerar fala: `POST /generate`

O corpo vai como `multipart/form-data`.

| Campo | Obrigatório | Valor |
|---|---|---|
| `text` | sim | Texto a falar, em português. |
| `profile_id` | sim | Id da voz. **Jéssica (Papo) = `1508711b`**. Outras vozes: ver `GET /profiles`. |
| `engine` | **sim, sempre `voxcpm2`** | O motor padrão do servidor não tem licença comercial. Sempre envie `engine=voxcpm2`. |
| `effect_preset` | não | `raw` (sem tratamento, recomendado), `broadcast`, `podcast`, `warm`, `cinematic`. |
| `seed` | não | Inteiro. A mesma seed com o mesmo texto gera o mesmo áudio. |
| `speed` | não | `1.0` é o normal. |

**Resposta:** `200` com o arquivo WAV no corpo (`audio/wav`). Cabeçalhos úteis:
- `X-Gen-Time`: segundos de processamento.
- `X-Audio-Duration`: duração do áudio em segundos.
- `X-Audio-Id`: id interno do áudio.

**Tempo:** ~25 a 55 s para uma frase de ~8 s. A primeira chamada depois que o servidor liga pode levar ~2 min, porque carrega o modelo. Use timeout de **pelo menos 5 minutos** e mande uma frase ou parágrafo por chamada. Para textos longos, divida em partes e junte os WAVs.

```bash
curl -X POST "https://desktop-7rmetgc.tail6b7885.ts.net/generate" \
  -H "Authorization: Bearer $PAPO_VOZ_API_KEY" \
  -F "text=Oi, pessoal! Hoje a gente vai falar sobre como transformar a visita do técnico em uma propaganda da sua marca." \
  -F "profile_id=1508711b" \
  -F "engine=voxcpm2" \
  -F "effect_preset=raw" \
  --max-time 600 \
  -o fala.wav
```

```python
import os, requests
r = requests.post(
    "https://desktop-7rmetgc.tail6b7885.ts.net/generate",
    headers={"Authorization": f"Bearer {os.environ['PAPO_VOZ_API_KEY']}"},
    data={"text": "Oi, pessoal!", "profile_id": "1508711b",
          "engine": "voxcpm2", "effect_preset": "raw"},
    timeout=600,
)
r.raise_for_status()
open("fala.wav", "wb").write(r.content)
```

## Transcrever: `POST /v1/audio/transcriptions`

O corpo vai como `multipart/form-data`.

| Campo | Obrigatório | Valor |
|---|---|---|
| `file` | sim | Arquivo de áudio ou vídeo (mp3, wav, m4a, flac, mp4...). Máximo 500 MB. |
| `model` | sim | `deepdml/faster-whisper-large-v3-turbo-ct2` |
| `language` | recomendado | `pt` |

**Resposta:** JSON `{"text": "..."}`. Velocidade: ~30 s de áudio em ~5 s.

```bash
curl -X POST "https://desktop-7rmetgc.tail6b7885.ts.net/v1/audio/transcriptions" \
  -H "Authorization: Bearer $PAPO_VOZ_API_KEY" \
  -F "file=@aula.mp4" \
  -F "model=deepdml/faster-whisper-large-v3-turbo-ct2" \
  -F "language=pt" \
  --max-time 1800
```

## Listar vozes: `GET /profiles`

Retorna uma lista JSON. Use os campos `id` e `name`.

```bash
curl -H "Authorization: Bearer $PAPO_VOZ_API_KEY" "https://desktop-7rmetgc.tail6b7885.ts.net/profiles"
```

## Erros

| Código | Significado | O que fazer |
|---|---|---|
| 401 | Chave ausente ou errada | Confira o cabeçalho `Authorization: Bearer <CHAVE>`. |
| 403 | Rota não liberada | Use só as quatro rotas acima. |
| 502 / 503 / timeout | Servidor de voz desligado ou reiniciando | Espere 2 a 3 minutos e tente de novo. O servidor é um PC da Papo e pode estar reiniciando. |
| 422 | Campo faltando ou inválido | Confira os campos obrigatórios. |

## Regras de uso

- Use as vozes clonadas **só em conteúdo da Papo e dos clientes da Papo**, que é o que a Jéssica autorizou.
- Não tente outras rotas nem outros motores: só `engine=voxcpm2` tem licença comercial.
- Uma chamada por vez é o ideal. A GPU processa uma geração por vez, e as outras ficam na fila.