GET
/
v1
/
voices
/
search
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.