GET
/
v1
/
voices
/
search
curl --request GET \
  --url https://supertoneapi.com/v1/voices/search \
  --header 'x-sup-api-key: <x-sup-api-key>'
{
  "voices": [
    {
      "voice_id": "<string>",
      "name": "<string>",
      "description": "<string>",
      "age": "<string>",
      "gender": "<string>",
      "use_case": "<string>",
      "language": "<string>",
      "style": "<string>"
    }
  ],
  "total": 123,
  "page": 123,
  "page_size": 123,
  "total_pages": 123
}

Search Voices API를 사용하면 다양한 필터링과 정렬 옵션을 통해 원하는 음성을 찾을 수 있습니다. 이 가이드는 검색 매개변수를 효과적으로 사용하는 방법을 설명합니다.

기본 사용법

음성을 검색하려면 /v1/voices/search에 GET 요청을 보내세요. 여러 매개변수를 사용하여 결과를 필터링하고 정렬할 수 있습니다.

검색 논리

  • 동일한 매개변수 내의 여러 값은 OR 논리로 결합됩니다 (쉼표로 구분)
  • 서로 다른 매개변수는 AND 논리로 결합됩니다
  • 매개변수를 지정하지 않으면 이름 오름차순으로 정렬된 첫 페이지의 20개 음성이 반환됩니다

사용 가능한 매개변수

필터 매개변수

language

  • 사용 가능한 옵션: ko, ja, en
  • 예시: language=en,ko (영어 또는 한국어 음성 검색)

gender

  • 사용 가능한 옵션: male, female
  • 예시: gender=male,female

age

  • 사용 가능한 옵션: child, young-adult, middle-aged, elder
  • 예시: age=young-adult,middle-aged

use_case

  • 사용 가능한 옵션: advertisement, announcement, audiobook, documentary, education, game
  • 예시: use_case=game,advertisement

search

  • 이름과 설명 필드에서 검색
  • 공백으로 구분된 키워드는 AND 논리로 검색
  • 예시: search=calm professional

페이지네이션

page

  • 0부터 시작
  • 기본값: 0

page_size

  • 범위: 1-100
  • 기본값: 20

정렬

sort

  • 기본값: name:asc
  • 사용 가능한 옵션:
    • name:asc, name:desc
    • age:asc, age:desc
    • use_case:asc, use_case:desc
    • language:asc, language:desc
    • gender:asc, gender:desc

요청 예시

# 영어 또는 한국어 여성 게임 음성 찾기
/v1/voices/search?language=en,ko&gender=female&use_case=game

# 차분하고 전문적인 스타일의 청년 또는 중년 음성 검색
/v1/voices/search?age=young-adult,middle-aged&search=calm professional

# 50개 음성이 포함된 두 번째 페이지 가져오기
/v1/voices/search?page=1&page_size=50

# 나이 내림차순으로 음성 정렬
/v1/voices/search?sort=age:desc

응답 형식

API는 다음을 포함하는 JSON 응답을 반환합니다:

  • 일치하는 음성 목록
  • 총 일치 수
  • 현재 페이지 번호
  • 페이지 크기
  • 총 페이지 수

응답 예시

{
  "voices": [
        {
            "voice_id": "eYcikLUBeC8TFJmJ1rtu6u",
            "name": "Esther",
            "description": "Esther is a warm and kind grandmother who speaks in a gentle, soothing tone.",
            "age": "elder",
            "gender": "female",
            "use_case": "game",
            "language": "ja",
            "style": "serene"
        }
    // ... 더 많은 음성
  ],
  "total": 157,
  "page": 0,
  "page_size": 20,
  "total_pages": 8
}

Headers

x-sup-api-key
string
required

API key for the service

Query Parameters

Search across name and description

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)

page
number

Page number (default: 0)

page_size
number

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

sort
string

Sorting criteria (default: name:asc)

Response

200
application/json
Successful voice search response
voices
object[]
required
total
number
required
page
number
required
page_size
number
required
total_pages
number
required