---
title: "List available voices"
method: GET
path: "/api/v1/voices"
tags: ["Public API v1"]
---

# List available voices

`GET /api/v1/voices`

Returns the voices an administrator has activated in the catalog (`kind:"catalog"`). Authentication is optional: when you send your API key, the response ALSO includes your own saved cloned voices (`kind:"cloned"`, ids like `clone_…`) — create them with POST /v1/voices, then pass the id as `voiceId` to POST /v1/tts or POST /v1/tts/stream. Each voice carries the `engine` it renders on — a voice is only usable on that engine, cloned voices included (a clone is enrolled for one engine at creation). Pass `?engine=v3` (or `v4`) to list one engine only; omitting it lists every engine.

## Query parameters

- `engine` 'v3' | 'v4'

## Response `200`

The catalogue, plus your own cloned voices when an API key is sent.

- PublicVoiceListResponseDto
  - `voices` PublicVoiceDto[], required
    - `id` string, required — Voice id — pass this as `voiceId` (or `voice` on the OpenAI-compatible route). Cloned voices you created look like `clone_9f1c2d34-…`.
    - `description` string
    - `name` string — Display name.
    - `gender` string, nullable — Speaker gender. Explicitly null when the catalogue does not record one.
    - `region` string, nullable — Regional accent. Explicitly null when the catalogue does not record one.
    - `engine` 'v3' | 'v4', required — The engine this voice renders on. A voice is usable on that engine ONLY — passing it with a different `engine` is rejected, not substituted.
    - `kind` 'catalog' | 'cloned', required — `catalog` for a voice VieNeu publishes; `cloned` for one you created with POST /v1/voices. Cloned voices are only listed when you send your API key.
  - `count` number, required — Number of voices in `voices`.
  - `error` string — Present only when the catalogue could not be read. The response is still 200 with an empty list — treat a non-empty `error` as "retry", not as "no voices".

## Other responses

- `400` — `engine` is not a known engine.
- `401` — API key missing, malformed, or revoked.
- `429` — Rate limit or token quota exceeded. When the limit came from the application the response carries `Retry-After` (seconds) and the `X-RateLimit-*` headers and is counted against your API key; a 429 with none of those headers came from the edge proxy and is counted against your source address, shared with every other key calling from it. Back off on either.

---

[API](https://skmtc.dev/vieneu/apis/vieneu-api.md) · [All operations](https://skmtc.dev/vieneu/apis/vieneu-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/vieneu/vieneu-api/revisions/11c8166a6c4d/schema)