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"
}
보이스를 조건에 따라 검색할 수 있는 API입니다.
내 계정에서 사용 가능한 보이스(일반 + 클론 보이스 포함)를 이름, 언어, 스타일 등 다양한 조건으로 필터링할 수 있습니다.

​
주요 파라미터

파라미터설명예시
name보이스 이름으로 검색 (부분 일치)My Voice (→ 클론 보이스 찾기)
language보이스의 언어 코드 (쉼표로 다중 입력 가능)ko, en, ja
gender보이스의 성별 (쉼표로 다중 입력 가능)male, female
age보이스의 연령대teen, adult, senior 등
use_case추천 사용처 기반 필터audiobook, narration, advertisement 등
style감정 스타일 필터 (가장 앞에 오는 값이 디폴트)neutral, happy, sad, angry 등
model지원하는 음성 모델 기준 필터sona_speech_1 등
page_size한 페이지당 항목 수 (기본값: 20, 최대: 100)50
next_page_token페이지네이션을 위한 토큰이전 응답에서 받은 nextPageToken 값
⚠️ sort 파라미터는 지원하지 않습니다.

​
사용 예시 1: 클론드 보이스 찾기

GET /v1/voices/search?name=My Voice
→ 내 계정에 등록된 클론드 보이스(예: My Voice)를 검색하여 voice_id를 얻을 수 있습니다.

​
사용 예시 2: 스타일과 언어 조건 필터

GET /v1/voices/search?style=happy&language=ko,en
스타일에 happy가 포함되고, 언어에 한국어(ko)와 영어(en) 중 1개 이상이 포함되는 보이스만 조회됩니다.

​
사용 예시 3: 페이지네이션 적용

GET /v1/voices/search?page_size=50&next_page_token=eyJpZCI6IjEyMzQ1In0=
  • 50개 단위로 다음 페이지를 가져옵니다.
  • next_page_token 값은 이전 응답에서 받아올 수 있습니다.

​
유의사항

  • 파라미터는 모두 쉼표 구분으로 다중 조건(OR)을 입력할 수 있습니다. 
    language=ko,en&style=happy,sad
  • 존재하지 않는 조합을 입력하면 응답은 200 OK지만 결과가 비어 있을 수 있습니다.
  • 응답 구조는 items 배열과 next_page_token 값을 포함하며, 각 보이스의 voice_id, 스타일, 샘플 URL 등도 함께 제공됩니다.

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.