# VEX-ASR

VEX-ASR, tecnologia [AUXYRA](https://auxyra.com.br/) expõe ASR em português por HTTP.

Endpoint público:

```text
POST https://asr.auxyra.com.br/v1
Header: X-VEX-Token: <token>
Content-Type: multipart/form-data
```

Não há endpoints públicos de status, documentação automática ou descoberta.

## Campos

- `file`: áudio `.wav`, `.mp3`, `.webm`, `.opus` ou `.ogg`. WAV PCM em uma taxa suportada preserva sua taxa original, que é informada diretamente ao reconhecedor. Canais e larguras PCM suportados são convertidos em memória. Os demais formatos e WAVs que exigem conversão usam `ffmpeg` para mono PCM16/16 kHz.
- `model`: `VEX-ASR-8`, `VEX-ASR-16`, `int8` ou `int16`.
- `choices`: opcional. JSON array de palavras ou frases possíveis.

O dicionário administrativo é aplicado ao resultado do recognizer antes da montagem da resposta. Portanto, `raw_asr` já contém as correções cadastradas. Quando `choices` não é enviado, `asr` é sempre igual a `raw_asr`. Quando `choices` é enviado, `asr` retorna o item da lista mais parecido com `raw_asr`.

## Resposta

```json
{
  "request_id": "3a0b5d17-fb1e-4d64-9f98-4c2d36b19b72",
  "model": "VEX-ASR-8",
  "raw_asr": "nao quero",
  "asr": "nao",
  "matched_choice": true,
  "choice_similarity": 0.61,
  "confidence": "high",
  "elapsed_ms": 123
}
```

- `raw_asr`: resultado do recognizer após a correção de nomes próprios e termos de domínio pelo dicionário administrativo.
- `asr`: igual ao `raw_asr` sem `choices`; com `choices`, contém a melhor opção da lista.
- `matched_choice`: `true` quando `choices` foi usado.
- `choice_similarity`: proximidade entre `raw_asr` e a opção escolhida; `null` sem `choices`.
- `confidence`: confiança do recognizer, sem penalização pelo dicionário ou por `choices`.
- `elapsed_ms`: tempo apenas do `recognize()` do ASR, sem incluir upload, autenticação, conversão de áudio ou tempo do cliente HTTP.

## Exemplos

WAV:

```bash
curl -X POST "https://asr.auxyra.com.br/v1" \
  -H "X-VEX-Token: SEU_TOKEN" \
  -F "model=VEX-ASR-8" \
  -F "file=@audio.wav"
```

MP3:

```bash
curl -X POST "https://asr.auxyra.com.br/v1" \
  -H "X-VEX-Token: SEU_TOKEN" \
  -F "model=VEX-ASR-16" \
  -F "file=@audio.mp3"
```

Com lista de opções:

```bash
curl -X POST "https://asr.auxyra.com.br/v1" \
  -H "X-VEX-Token: SEU_TOKEN" \
  -F "model=int8" \
  -F "choices=[\"sim\",\"nao\",\"talvez\"]" \
  -F "file=@resposta.wav"
```

## Erros

- `401`: token ausente ou inválido.
- `403`: licença sem permissão para o modelo ou inativa.
- `409`: limite de execução concorrente atingido.
- `429`: limite total de uso atingido.
- `422`: payload inválido, áudio inválido ou `choices` inválido.
- `503`: modelo solicitado não está carregado (`modelo nao disponivel`) ou houve falha no runtime.