Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.supertoneapi.com/llms.txt

Use this file to discover all available pages before exploring further.

The Supertone API uses a credit-based billing model that is shared with Supertone Play. This page covers how credits work, how to forecast cost before generating, and the endpoints you should integrate into your observability stack.

​
How credits work

  • Credits are deducted per second of generated audio.
  • Credits are shared with Supertone Play — the same balance applies to both. Credits charged in Play are immediately available to the API and vice versa.
  • Both preset voices and custom voices deduct from the same balance.
  • predict_duration is free. No credits are deducted — use it for cost preview and pre-flighting.
Pricing tiers are listed on the Play subscription page. For higher limits and dedicated capacity, see enterprise plans.

​
Endpoints you should integrate

EndpointPurpose
POST /v1/predict-duration/{voice_id}Forecast audio length (and therefore credit cost) before generating.
GET /v1/creditsCurrent credit balance — alert when it’s low.
GET /v1/voice-usageMinutes generated per voice / style / language / model, by day (max 30 days).
GET /v1/usageBucketed analytics with breakdowns by voice_id, voice_name, api_key, or model.

​
Predict duration

predict_duration returns the expected length of generated speech for a given text, without producing audio. Use it to:
  • Show users a “this will take ~12 seconds” estimate before generation.
  • Forecast credit cost (no credits are deducted by this endpoint).
  • Decide whether a sentence fits a UI slot or budget.
predict_duration does not auto-chunk — the same 300-character limit applies. For longer scripts, split yourself and sum the predicted durations.
import os
from supertone import Supertone

VOICE_ID = "20160a4c5ba38967330c84"  # replace with your voice ID

with Supertone(api_key=os.environ["SUPERTONE_API_KEY"]) as client:
    response = client.text_to_speech.predict_duration(
        voice_id=VOICE_ID,
        text="This is a sentence to estimate.",
        language="en",
    )

print(f"Estimated duration: {response.duration:.2f}s")
The request body is the same shape as Create speech — text, language, style, model, voice_settings — minus output_format, include_phonemes, and normalized_text (none of which affect the predicted length). Tips for accurate forecasts:
  • Speed changes the result. voice_settings.speed multiplies the duration. If you preview at one speed and generate at another, the actual length will differ. Use the same speed in both calls.
  • Match the model. predict_duration accepts the same model field as create_speech. If your generation will use a specific model, predict against it.
For pre-flighting batch jobs or per-user budgets, call predict_duration first and sum the durations to decide whether to proceed.

​
Daily balance check

A simple cron job that posts to your monitoring tool when the balance drops below a threshold gives you days of warning before a 402 Payment Required outage. 
import os
from supertone import Supertone

LOW_THRESHOLD_USD = 50.0

with Supertone(api_key=os.environ["SUPERTONE_API_KEY"]) as client:
    balance = client.usage.get_credit_balance()
    if balance.credit_balance < LOW_THRESHOLD_USD:
        notify_oncall(
            f"Supertone credit balance low: ${balance.credit_balance:.2f}"
        )
You can also view the live balance in the console dashboard or the Play subscription page.

​
Weekly per-voice report

Useful when you want to know which voices drive the most cost, or to flag a runaway integration. Maximum query window is 30 days; dates are UTC+0. 
from supertone import Supertone

with Supertone(api_key=API_KEY) as client:
    usage = client.usage.get_voice_usage(
        start_date="2025-05-01",
        end_date="2025-05-31",
    )

    by_voice = {}
    for row in usage.usages or []:
        by_voice[row.name] = by_voice.get(row.name, 0) + row.total_minutes_used

    for name, minutes in sorted(by_voice.items(), key=lambda x: -x[1]):
        print(f"{name:30s} {minutes:>8.2f} min")

​
Bucketed analytics for dashboards

GET /v1/usage supports hourly or daily buckets with multiple breakdowns. Use it to populate a dashboard panel or send rows to your metrics backend. 
from supertone import Supertone

with Supertone(api_key=API_KEY) as client:
    page = client.usage.get_usage(
        start_time="2025-05-01T00:00:00+00:00",
        end_time="2025-05-31T23:59:59+00:00",
        bucket_width="day",
        breakdown_type=["api_key", "model"],
        page_size=20,
    )

    for row in page.items or []:
        emit_metric("supertone.minutes_generated", value=row.total_minutes_used, tags={
            "api_key": row.api_key,
            "model": row.model,
            "bucket_start": row.bucket_start,
        })
Restrictions:
  • You can’t combine voice_id and voice_name in the same breakdown_type.
  • If start_time and end_time have different UTC offsets, the API ignores end_time’s offset.
  • Page size is 1–20; paginate via next_page_token.

​
Anomaly alerts

Two cheap, useful alerts:
  1. Spend spike — compare today’s minutes-generated to the rolling 7-day median. Alert if today is more than (say) 3× the median.
  2. New voice in production — if a voice not in your expected set appears in get_voice_usage, flag it. This catches accidental hard-coded test voices in production code.

​
Per-user attribution

The Supertone API itself doesn’t track end-user identities — your backend does. The pattern is:
  1. Have your backend record each TTS call with user_id, voice_id, predicted/actual duration, timestamp.
  2. Roll up internally for billing or anti-abuse.
  3. Cross-check periodically against get_voice_usage to make sure your records align with Supertone’s count.

Create speech

Generate audio once you’ve forecasted the cost.

Rate limits

Per-minute request limits by tier.