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件の音声を含む2ページ目を取得
/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