# Beatra API — Voices

> List, inspect, and delete the voices available for speech synthesis.
> Self-contained integration guide for AI coding assistants.
> Human-readable page: https://docs.beatra.ai/en/docs/capabilities/speech/voices

- Base URL: `https://api.beatra.ai/v1`
- Auth: `Authorization: Bearer <BEATRA_API_KEY>` — create keys in the console at https://console.beatra.ai (Developer → API keys)
- Headers: `Content-Type: application/json`; send `Idempotency-Key` (stable UUID) on create-style POSTs (24h dedupe window); optional `X-Request-Id` is echoed back.

---

## Primary agent path

Use the Universal Skill with the MCP tool `beatra.voices.list`. It is a
non-billable, read-only call that returns preset and tenant-owned cloned
voices.

1. Filter by `category` (`preset` / `cloned`), `language` (BCP-47), `gender`,
   or `query` (search by name).
2. Use the returned `voice_id` directly as the `voice` field in
   [text to speech](https://docs.beatra.ai/en/docs/capabilities/speech/text-to-speech); `preview_url`
   lets the user listen to a sample before choosing.

## Tool arguments

```json
{
  "category": "preset",
  "language": "zh-CN"
}
```

A voice entry looks like:

```json
{
  "voice_id": "voice_01JX...",
  "display_name": "Sunny female voice",
  "category": "preset",
  "language": "zh-CN",
  "gender": "female",
  "preview_url": "https://cdn.beatra.ai/.../preview.mp3",
  "status": "ready"
}
```

## Deleting a cloned voice

Deletion is REST-only:

```bash
curl -X DELETE "$BEATRA_BASE_URL/voices/voice_01JX..." \
  -H "Authorization: Bearer $BEATRA_API_KEY"
```

Returns `204`. Only voices you cloned yourself can be deleted; preset voices
cannot.

## REST API

Direct protocol integrations may use the voice endpoints directly:
[List](https://docs.beatra.ai/en/docs/api-reference/operations/voices/list_voices_v1_voices_get) ·
[Retrieve](https://docs.beatra.ai/en/docs/api-reference/operations/voices/get_voice_v1_voices__voice_id__get) ·
[Delete](https://docs.beatra.ai/en/docs/api-reference/operations/voices/delete_voice_v1_voices__voice_id__delete).
Skill + MCP is the recommended integration; use REST for custom, non-agent
applications.

---

## Appendix: errors

Every non-2xx response uses one envelope:

```json
{ "error": { "code": "...", "type": "...", "message": "...", "retryable": false, "request_id": "req_..." } }
```

Retry only when `retryable` is `true`, with exponential backoff and the SAME
`Idempotency-Key`. `429` responses include `X-RateLimit-*` headers.