---
title: "Get a stock voice"
method: GET
path: "/v1/voices/{id}"
tags: ["Text To Speech (Speak)"]
---

# Get a stock voice

`GET /v1/voices/{id}`

## Request

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

## Path parameters

- `id` string, required

## Response `200`

Stock voice

- 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`)
- `404`: No such stock voice

---

[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/271a1539185b?raw)