GET
/
v1
/
voices
/
search
Search voices.
curl --request GET \
  --url https://supertoneapi.com/v1/voices/search \
  --header 'x-sup-api-key: <x-sup-api-key>'
{
  "items": [
    {
      "voice_id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "age": "<string>",
      "gender": "<string>",
      "use_case": "<string>",
      "language": "<string>",
      "styles": "<string>",
      "models": "<string>",
      "samples": [
        {
          "language": "<string>",
          "style": "<string>",
          "model": "<string>",
          "url": "<string>"
        }
      ],
      "thumbnail_image_url": "<string>"
    }
  ],
  "total": 150,
  "nextPageToken": "some_opaque_token_string_representing_last_id"
}

An API that can search voices based on conditions.
You can filter voices available in your account (including regular + cloned voices) by various conditions such as name, language, style, etc.

​
Key Parameters

ParameterDescriptionExample
nameSearch by voice name (partial match)My Voice (→ finding cloned voices)
languageVoice language code (multiple inputs possible with comma)ko, en, ja
genderVoice gender (multiple inputs possible with comma)male, female
ageVoice age groupteen, adult, senior, etc.
use_caseFilter based on recommended use caseaudiobook, narration, advertisement, etc.
styleEmotion style filter (The first value is the default)neutral, happy, sad, angry, etc.
modelFilter based on supported voice modelsona_speech_1, etc.
page_sizeNumber of items per page (default: 20, max: 100)50
next_page_tokenToken for paginationnextPageToken value received from previous response

⚠️ sort parameter is not supported.

​
Example 1: Finding Cloned Voices

GET /v1/voices/search?name=My Voice

→ You can search for cloned voices registered in your account (e.g., My Voice) to get the voice_id.

​
Example 2: Style and Language Condition Filter

GET /v1/voices/search?style=happy&language=ko,en

Only voices that include happy in style and contain at least one of Korean (ko) and English (en) in language will be retrieved.

​
Example 3: Apply Pagination

GET /v1/voices/search?page_size=50&next_page_token=eyJpZCI6IjEyMzQ1In0=
  • Fetches the next page in units of 50.
  • The next_page_token value can be obtained from the previous response.

​
Important Notes

  • All parameters can accept multiple conditions (OR) separated by commas.

    language=ko,en&style=happy,sad

  • If non-existent combinations are entered, the response will be 200 OK but the results may be empty.

  • The response structure includes an items array and next_page_token value, and also provides each voice’s voice_id, style, sample URL, etc.

Headers

​
x-sup-api-key
string
required

API key for the service

Query Parameters

​
page_size
number

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

​
name
string

Search across name. Space separated.

​
description
string

Search across description. Space separated.

​
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)

​
model
string

Filter by model (comma-separated)

​
next_page_token
string

Token for pagination (obtained from the previous page's response)

Response

200
application/json

Paginated available voices response with next page token

The response is of type object.