GET
/
v1
/
voices
/
search
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_size1ページ当たり項目数（デフォルト：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.