Search Voices

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
}