---
title: "List the caller's reusable studio voices."
method: GET
path: "/voices"
tags: ["Voices"]
---

# List the caller's reusable studio voices.

`GET /voices`

## Request

- Base URL: `https://docs.sleeperhit.studio/api/v1`
- URL: `https://docs.sleeperhit.studio/api/v1/voices`
- Auth: HTTP bearer

Lists the studio voices owned by the caller: designed voices (text-description voice design) and cloned voices (recorded sample, `sourceKind: "cloned"`), each with the provider that speaks it. Each entry carries `{ voiceId, name, provider, sourceKind, isCloned, retiresAt, retired, consent }` and what uses it (`usedBy`, `useCount`, `inUse`, `usedByLine`); the voices something uses come first, and the rest (`inUse: false`) are the Voices library's "Not used" group. Assign one to a character via the cast/voice surfaces using `voiceId` + `provider`. A voice with `retiresAt` is on a provider that is shutting its voices down: migrate it before then (POST /voice-migrations); once `retired`, it can no longer speak. A cloned voice speaks only while `consent.status` is `recorded`: one with `required` needs its subject to confirm (POST /voices/{voiceId}/consent-link), and one with `revoked` can never be used again. Scope: `story:read`.

## Response `200`

Studio voices.

- StudioVoiceListResponse: The caller's reusable studio voices — designed and cloned — with provider and source tagging, and what uses each one. The voices something uses come first; the rest (`inUse: false`) are the Voices library's "Not used" group.
  - `voices` object[], required
    - `id` string, required: Studio voice record id.
    - `voiceId` string, required: Provider voice id — use with cast/voice surfaces alongside `provider`.
    - `name` string, required: The name the writer is shown: never the service that speaks the voice ("MARFA (Cartesia take 2)" reads "MARFA (take 2)"), and a screenplay cue after a project reads as the cast does ("Karamazov - Marfa").
    - `description` string: The voice in words; empty when the stored description only says where the voice was copied from.
    - `gender` string, nullable
    - `age` string, nullable
    - `provider` 'cartesia' | 'elevenlabs' | 'openai' | 'deepgram' | 'hume', required: TTS provider that owns the voice.
    - `usedBy` object[], required: Where the voice is used (at most 8): pinned on a person in a project cast, spoken by a character in a read, or narrating a trailer or a deck.
      - `kind` 'cast' | 'read' | 'narrator', required
      - `character` string: The person (cast) or character (read).
      - `project` string: The project whose cast pins it (cast).
      - `title` string: The read, trailer or deck (read, narrator).
    - `useCount` integer, required: How many uses there are in all.
    - `inUse` boolean, required: False when nothing uses the voice: the Voices library lists it under "Not used".
    - `usedByLine` string, nullable, required: The "Used by …" line every surface shows; null when nothing uses the voice.
    - `sourceKind` string, required: designed (text-description voice design) | cloned (recorded sample) | cloned_pro (professional clone).
    - `isCloned` boolean, required
    - `createdAt` string, date-time
    - `retiresAt` string, date-time, nullable: When the voice's provider retires its voices, if it is retiring. Migrate it before then (POST /voice-migrations).
    - `retired` boolean: True once `retiresAt` has passed: the voice can no longer speak, and is migrated rather than cast.
    - `consent` StudioVoiceConsent: The consent of the person whose voice a CLONE is. A clone speaks only while `status` is `recorded`; `required` (cloned before consent records began) is refused with 409 `voice_consent_required` until its subject confirms through POST /voices/{voiceId}/consent-link; `revoked` is final (409 `voice_consent_revoked`). A designed voice is `not_needed`.
      - `status` 'recorded' | 'required' | 'revoked' | 'not_needed', required
      - `consentId` string, nullable, required
      - `recordedAt` string, date-time, nullable, required
      - `subjectType` 'self' | 'living_third_party' | 'estate' | 'null', nullable, required: Whose voice it is: the account holder, another living person, or a deceased person approved by their estate.
      - `subjectName` string, nullable, required
      - `revokedAt` string, date-time, nullable, required

## Other responses

- `401`: Missing, malformed, revoked, or expired API key.
- `403`: API key is valid but lacks the scope, is blocked by IP allowlist, or the account is disabled.
- `429`: Rate limit for this API key + IP + route family was exceeded.
- `500`: The API failed unexpectedly. Safe to retry with the same Idempotency-Key.

---

[API](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api.md) · [All operations](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/llms.txt) · [OpenAPI document](https://skmtc.dev/sleeperhit/apis/sleeper-hit-studio-story-api/revisions/4534f5d25540?raw)