supertone 0.1.1

Python Client SDK for Supertone API Generated by Supertone.

Supertone Python Library

API & Docs

The official Python SDK for Supertone API

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

Speech Generation Example

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="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="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="sona_speech_1", output_format=models.APIConvertTextToSpeechUsingCharacterRequestOutputFormat.WAV, include_phonemes=False)

    # Handle response
    print(res)

Available Resources and Operations

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.

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.

Error Handling 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="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

Additional Example Code

Additional example code can be found in the examples directory.