---
title: "Search Model Voices"
method: GET
path: "/models/{model}/voices/search"
tags: ["Models"]
---

# Search Model Voices

`GET /models/{model}/voices/search`

## Request

- Base URL: `https://api.hedra.com/v3`
- URL: `https://api.hedra.com/v3/models/{model}/voices/search`
- Auth: one of:
  - API key in header `Authorization`
  - HTTP bearer

The voices this model accepts, ranked against a description — the whole shared library, including the voices the listing does not return.

## Path parameters

- `model` string, required: The model's public id (`GET /v3/models`).

## Query parameters

- `q` string, required: What the voice should sound like, in plain words — "warm british narrator", "energetic young announcer". Matched against the whole library for this model's provider, not just the voices `GET /v3/models/{model}/voices` returns.
- `limit` integer: Maximum voices to return. Applies to the whole response.
- `gender` 'male' | 'female': The `gender` curation label, as a voice search filter. Two members because the label carries exactly two values across every provider; published as an enum so a generated SDK types the filter rather than taking any string and failing at the boundary.
- `language` string, nullable: Only voices curated for this language, as an ISO 639-1 two-letter code (`en`, `es`, `fr`).

## Response `200`

Successful Response

- VoiceListResponse
  - `data` VoiceSummary[], required: This page of items.
    - `id` string, required: The voice's id (`voice_<uuid>`); pass it as `input.voice_id` on submit.
    - `name` string, nullable: Human-readable name.
    - `preview_url` string, nullable: URL of a short audio sample of this voice.
    - `labels` object: Curation metadata (language, gender, accent, ...).
  - `next_cursor` string, nullable, required: Opaque cursor for the next page, or null when this response completes the list. Always present. Endpoints that serve the whole collection at once always return null.

## Other responses

- `400`: Invalid or failed-validation request.
- `401`: Authentication failed: missing, malformed, or invalid credentials.
- `403`: Insufficient scope or plan.
- `404`: Resource not found.
- `429`: Rate limit exceeded.
- `500`: Internal error.

## Changes

- **2026-10-16** `06692d16e78a`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hedra-labs/apis/hedra-api/changes/models/:model/voices/search/get.md)

---

[API](https://skmtc.dev/hedra-labs/apis/hedra-api.md) - [All operations](https://skmtc.dev/hedra-labs/apis/hedra-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hedra-labs/apis/hedra-api/revisions/6ef35a11cefe?raw)