> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knowlify.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Voices and voice changes

> Browse Training voices and change narration on an existing video

## List voices

`GET {API_BASE}/v1/voices`

Send `X-API-Key`. The `voices` array contains the app's curated narrator catalog plus custom voices saved by the key's owner. An organization key does not expose other members' private custom voices.

Each entry contains `voice_id`, `name`, `description`, `custom`, and nullable `preview_url`. Curated entries also include gender, accent, age, and descriptive tags. Custom entries include their stored labels. Curated previews are currently null; custom previews are returned when saved.

Use the selected `voice_id` in [video creation](/api-reference/create-video), or to change an existing video's narration below. This endpoint does not create or clone voices.

## Change an existing video's voice

`POST {API_BASE}/v1/videos/{uuid}/voice`

```bash theme={null}
curl --fail-with-body -X POST "$API_BASE/v1/videos/$VIDEO_UUID/voice" \
  -H "X-API-Key: $KNOWLIFY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"voice_id":"JBFqnCBsd6RMkjVDRZzb"}'
```

This selects George from the catalog and regenerates narration using the existing script. Omit `scene_numbers` to change all supported scenes, or supply a nonempty list of positive scene numbers. The video must be fully rendered with no pending edits. The key must own the video in its workspace. User IDs and billing scope cannot be supplied in the request.

The response is HTTP 202 with `uuid`, `job_id`, `status`, `voice_id`, and `status_url`. Poll [video status](/api-reference/poll-video) until rendering completes and a combined `video_url` is available. Changing voices may change narration timing and video length. Avatar scenes may require lip-sync rendering. Normal account credit checks apply.

Unknown or inaccessible voice IDs and invalid scene numbers return 422. Busy, incomplete, or failed videos return 409. Failed public voice jobs report failure instead of pretending the old voice is a successful result. Partial scene-render failures do not publish a mixed-voice result. A later failure, such as billing settlement, can occur after media was saved; inspect status before retrying. If submission returns 503, queue acceptance may be uncertain: poll the video before retrying. Do not submit concurrent edits or revoice operations against the same video.

Voice changes are not `/v1/edits` records and cannot be reverted through the edit-revert endpoint. Save the original output if you need it.

These routes require the updated API and worker on `dev`; production availability is not confirmed.