supertone 0.1.0

Python Client SDK Generated by Speakeasy.

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 git+<UNSET>.git

PIP

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

pip install git+<UNSET>.git

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 git+<UNSET>.git

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.