---
title: "List voices"
method: GET
path: "/v1/voices"
tags: ["Text To Speech (Speak)"]
---

# List voices

`GET /v1/voices`

## Request

- Base URL: `https://api.pyai.com`
- URL: `https://api.pyai.com/v1/voices`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Your unified voice library: the prebuilt PyAI catalog (with presentation metadata; some entries include an avatar or pre-generated audio preview) merged with your saved **designed** voices, each tagged by `source` (`stock` | `design`). Any active key may read it (no specific scope). Inspect `available_on` before using a stock voice with Speak or Omni, and inspect `synthesis_modes` before choosing streaming or async Speak delivery. `tier` is the customer-facing quality tier. `pricing` reports only the voice-specific amount on top of that product's base rate. `aliases` are permanent convenience inputs on the advertised surfaces; responses report the canonical `voice_id`. Cloned voices are listed separately via `GET /v1/voice/clones`.

## Query parameters

- `gender` 'M' | 'F' | 'm' | 'f' | 'male' | 'female'
- `region` string
- `language` 'bn' | 'de' | 'en' | 'en-CA' | 'en-GB' | 'en-US' | 'en-ZA' | 'es' | 'fr' | 'gu' | 'hi' | 'it' | 'ja' | 'kn' | 'ko' | 'pa' | 'pt' | 'ru' | 'te' | 'ur' | 'zh'
- `tier` 'standard' | 'natural'
- `q` string
- `source` 'stock' | 'design'

## Response `200`

Voice library (stock + designed)

- StockVoiceList
  - `object` string
  - `data` StockVoice[]
    - `object` string
    - `voice_id` string
    - `name` string
    - `gender` 'M' | 'F'
    - `region` string: Accent / regional flavor.
    - `age` string
    - `tone` string
    - `bio` string
    - `language` string
    - `avatar_url` string, uri: Voice-matched avatar image (PNG).
    - `preview_url` string, uri: Optional pre-generated audio preview (MP3). If absent, synthesize a short sample with this `voice_id`.
    - `accent` string: Normalized accent label used for matching.
    - `age_band` string: Normalized age band, e.g. 25-34.
    - `pitch_band` string: Normalized pitch band, e.g. low-medium.
    - `pace` string: Normalized speaking pace.
    - `use_cases` string[]: Recommended Agent and content use cases.
    - `search_tags` string[]: Search and auto-suggest tags.
    - `aliases` string[]: Permanent convenience identifiers accepted on the voice's advertised surfaces. API responses report the canonical `voice_id`.
    - `available_on` string[]: Product surfaces on which this stock voice can be selected.
    - `speak_emotions` string[]: Verified named delivery controls on Speak for this voice. An empty or absent list means directed emotion is unavailable. These controls apply to streaming and buffered speech; intensity is not supported.
    - `synthesis_modes` string[]: Delivery modes accepted for this voice on `POST /v1/audio/speech`. Every Speak-available voice accepts both; a voice served from a blocking-only fleet answers a streaming request with `x-pyai-stream: buffered`. An empty list means the voice has no Speak surface at all (check `available_on`).
    - `tier` 'standard' | 'natural': Customer-facing voice quality tier. The public catalog includes Standard and Natural voices; inspect `available_on` and `synthesis_modes` before use.
    - `pricing` object: Voice-specific pricing on top of the selected product's base rate.
      - `included_in_base_price` boolean, required
      - `additional_price_usd_per_minute` number, required
    - `source_dataset` string: Source dataset attribution.
    - `license` string: Source voice license identifier.

## Other responses

- `401`: Missing or invalid API key (`code: unauthorized`)

---

[API](https://skmtc.dev/pyai/apis/pyai-api.md) · [All operations](https://skmtc.dev/pyai/apis/pyai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pyai/apis/pyai-api/revisions/819d8e7c4d09?raw)