---
url: https://docs.ouvixpro.ai/guia/audio.md
description: >-
  Como obter o áudio de um atendimento: GET /v1/atendimentos/{id}/audio, sempre
  WAV, só o trecho da conversa, com dados pessoais em silêncio.
---

# Áudio

Cada atendimento pode ser ouvido. `GET /v1/atendimentos/{id}/audio` devolve exatamente o que o botão de play do painel reproduz: só o trecho da conversa, em um único arquivo WAV, com documento e nome completo já em silêncio.

A API não expõe arquivos de gravação, nomes de arquivo nem posições internas. O único identificador que você precisa é o `id` do atendimento.

## Como chegar ao áudio

Todo atendimento traz um bloco `audio`:

```json
{
  "id": "2026-10-06:atend_27",
  "horario": "13:16:41",
  "resumo": "Visitante interessada no quadrimestral…",
  "audio": {
    "url": "/v1/atendimentos/2026-10-06:atend_27/audio",
    "duracao_s": 324,
    "partes": 1
  }
}
```

| Campo | O que é |
| --- | --- |
| `url` | Caminho relativo à base da API. |
| `duracao_s` | Duração do áudio entregue, em segundos. |
| `partes` | Quantos recortes foram colados em sequência (a conversa pode atravessar a troca de arquivo da gravação). Você sempre recebe um único WAV. |

`audio` é `null` quando o atendimento não tem trecho de gravação.

## Chamada

Use o mesmo `Authorization`, `Id_unidade`, `de`, `ate` (e `turno`, se usou) da chamada que devolveu o atendimento.

::: code-group

```bash [cURL]
curl -o atendimento.wav \
  "https://api.ouvixpro.ai/v1/atendimentos/2026-10-06:atend_27/audio?Id_unidade=375&de=2026-10-06&ate=2026-10-06" \
  -H "Authorization: Bearer $OUVIX_API_KEY"
```

```python [Python]
import os
import urllib.request

url = (
    "https://api.ouvixpro.ai/v1/atendimentos/2026-10-06:atend_27/audio"
    "?Id_unidade=375&de=2026-10-06&ate=2026-10-06"
)
req = urllib.request.Request(url, headers={"Authorization": f"Bearer {os.environ['OUVIX_API_KEY']}"})
with urllib.request.urlopen(req) as res, open("atendimento.wav", "wb") as f:
    f.write(res.read())
```

```js [Node.js]
import { writeFile } from 'node:fs/promises'

const base = 'https://api.ouvixpro.ai'
const atendimento = { audio: { url: '/v1/atendimentos/2026-10-06:atend_27/audio' } } // vindo do /v1/painel
const res = await fetch(`${base}${atendimento.audio.url}?Id_unidade=375&de=2026-10-06&ate=2026-10-06`, {
  headers: { Authorization: `Bearer ${process.env.OUVIX_API_KEY}` },
})
if (!res.ok) throw new Error(`HTTP ${res.status}`)
await writeFile('atendimento.wav', Buffer.from(await res.arrayBuffer()))
```

:::

## Resposta

| Cabeçalho | Valor |
| --- | --- |
| `Content-Type` | `audio/wav` — PCM 16 bits, pronto para tocar em qualquer player. |
| `Content-Disposition` | `inline; filename="atendimento-<id>.wav"` |
| `X-Audio-Duracao-S` | Duração em segundos. |
| `X-Audio-Partes` | Número de recortes colados. |
| `Cache-Control` | `private, max-age=300` |

O formato é sempre o mesmo, independentemente de como a unidade grava. A API recorta e converte no servidor.

## Dados pessoais

As janelas em que foram ditos documento ou nome completo chegam em silêncio, com a mesma regra do player do painel. Os textos (`resumo`, `evidencia`, `fato`…) já vêm mascarados. Não há nada a tratar do seu lado.

## Desempenho

A primeira chamada para um atendimento busca a gravação no armazenamento e pode levar alguns segundos, proporcional ao tamanho do bloco de áudio. Chamadas seguintes para a mesma gravação são rápidas. Para catálogos grandes, baixe sob demanda (quando alguém clicar em ouvir) em vez de pré-carregar o dia inteiro.

## Erros relacionados

| HTTP | `code` | Causa |
| --- | --- | --- |
| 404 | `atendimento_nao_encontrado` | O `id` não está nessa unidade e nesse período (confira `Id_unidade`, `de`, `ate` e `turno`). |
| 404 | `audio_indisponivel` | O atendimento não tem trecho de gravação (`audio` é `null`). |
| 502 | `audio_indisponivel` | O armazenamento de áudio não respondeu ou o recorte falhou. Tente novamente em instantes. |
| 410 | `endpoint_removido` | Chamada ao antigo `/v1/audio`. Use `/v1/atendimentos/{id}/audio`. |