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",
      "age": "young-adult",
      "gender": "female",
      "use_case": "narration",
      "use_cases": [
        "narration",
        "storytelling"
      ],
      "language": [
        "ar",
        "bg",
        "cs",
        "da",
        "de",
        "el",
        "en",
        "es",
        "et",
        "fi",
        "fr",
        "hi",
        "hu",
        "id",
        "it",
        "ja",
        "ko",
        "nl",
        "pl",
        "pt",
        "ro",
        "ru",
        "vi"
      ],
      "styles": [
        "kind-default",
        "normal",
        "serene"
      ],
      "models": [
        "sona_speech_1",
        "sona_speech_2",
        "sona_speech_2_flash",
        "supertonic_api_1",
        "supertonic_api_3"
      ],
      "description": "",
      "samples": [
        {
          "language": "ko",
          "style": "kind-default",
          "model": "supertonic_api_3",
          "url": "https://example.com/samples/sample-audio.wav"
        }
      ],
      "thumbnail_image_url": "https://example.com/thumbnails/voice-thumbnail.png"
    }
  ],
  "total": 150,
  "next_page_token": "some_opaque_token_string_representing_last_id"
}
이 문서는 영어 원문을 기반으로 자동 번역되었습니다. 표현이 어색하거나 모호한 부분이 있을 수 있으니, 정확한 내용은 영어 원문을 함께 확인해 주세요.
주어진 필터와 일치하는 프리셋 보이스를 반환합니다. 파라미터당 여러 값은 콤마로 구분되며 OR 조건으로 처리됩니다.

​
엔드포인트

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

​
쿼리 파라미터

NameDescriptionExample
name보이스 이름, 부분 일치.Coco
description설명, 부분 일치.kind and gentle
language언어 코드, 콤마로 구분.ko,en,ja
gender보이스 성별, 콤마로 구분.male,female
age보이스 연령대.child, young-adult, middle-aged, elder
use_case주요 사용 사례.audiobook, narration, advertisement
use_cases권장 사용 사례 (OR).audiobook,narration
style감정 스타일입니다. 첫 번째 값이 기본값입니다.neutral, happy, sad, angry
model지원 모델.sona_speech_1
page_size페이지당 항목 수입니다. 기본값 20, 최대 100.50
next_page_token이전 응답의 토큰입니다.eyJpZCI6IjEyMzQ1In0=
sort는 지원되지 않습니다. 결과는 자연 순서로 반환되므로 필요하면 클라이언트 측에서 정렬해 주십시오.

​
예시

스타일과 언어로 필터링: 
GET /v1/voices/search?style=happy&language=ko,en
스타일 목록에 happy가 포함되고 한국어 또는 영어를 지원하는 보이스를 반환합니다. 페이지네이션: 
GET /v1/voices/search?page_size=50&next_page_token=eyJpZCI6IjEyMzQ1In0=

​
응답

items(보이스 객체 배열)와 next_page_token(문자열, 선택)을 반환합니다. 일치하는 보이스가 없으면 items는 빈 배열이며, 요청 자체는 200 OK를 반환합니다.

​
참고사항

  • 콤마로 구분된 값은 OR로 결합됩니다: language=ko,en&style=happy,sad는 한국어 또는 영어를 지원하고 동시에 스타일에 happy 또는 sad가 포함된 보이스를 반환합니다.
  • 빈 결과는 오류가 아닙니다 — 4xx 응답에 의존하지 말고 items.length로 확인해 주십시오.
  • 전체 보이스 객체 구조(샘플, 지원 모델 등)는 Voices를 참고해 주십시오.

​
함께 보기

Docs: Voices

SDK 코드와 함께 보는 개념 가이드입니다.

Voice search example

앱 내 검색 가능한 보이스 선택기를 구축합니다.

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

​
next_page_token
string

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

Example:

"some_opaque_token_string_representing_last_id"