Search Voices

Search Voices API allows you to find the perfect voice for your needs using various filtering and sorting options. This guide explains how to effectively use the search parameters to narrow down your results.

​

Basic Usage

To search for voices, make a GET request to /v1/voices/search. You can use multiple parameters to filter and sort the results.

​

Search Logic

• Multiple values within the same parameter are combined with OR logic (comma-separated)
• Different parameters are combined with AND logic
• If no parameters are provided, returns the first page with 20 voices sorted by name ascending

​

Available Parameters

​

Filter Parameters

language

• Available options: ko, ja, en
• Example: language=en,ko (searches for voices in English OR Korean)

gender

• Available options: male, female
• Example: gender=male,female

age

• Available options: child, young-adult, middle-aged, elder
• Example: age=young-adult,middle-aged

use_case

• Available options: advertisement, announcement, audiobook, documentary, education, game
• Example: use_case=game,advertisement

search

• Searches across name and description fields
• Uses space-separated keywords with AND logic
• Example: search=calm professional

​

Pagination

page

• Starting from 0
• Default: 0

page_size

• Range: 1-100
• Default: 20

​

Sorting

sort

• Default: name:asc
• Available options:
  • name:asc, name:desc
  • age:asc, age:desc
  • use_case:asc, use_case:desc
  • language:asc, language:desc
  • gender:asc, gender:desc

​

Example Requests

# Find English or Korean female voices for games
/v1/voices/search?language=en,ko&gender=female&use_case=game

# Search for young or middle-aged voices with calm professional style
/v1/voices/search?age=young-adult,middle-aged&search=calm professional

# Get the second page of results with 50 voices per page
/v1/voices/search?page=1&page_size=50

# Sort voices by age in descending order
/v1/voices/search?sort=age:desc

​

Response Format

The API returns a JSON response containing:

• List of matching voices
• Total count of matches
• Current page number
• Page size
• Total number of pages

​

Example Response

{
  "voices": [
        {
            "voice_id": "eYcikLUBeC8TFJmJ1rtu6u",
            "name": "Esther",
            "description": "Esther is a warm and kind grandmother who speaks in a gentle, soothing tone.",
            "age": "elder",
            "gender": "female",
            "use_case": "game",
            "language": "ja",
            "style": "serene"
        }
    // ... more voices
  ],
  "total": 157,
  "page": 0,
  "page_size": 20,
  "total_pages": 8
}