Supertone Python Library

Summary

Supertone Public API: Supertone API is a RESTful API for using our state-of-the-art AI voice models.

SDK Installation

The SDK can be installed with uv, pip, or poetry package managers.

uv

uv is a fast Python package installer and resolver, designed as a drop-in replacement for pip and pip-tools. It's recommended for its speed and modern Python tooling capabilities.

uv add supertone

PIP

PIP is the default package installer for Python, enabling easy installation and management of packages from PyPI via the command line.

pip install supertone

Poetry

Poetry is a modern tool that simplifies dependency management and package publishing by using a single pyproject.toml file to handle project metadata and dependencies.

poetry add supertone

SDK Example Usage

Example

# Synchronous Example
from supertone import Supertone, models


with Supertone(
    api_key="<YOUR_API_KEY_HERE>",
) as s_client:

    res = s_client.text_to_speech.create_speech(voice_id="<id>", text="<value>", language=models.APIConvertTextToSpeechUsingCharacterRequestLanguage.JA, model=models.APIConvertTextToSpeechUsingCharacterRequestModel.SONA_SPEECH_1, output_format=models.APIConvertTextToSpeechUsingCharacterRequestOutputFormat.WAV, include_phonemes=False)

    # Handle response
    print(res)

The same SDK client can also be used to make asynchronous requests by importing asyncio.

# Asynchronous Example
import asyncio
from supertone import Supertone, models

async def main():

    async with Supertone(
        api_key="<YOUR_API_KEY_HERE>",
    ) as s_client:

        res = await s_client.text_to_speech.create_speech_async(voice_id="<id>", text="<value>", language=models.APIConvertTextToSpeechUsingCharacterRequestLanguage.JA, model=models.APIConvertTextToSpeechUsingCharacterRequestModel.SONA_SPEECH_1, output_format=models.APIConvertTextToSpeechUsingCharacterRequestOutputFormat.WAV, include_phonemes=False)

        # Handle response
        print(res)

asyncio.run(main())

Authentication

Per-Client Security Schemes

This SDK supports the following security scheme globally:

To authenticate with the API the api_key parameter must be set when initializing the SDK client instance. For example:

from supertone import Supertone, models


with Supertone(
    api_key="<YOUR_API_KEY_HERE>",
) as s_client:

    res = s_client.text_to_speech.create_speech(voice_id="<id>", text="<value>", language=models.APIConvertTextToSpeechUsingCharacterRequestLanguage.JA, model=models.APIConvertTextToSpeechUsingCharacterRequestModel.SONA_SPEECH_1, output_format=models.APIConvertTextToSpeechUsingCharacterRequestOutputFormat.WAV, include_phonemes=False)

    # Handle response
    print(res)

Models

Supertone’s Text-to-Speech API provides multiple TTS models, each with different supported languages, available voice settings, and streaming capabilities.

Model Overview

Model Overview

|

Supported Languages by Model

• sona_speech_2

  • en, ko, ja, bg, cs, da, el, es, et, fi, hu, it, nl, pl, pt, ro,
    ar, de, fr, hi, id, ru, vi

• sona_speech_2_flash

  • en, ko, ja, bg, cs, da, el, es, et, fi, hu, it, nl, pl, pt, ro,
    ar, de, fr, hi, id, ru, vi

• sona_speech_1

  • en, ko, ja

• supertonic_api_3

  • en, ko, ja, ar, bg, cs, da, de, el, es, et, fi, fr, hi, hr, hu,
    id, it, lt, lv, nl, pl, pt, ro, ru, sk, sl, sv, tr, uk, vi

• supertonic_api_1

  • en, ko, ja, es, pt

Voice Settings (Optional)

Some TTS models support optional voice settings that allow fine control over output speech characteristics (e.g., speed, pitch, pitch variance).

• sona_speech_2

  • Supports all Voice Settings except subharmonic_amplitude_control.

• sona_speech_2_flash

  • Supports all Voice Settings except similarity, text_guidance, subharmonic_amplitude_control.

• sona_speech_1

  • Supports all available Voice Settings.

• supertonic_api_3

  • Supports only the speed setting. All other settings will be ignored.

• supertonic_api_1

  • Supports only the speed setting. All other settings will be ignored.

All Voice Settings are optional. When omitted, each model’s default values will be applied.

Error Handling

SupertoneError is the base class for all HTTP error responses. It has the following properties:

Example

from supertone import Supertone, errors, models


with Supertone(
    api_key="<YOUR_API_KEY_HERE>",
) as s_client:
    res = None
    try:

        res = s_client.text_to_speech.create_speech(voice_id="<id>", text="<value>", language=models.APIConvertTextToSpeechUsingCharacterRequestLanguage.JA, model=models.APIConvertTextToSpeechUsingCharacterRequestModel.SONA_SPEECH_1, output_format=models.APIConvertTextToSpeechUsingCharacterRequestOutputFormat.WAV, include_phonemes=False)

        # Handle response
        print(res)


    except errors.SupertoneError as e:
        # The base class for HTTP error responses
        print(e.message)
        print(e.status_code)
        print(e.body)
        print(e.headers)
        print(e.raw_response)

        # Depending on the method different errors may be thrown
        if isinstance(e, errors.BadRequestErrorResponse):
            print(e.data.status)  # str
            print(e.data.message)  # str

Error Classes

Primary error:

• SupertoneError: The base class for HTTP error responses.

* Check the method documentation to see if the error is applicable.

Additional Example Code

Additional example code can be found in the examples directory.