> ## Documentation Index > Fetch the complete documentation index at: https://typecast.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Recommend Voices > 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 /v2/voices` or `GET /v2/voices/{voice_id}` when you need detailed metadata such as supported models, emotions, gender, age, or use cases for the recommended voices. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/voices/recommendations openapi: 3.1.0 info: title: Typecast API version: 0.1.2 x-logo: url: https://typecast.ai/_ipx/_/image/logo/tc_logo.webp servers: - url: https://api.typecast.ai description: Production server security: - ApiKeyAuth: [] paths: /v1/voices/recommendations: get: tags: - Voices summary: Recommend Voices description: >- 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 /v2/voices` or `GET /v2/voices/{voice_id}` when you need detailed metadata such as supported models, emotions, gender, age, or use cases for the recommended voices. operationId: recommend_voices_v1_voices_recommendations_get parameters: - name: query in: query required: true schema: type: string minLength: 1 maxLength: 500 description: >- Text description. Describe the desired style, mood, language, use case, or content context with keywords or sentences. title: Query description: >- Text description. Describe the desired style, mood, language, use case, or content context with keywords or sentences. example: warm female voice for product tutorial - name: count in: query required: false schema: type: integer minimum: 1 maximum: 10 description: >- 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. default: 5 title: Count description: >- 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. example: 5 responses: '200': description: Success - Returns recommended voices sorted by score content: application/json: schema: type: array items: $ref: '#/components/schemas/RecommendedVoice' title: Response Recommend Voices V1 Voices Recommendations Get maxItems: 10 example: - voice_id: tc_60e5426de8b95f1d3000d7b5 voice_name: Olivia score: 0.92 - voice_id: tc_62a8975e695ad26f7fb514d1 voice_name: Emma score: 0.87 '401': description: Unauthorized - Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: Invalid API key '422': description: Validation Error - Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' example: detail: - loc: - query - query msg: String should have at most 500 characters type: string_too_long '500': description: Internal Server Error - Voice recommendation failed content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: detail: An unexpected error occurred x-codeSamples: - lang: cURL label: cURL source: | curl --request GET \ --url 'https://api.typecast.ai/v1/voices/recommendations?query=warm%20female%20voice%20for%20product%20tutorial&count=5' \ --header 'X-API-KEY: ' - lang: Python label: Python (requests) source: | import requests response = requests.get( "https://api.typecast.ai/v1/voices/recommendations", headers={"X-API-KEY": ""}, params={ "query": "warm female voice for product tutorial", "count": 5, }, timeout=30, ) response.raise_for_status() recommendations = response.json() if recommendations: print(recommendations[0]["voice_id"]) components: schemas: RecommendedVoice: type: object properties: voice_id: type: string title: Voice Id description: >- Typecast voice identifier with the `tc_` prefix. Use this value as `voice_id` in text-to-speech requests. example: tc_60e5426de8b95f1d3000d7b5 voice_name: type: string title: Voice Name description: Human-readable voice name. example: Olivia score: type: number title: Score description: >- Recommendation relevance score. Higher values indicate a stronger match for the query. example: 0.92 required: - voice_id - voice_name - score title: RecommendedVoice description: >- Recommended voice candidate returned by `GET /v1/voices/recommendations`, sorted by relevance. ErrorResponse: type: object properties: detail: type: string description: Error message describing the issue required: - detail example: detail: An error occurred processing the request HTTPValidationError: type: object properties: detail: type: array items: $ref: '#/components/schemas/ValidationError' title: Detail title: HTTPValidationError ValidationError: type: object properties: loc: type: array items: anyOf: - type: string - type: integer title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context required: - loc - msg - type title: ValidationError securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-KEY description: >- API key for authentication. You can obtain an API key from the Typecast API Console. ````