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:

Name	Type	Scheme
api_key	apiKey	API key

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 Name	Identifier	Streaming Support (stream_speech)	Voice Settings Support
SONA Speech 1	sona_speech_1	✅ Supported	Supports all Voice Settings
Supertonic API 1	supertonic_api_1	❌ Not supported	Supports only the speed setting (others are ignored)
SONA Speech 2	sona_speech_2	❌ Not supported	Supports pitch_shift, pitch_variance, speed

Note

Streaming Support

Streaming TTS using the stream_speech endpoint is only available for the sona_speech_1 model.

---

Supported Languages by Model

Note

The set of supported input languages varies depending on the TTS model.

• sona_speech_1

  • en, ko, ja

• supertonic_api_1

  • en, ko, ja, es, pt

• 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

---

Voice Settings (Optional)

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

Note

The available Voice Settings vary depending on the TTS model.

• sona_speech_1

  • Supports all available Voice Settings.

• supertonic_api_1

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

• sona_speech_2

  • Supports the following Voice Settings:
    • pitch_shift
    • pitch_variance
    • speed

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

Available Resources and Operations

Available methods

custom_voices

• create_cloned_voice - Create cloned voice
• list_custom_voices - Gets custom (cloned) voices
• search_custom_voices - Search custom (cloned) voices
• get_custom_voice - Get single cloned voice
• edit_custom_voice - Update cloned voice (partial update)
• delete_custom_voice - Delete cloned voice

text_to_speech

• create_speech - Convert text to speech
• stream_speech - Convert text to speech with streaming response
• predict_duration - Predict text-to-speech duration

usage

• get_voice_usage - Retrieve TTS API usage data
• get_usage - Retrieve advanced API usage analytics
• get_credit_balance - Retrieve credit balance

voices

• list_voices - Gets available voices
• search_voices - Search voices.
• get_voice - Get voice details by ID

Error Handling

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

Property	Type	Description
err.message	str	Error message
err.status_code	int	HTTP response status code eg 404
err.headers	httpx.Headers	HTTP response headers
err.body	str	HTTP body. Can be empty string if no body is returned.
err.raw_response	httpx.Response	Raw HTTP response
err.data		Optional. Some errors may contain structured data. See Error Classes.

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.

Less common errors (15)

Network errors:

• httpx.RequestError: Base class for request errors.
  • httpx.ConnectError: HTTP client was unable to make a request to a server.
  • httpx.TimeoutException: HTTP request timed out.

Inherit from SupertoneError:

• UnauthorizedErrorResponse: Unauthorized: Invalid API key. Status code 401. Applicable to 10 of 15 methods.*
• InternalServerErrorResponse: Status code 500. Applicable to 10 of 15 methods.*
• NotFoundErrorResponse: Status code 404. Applicable to 9 of 15 methods.*
• BadRequestErrorResponse: Status code 400. Applicable to 5 of 15 methods.*
• ForbiddenErrorResponse: Status code 403. Applicable to 4 of 15 methods.*
• RequestTimeoutErrorResponse: Status code 408. Applicable to 4 of 15 methods.*
• TooManyRequestsErrorResponse: Status code 429. Applicable to 4 of 15 methods.*
• PaymentRequiredErrorResponse: Status code 402. Applicable to 3 of 15 methods.*
• PayloadTooLargeErrorResponse: Payload Too Large: File size exceeds 3MB limit. Status code 413. Applicable to 1 of 15 methods.*
• UnsupportedMediaTypeErrorResponse: Unsupported Media Type: Invalid audio file format. Status code 415. Applicable to 1 of 15 methods.*
• ResponseValidationError: Type mismatch between the response data and the expected Pydantic model. Provides access to the Pydantic validation error via the cause attribute.

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

Additional Example Code

Additional example code can be found in the examples directory.