---
title: "Recommend Voices"
method: GET
path: "/v1/voices/recommendations"
tags: ["Voices"]
---

# Recommend Voices

`GET /v1/voices/recommendations`

## Request

- Base URL: `https://api.typecast.ai`
- URL: `https://api.typecast.ai/v1/voices/recommendations`
- Auth: API key in header `X-API-KEY`

This API recommends the best Typecast voices based on text descriptions.

Instead of manually searching for a specific `voice_id`, you can find the perfect voice by simply inputting keywords or sentences describing the desired style, mood, language, or use case. The response is sorted by recommendation score, so you can pass the top candidate directly to text-to-speech endpoints such as `POST /v1/text-to-speech`.

The response includes only `voice_id`, `voice_name`, and `score`. Use `GET /v3/voices` or `GET /v3/voices/{voice_id}` when you need detailed metadata such as supported models, emotions, gender, age, or use cases for the recommended voices.

## Query parameters

- `query` string, required: Text description. Describe the desired style, mood, language, use case, or content context with keywords or sentences.
- `count` integer: Maximum number of recommended voices to return after filtering. Must be between 1 and 10. Fewer than `count` voices may be returned when there are not enough matching candidates.

## Response `200`

Success - Returns recommended voices sorted by score

- RecommendedVoice[]
  - `score` number, required: Recommendation relevance score. Higher values indicate a stronger match for the query.
  - `voice_id` string, required: Typecast voice identifier with the `tc_` prefix. Use this value as `voice_id` in text-to-speech requests.
  - `voice_name` string, required: Human-readable voice name.

## Other responses

- `401`: Unauthorized - Invalid or missing API key
- `422`: Validation Error - Invalid request parameters
- `500`: Internal Server Error - Voice recommendation failed

---

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