Skip to main content
GET
/
v1
/
voices
/
search
Search voices.
curl --request GET \
  --url https://supertoneapi.com/v1/voices/search \
  --header 'x-sup-api-key: <api-key>'
{
  "items": [
    {
      "voice_id": "<voice-id>",
      "name": "Agatha",
      "description": "",
      "age": "young-adult",
      "gender": "female",
      "use_case": "narration",
      "use_cases": [
        "narration",
        "storytelling"
      ],
      "language": [
        "ko",
        "en",
        "ja"
      ],
      "styles": [
        "kind-default",
        "normal",
        "serene"
      ],
      "models": [
        "sona_speech_1"
      ],
      "samples": [
        {
          "language": "ko",
          "style": "kind-default",
          "model": "sona_speech_1",
          "url": "https://example.com/samples/sample-audio.wav"
        }
      ],
      "thumbnail_image_url": "https://example.com/thumbnails/voice-thumbnail.png"
    }
  ],
  "total": 150,
  "nextPageToken": "some_opaque_token_string_representing_last_id"
}
You can filter Supertone provided voices available in your account by various conditions such as name, language, style, etc.

​
Endpoint

https://supertoneapi.com/v1/voices/search

​
Key Parameters

ParameterDescriptionExample
nameSearch by voice name (partial match)Coco
languageVoice language code (multiple inputs possible with comma)ko, en, ja
genderVoice gender (multiple inputs possible with comma)male, female
ageVoice age groupchild, young-adult, middle-aged, elder, etc.
use_caseFilter based on the primary use caseaudiobook, narration, advertisement, etc.
use_casesFilter based on recommended use casesaudiobook, narration, advertisement, etc.
styleEmotion style filter (The first value is the default)neutral, happy, sad, angry, etc.
descriptionSearchable by description (partial match)kind and gentle, 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: 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 2: 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.

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

Authorizations

​
x-sup-api-key
string
header
required

Query Parameters

​
page_size
number

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

​
next_page_token
string

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

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

​
use_cases
string

Filter by use cases array (comma-separated for OR logic)

​
style
string

Filter by style (comma-separated for OR, semicolon-separated for AND). Mixing comma and semicolon is invalid and will result in 400. Note: AND semantics apply across styles on a single character; cloned voices have a single style and will only match AND when exactly one style is requested and equals the cloned voice style.

​
model
string

Filter by model (comma-separated)

Response

Paginated available voices response with next page token

​
items
object[]
required

List of character items

​
total
number
required

Total number of available characters (might be approximate or removed in future)

Example:

150

​
nextPageToken
string

Token for fetching the next page of results. Undefined if no more pages.

Example:

"some_opaque_token_string_representing_last_id"