Voices

• Preset voices — designed and provided by Supertone. Browse them in the Play voice library or via GET /v1/voices. This page covers preset voices.
• Custom voices — voice clones you create and manage yourself. See Custom voices.

​

Find a voice ID

​

Copy from Supertone Play (fastest)

​

List voices via the API

import os
from supertone import Supertone

with Supertone(api_key=os.environ["SUPERTONE_API_KEY"]) as client:
    result = client.voices.list_voices(page_size=20)
    for voice in result.items or []:
        print(voice.voice_id, voice.name, voice.language)

import { Supertone } from "@supertone/supertone";

const client = new Supertone({ apiKey: process.env.SUPERTONE_API_KEY });
const result = await client.voices.listVoices({ pageSize: 20 });

for (const voice of result.items ?? []) {
  console.log(voice.voiceId, voice.name, voice.language);
}

curl "https://supertoneapi.com/v1/voices?page_size=20" \
  -H "x-sup-api-key: $SUPERTONE_API_KEY"

​

Search by filters

result = client.voices.search_voices(
    language="ko,en",
    style="happy",
    page_size=20,
)

const result = await client.voices.searchVoices({
  language: "ko,en",
  style: "happy",
  pageSize: 20,
});

curl "https://supertoneapi.com/v1/voices/search?language=ko,en&style=happy&page_size=20" \
  -H "x-sup-api-key: $SUPERTONE_API_KEY"

​

The voice object

{
  "voice_id": "20160a4c5ba38967330c84",
  "name": "Adam",
  "description": "",
  "age": "young-adult",
  "gender": "male",
  "use_case": "meme",
  "language": ["ko", "en", "ja"],
  "styles": ["neutral"],
  "models": ["sona_speech_1"],
  "samples": [
    {
      "language": "en",
      "style": "neutral",
      "model": "sona_speech_1",
      "url": "https://.../sample.wav"
    }
  ],
  "thumbnail_image_url": "https://.../thumb.png"
}

​

Important constraints

• All three must align. A successful TTS call needs a voice_id plus a (language, style, model) combination that the voice actually supports. If the combination doesn’t exist, the API returns an error.
• Default style. If you omit style, the first value in the voice’s styles array is used. Different characters can have different defaults, so check the voice object before omitting.
• Permissions. Preset voices are available to every account; access is gated only by your plan.

​

Next