# Áudio



<ToolHero tool="audio" />

## Visão geral

Toda operação de áudio é **assíncrona** e cobrada na hora:

1. `POST` na operação → **202 Accepted** com `job_id`, `status: pending` e `poll_after_seconds`.
2. Um worker processa em background.
3. Consulte `GET /jobs/{id}` até o `status` ser `completed` (ou `failed`, e a cobrança é devolvida). Pronto, a resposta traz o resultado e um **link assinado** que expira.

Os mesmos casos de uso estão no [MCP](/agentes-de-ia) como as tools `audio_*` (toolset `audio`); a REST e o MCP compartilham formatos, preços e limites.

<Callout type="warn" title="Cobrança ao aceitar o job">
  Os créditos são debitados quando o job é aceito. Falha do motor, etapa que não foi necessária e preço calculado a mais são **devolvidos** automaticamente; nada é cobrado se o pedido for recusado antes (`audio.too_long`, `audio.price_above_max`…).
</Callout>

<EndpointList tool="audio" />

## Entrada do áudio

As operações que recebem um áudio pedem **exatamente um** destes campos:

| Campo          | O que é                                                                                                                                                                    |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `audio_url`    | URL pública `http(s)` do arquivo. Endereços de rede interna ou privada são recusados (`audio.input_blocked`) e o download tem limite de <Limit name="audioFetchTimeout" /> |
| `audio_base64` | O áudio inline em base64, até <Limit name="audioInlineMax" /> decodificado                                                                                                 |
| `file_id`      | Id de um arquivo de áudio já enviado para a conta                                                                                                                          |

Formatos aceitos: mp3, wav, ogg, m4a, flac e webm. O limite é de <Limit name="audioMaxDuration" /> de áudio e <Limit name="audioInputMax" /> por arquivo por chamada. Em `summarize` e `translate` você pode mandar, no lugar do áudio, o `job_id` de uma transcrição já pronta: a transcrição é reaproveitada e só a operação nova é cobrada.

Todas as rotas de operação aceitam `max_credits` (em unidades; 10.000 unidades = 1 crédito): se o preço passar disso, o pedido é recusado com `audio.price_above_max` e nada é cobrado. O header `Idempotency-Key` torna a repetição segura: a mesma chave devolve o primeiro job em vez de cobrar de novo.

## Custos

<PricingTable tool="audio" group="speech-to-text" />

<PricingTable tool="audio" group="text-to-speech" />

<PricingTable tool="audio" group="processing" />

<PricingTable tool="audio" group="revoice" />

O "minuto iniciado" arredonda para cima. Um áudio cuja duração não dá para ler do cabeçalho é cobrado pelo teto de <Limit name="audioMaxDuration" /> e a diferença volta no fim do job. Consultas aos jobs seguem a [franquia diária](/cobranca-e-limites#franquia-diaria). O preço exato de uma chamada sai do [dry-run](#dry-run).

### Dry-run

Com `?dry_run=true` na query (nas rotas de áudio é a query, não o header `X-Dry-Run`), as operações pagas respondem `200` com o preço e não cobram nem criam job:

```json
{
  "success": true,
  "data": {
    "service_code": "audio_transcribe_minute",
    "units": 3,
    "rate": 15000,
    "total_units": 45000,
    "duration_ms": 125000,
    "duration_known": true,
    "parts": [{ "service_code": "audio_transcribe_minute", "units": 3, "rate": 15000, "total": 45000 }]
  }
}
```

`rate` e `total_units` estão em unidades (10.000 unidades = 1 crédito); `parts` detalha cada serviço cobrado. Em `speak`, o orçamento traz `chars`, `voice`, `language` e `format`.

## Operações

### Transcrever áudio

<Endpoint id="audio.transcribe" example={{ body: `{ "audio_url": "https://example.com/episodio-12.mp3", "format": "text", "language": "pt" }` }}>
  `format`: `text` (padrão), `srt` ou `vtt`. `language` é opcional (código ISO 639-1; sem ele o idioma é detectado). Com `diarize: true` (ou `speakers`, o número conhecido de falantes) cada trecho diz quem falou (`Speaker 1`, `Speaker 2`…), por um adicional por minuto.
</Endpoint>

### Gerar fala a partir de texto

<Endpoint id="audio.speak" example={{ body: `{ "text": "Olá! Seu pedido saiu para entrega.", "voice": "pt-BR-dora", "format": "mp3", "speed": 1 }` }}>
  `text` aceita até <Limit name="audioTtsCharsMax" /> caracteres (acima disso o pedido é recusado antes de cobrar). `voice` é um id do [catálogo](#vozes-do-catalogo) ou uma voz clonada da conta (`vc_…`, [só no MCP](#vozes-clonadas)); sem `voice`, vale a voz padrão do `language` (`pt-BR`, `en-US`, `en-GB`, `es-ES`, `fr-FR` ou `it-IT`). `format`: `mp3` (padrão) ou `wav`; `speed`: 0,5 a 2.
</Endpoint>

### Listar as vozes

<Endpoint id="audio.voices" example={{ query: { language: 'pt-BR' } }}>
  Catálogo fechado de vozes do `speak` e do `revoice`. `language` filtra por idioma. Não é cobrado.
</Endpoint>

### Gerar efeito sonoro ou música

<Endpoint id="audio.generate" example={{ body: `{ "kind": "effect", "prompt": "porta de madeira rangendo devagar", "duration_seconds": 4, "format": "mp3" }` }}>
  `kind`: `effect` (1 a <Limit name="audioEffectMax" />, padrão 5 s) ou `music` (instrumental, 1 a <Limit name="audioMusicMax" />, padrão 30 s). O áudio sai com exatamente `duration_seconds`. Não há fala nem canto, e descrições que imitam artistas, vozes ou obras existentes são recusadas antes de cobrar (`audio.input_blocked`). `seed` repete um som: o mesmo pedido com a `seed` que um job informou gera o mesmo áudio. A geração leva alguns minutos.
</Endpoint>

### Analisar áudio

<Endpoint id="audio.analyze" example={{ body: `{ "audio_url": "https://example.com/episodio-12.mp3" }` }}>
  Sem IA de transcrição: devolve em `analysis` a duração, o formato e codec, bitrate, taxa de amostragem, canais, loudness integrado (LUFS), pico real, faixa de loudness, os trechos de silêncio (`start_ms`/`end_ms`) e o idioma falado. Preço fixo por chamada.
</Endpoint>

### Converter ou normalizar áudio

<Endpoint id="audio.convert" example={{ body: `{ "audio_url": "https://example.com/episodio-12.wav", "format": "mp3", "bitrate_kbps": 128, "normalize": true }` }}>
  `format` (obrigatório): `mp3`, `wav`, `ogg`, `m4a` ou `flac`. `bitrate_kbps` (32 a 320) vale só para formatos com perda. `normalize: true` nivela o loudness em -14 LUFS (padrão de streaming, -1,5 dBTP). As tags de metadados são removidas.
</Endpoint>

### Resumir áudio

<Endpoint id="audio.summarize" example={{ body: `{ "job_id": "5b1d8c2e-6f4a-4e7b-9c3d-2a8e1f0b7d64", "output_language": "pt-BR" }` }}>
  Mande o `job_id` de uma transcrição pronta (o áudio não é processado de novo) ou um áudio novo (transcrito primeiro e cobrado junto). O resultado vem em `summary`: o resumo e os tópicos em ordem (`title`, `start_ms`, `points`), mais um Markdown para baixar. O texto da transcrição (nunca o áudio) é enviado ao modelo de linguagem da plataforma.
</Endpoint>

### Traduzir áudio

<Endpoint id="audio.translate" example={{ body: `{ "job_id": "5b1d8c2e-6f4a-4e7b-9c3d-2a8e1f0b7d64", "target_language": "en", "format": "srt" }` }}>
  `target_language` é obrigatório. A tradução sai em texto, SRT ou VTT com os tempos originais (e os falantes, se a transcrição tinha `diarize`); `source_language` informa de qual idioma ela veio. Não gera áudio dublado: para isso, use o [revoice](#revoice).
</Endpoint>

### Falar a gravação de novo com outra voz

<Endpoint id="audio.revoice" example={{ body: `{ "audio_url": "https://example.com/aviso.mp3", "voice_id": "pt-BR-alex", "format": "mp3" }` }}>
  Num só job: transcreve a gravação, traduz o texto quando a voz fala outro idioma e sintetiza o resultado. Informe `voice_id` (do catálogo) ou `language` (usa a voz padrão dele). O áudio novo não mantém o tempo nem o ritmo do original (sem sincronia labial), e só vozes do catálogo ou clonadas da própria conta valem: nada de imitar uma pessoa real. O resultado traz o texto falado (`transcript` e `text_download_url`) e o que cada etapa custou em `revoice.stages`.
</Endpoint>

### Listar jobs

<Endpoint id="audio.list" example={{ query: { limit: '20', offset: '0' } }}>
  Os jobs mais recentes primeiro, com `limit` (padrão 20, até <Limit name="pageSizeMax" />) e `offset`. A lista traz só o status; o resultado e o link ficam em `GET /jobs/{id}`. Jobs e arquivos são apagados depois da retenção (<Limit name="audioRetention" />).
</Endpoint>

### Status, resultado e download

<Endpoint id="audio.get">
  Não há rota de download separada: o resultado e o arquivo vêm deste endpoint. Com `status: completed`, a resposta traz o conteúdo pelo tipo de job — `transcript` (também inline até 32 KB; `truncated: true` avisa o corte) para transcrição e tradução, `summary`, `analysis`, `conversion`, `generation` ou `revoice` — e `download_url` com `download_expires_at`. O link é assinado e expira: consulte de novo para receber um link novo. Em `failed`, o `error_code` explica o motivo e a cobrança é devolvida. A leitura é medida na [franquia diária](/cobranca-e-limites#franquia-diaria).

  `status`: `pending`, `processing`, `completed` ou `failed`.
</Endpoint>

## Vozes clonadas e consentimento (só MCP)

Enquanto não existir uma rota REST, a clonagem de voz está **somente nas tools MCP** `voice_create`, `voice_list` e `voice_delete` (scope `tools:audio:speak`). A voz clonada serve só à conta que a criou, em `audio_speak` (`voice: "vc_…"`, preço de voz clonada) e em `audio_revoice` (`voice_id`).

* **`voice_create`** clona a voz **do titular da conta** a partir de uma amostra de <Limit name="audioVoiceSample" />. O consentimento é obrigatório: chame primeiro com `dry_run` para ler `consent_terms`, `consent_version` e `consent_phrase`; grave a amostra **com você sozinho lendo a frase em voz alta**; então chame com `consent.accepted: true` e a `consent_version`. Amostras sem a frase, com mais de uma voz ou fora da duração são recusadas e o valor é devolvido (`audio.voice_sample_rejected`). Sem o aceite, a resposta é `audio.consent_required`. É assíncrono: acompanhe com `voice_list` até a voz ficar `completed`.
* **`voice_list`** lista as vozes da conta (`voice_id`, nome, idioma, `status`, validade). Grátis.
* **`voice_delete`** apaga a voz de verdade: a amostra criptografada e o registro de consentimento são destruídos e a voz para de funcionar na hora (jobs na fila nela falham e são devolvidos). Grátis.

### Uso responsável

* **Só a sua voz, com o seu consentimento.** Clonar a voz de outra pessoa, mesmo com a gravação em mãos, não é permitido; a verificação da frase falada e de um único falante existe para impedir isso.
* **Nada de imitação.** Nem a fala, nem o `revoice`, nem a geração de sons aceitam imitar artistas, vozes ou obras existentes.
* **Limites:** até <Limit name="audioVoicesMax" /> vozes clonadas por conta, <Limit name="audioVoiceCreatesPerDay" /> criações por dia e <Limit name="audioVoiceUsesPerHour" /> usos por hora (`audio.voice_limit`, `audio.voice_rate_limited`).
* **Dados guardados:** a amostra fica criptografada por até <Limit name="audioVoiceSampleRetention" /> ou até o `voice_delete`; cada criação, recusa, uso e exclusão é auditado, sem conteúdo de voz. O áudio de entrada e de saída dos demais jobs expira em <Limit name="audioRetention" />.
* **Aviso ao ouvinte:** se você publica áudio sintético, avise que a voz é gerada, principalmente quando for uma voz clonada.

## Scopes

| Scope                    | Operações                                                                         |
| ------------------------ | --------------------------------------------------------------------------------- |
| `tools:audio:transcribe` | `transcribe`, `summarize`, `translate`                                            |
| `tools:audio:speak`      | `speak`, `generate`, `revoice` (no MCP, também `voice_create` e `voice_delete`)   |
| `tools:audio:process`    | `analyze`, `convert`                                                              |
| `tools:audio:read`       | `voices`, `jobs`, `jobs/{id}` (os três scopes acima também leem os próprios jobs) |

`tools:manage` cobre tudo. A lista completa fica em [Autenticação](/autenticacao).

## Erros

`audio.*` na resposta ou, em jobs que falham depois de aceitos, no `error_code` do job.

<ErrorTable tool="audio" />