GET
/
v1
/
voices
/
search
curl --request GET \
  --url https://supertoneapi.com/v1/voices/search \
  --header 'x-sup-api-key: <x-sup-api-key>'
{
  "voices": [
    {
      "voice_id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "age": "<string>",
      "gender": "<string>",
      "use_case": "<string>",
      "language": "<string>",
      "style": "<string>"
    }
  ],
  "total": 123,
  "page": 123,
  "page_size": 123,
  "total_pages": 123
}

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
}

Headers

x-sup-api-key
string
required

API key for the service

Query Parameters

Search across name and description

language
string

Filter by language (comma-separated)

gender
string

Filter by gender (comma-separated)

age
string

Filter by age (comma-separated)

use_case
string

Filter by use case (comma-separated)

style
string

Filter by style (comma-separated)

page
number

Page number (default: 0)

page_size
number

Number of items per page (default: 20, max: 100)

sort
string

Sorting criteria (default: name:asc)

Response

200
application/json
Successful voice search response
voices
object[]
required
total
number
required
page
number
required
page_size
number
required
total_pages
number
required