Voices

These endpoints manage voice clones used by Braiv Speech. They are not Brand Voices (GET /v1/brand-voices), which are thumbnail branding guidelines.

Create is async. POST /v1/voices/add returns a voice_id immediately with status: processing. Poll GET /v1/voices/{voice_id} until status is ready before calling text-to-speech. Failed clones include an error string.

Auth: xi-api-key or Authorization: Bearer (API key or OAuth oat_). Scopes: tts:read for list/get, tts:write for add/delete. Legacy unscoped TTS keys keep full Speech access.

Add a voice

Instant Voice Clone. Same path as ElevenLabs.

POST https://api.braiv.co/v1/voices/add
xi-api-key: YOUR_BRAIV_API_KEY

Multipart (HTTP clients)

Field	Required	Description
name	yes	Display name
files	yes*	One or more audio samples. The first usable clip is used.
description	no	Free text
labels	no	JSON string: language, gender, age
remove_background_noise	no	Maps to Omni enhance_reference. Default true.
sample_url	no*	https audio URL (alternative to files)

* Provide files or sample_url.

JSON (agents / MCP)

{
  "name": "Narrator",
  "sample_url": "https://example.com/sample.wav",
  "description": "Warm narration",
  "labels": {"language": "en", "gender": "female", "age": "young adult"},
  "remove_background_noise": true
}

Response (200)

{
  "voice_id": "YOUR_VOICE_ID",
  "requires_verification": false
}

Cloning itself is not billed. Synthesize still costs 1 credit.

List voices

GET https://api.braiv.co/v1/voices
GET https://api.braiv.co/v1/voices?status=ready
xi-api-key: YOUR_BRAIV_API_KEY

Returns every known clone in the bound library (ready, processing, failed). Soft-deleted clones are omitted. Cap is 100, newest first. Use status=ready for usable-only, ElevenLabs-style lists.

Workspace keys and OAuth tokens see all clones stamped with that workspaceId (any teammate’s creator). Personal credentials see clones you created with no workspaceId.

Get a voice

GET https://api.braiv.co/v1/voices/{voice_id}
xi-api-key: YOUR_BRAIV_API_KEY

Poll this after add until status is ready or failed.

Voice object

{
  "voice_id": "YOUR_VOICE_ID",
  "name": "Narrator",
  "category": "generated",
  "description": "Warm narration voice",
  "labels": {
    "language": "en",
    "gender": "female",
    "age": "young adult"
  },
  "preview_url": "https://...",
  "status": "ready",
  "workspace_id": "optional-workspace-id",
  "error": null,
  "available_for_tiers": ["pro", "business"],
  "settings": {
    "stability": null,
    "similarity_boost": null,
    "style": null,
    "use_speaker_boost": null,
    "speed": 1
  }
}

status is processing, ready, or failed. preview_url prefers the enhanced sample when present.

Delete a voice

DELETE https://api.braiv.co/v1/voices/{voice_id}
xi-api-key: YOUR_BRAIV_API_KEY

Soft-deletes the clone (204). Use this to clean up failed extracts.

Errors

Status	When
404	Missing, deleted, or outside the bound library
409	POST /v1/text-to-speech/{voice_id} before the clone is ready