Developer documentation

Text to Speech API

Generate an MP3 from a short text request with your TTSMint account key. This endpoint is for server-side applications; keep the key out of browsers and public repositories.

Authentication

Create a TTSMint API key in Settings → API access. Keys use the tmcp_ prefix and share the Credits balance of the same account. An active account can create keys without first buying a paid plan; up to 10 active keys are allowed. The full key is shown only when it is created.

Send the key as a Bearer token from a trusted server. Do not put it in browser JavaScript, a mobile app bundle, a public repository, or a client-side environment variable.

Authorization: Bearer $TTSMINT_API_KEY

Make a request

POST https://ttsmint.com/v1/audio/speech

The example request is shared with the Python sample file so both clients use the same text, voice, model, and speed:

{
  "model": "ttsmint-tts-1",
  "input": "Hello from TTSMint.",
  "voice": "v_a7140b65",
  "response_format": "mp3",
  "speed": 1
}

The sample text contains 19 Unicode code points and costs 1 Credit at the voice's current 1× rate.

Parameters

FieldRequirement and supported values
inputRequired, non-empty string of up to 5,000 Unicode code points. Whitespace, line breaks, and punctuation count. Input is not normalized.
modelDefaults to ttsmint-tts-1. The accepted aliases tts-1, tts-1-hd, and gpt-4o-mini-tts map to this TTSMint model; they do not select those upstream models.
voiceDefaults to v_a7140b65 (Fern Oasis). Use a voice ID or ShortName shown in the voice directory; each voice lists its current Credit rate.
response_formatOnly mp3 is supported. A successful response is audio, not JSON.
speedOptional number from 0.25 to 4.0; default 1.
instructionsOptional and intentionally narrow: only the supported exact speed template and default-pitch template are accepted. Omit it for the usual result; free-form style directions, arbitrary pitch, and volume controls are not supported.

curl

Save the shared request as tts-reader-request.json and run this from a trusted server with POSIX shell, curl, and mktemp. Set the placeholder in your server environment without printing it or committing it:

export TTSMINT_API_KEY='YOUR_TTSMINT_API_KEY'

The temporary file is promoted only after a 200 audio response; JSON errors do not overwrite an existing MP3.

#!/bin/sh
set -eu

: "${TTSMINT_API_KEY:?Set TTSMINT_API_KEY in your trusted shell or secret manager}"
tmp=$(mktemp "./speech.mp3.XXXXXX")
trap 'rm -f "$tmp"' EXIT HUP INT TERM

response_meta=$(curl --silent --show-error --connect-timeout 10 --max-time 60 --output "$tmp" --write-out '%{http_code} %{content_type}' \
  --request POST 'https://ttsmint.com/v1/audio/speech' \
  --header "Authorization: Bearer $TTSMINT_API_KEY" \
  --header 'Content-Type: application/json' \
  --header 'Accept: audio/mpeg' \
  --data-binary @tts-reader-request.json)
status=${response_meta%% *}
content_type=${response_meta#* }

if [ "$status" != 200 ] || [ "${content_type%%;*}" != 'audio/mpeg' ]; then
  cat "$tmp" >&2
  echo 'Check the JSON error.code above; the body was not saved as MP3.' >&2
  exit 1
fi
if [ ! -s "$tmp" ]; then
  echo 'The server returned an empty MP3; the existing output was left unchanged.' >&2
  exit 1
fi

mv -f "$tmp" speech.mp3
trap - EXIT HUP INT TERM

Download the curl shell script and shared request file into one directory, then run sh tts-reader.sh. The Python standard-library script also parses JSON error details and atomically replaces the output file after success.

Python standard library

Download the Python script and shared request file to the same directory, set TTSMINT_API_KEY in the server environment, then run python3 tts-reader.py. It writes speech.mp3 only after receiving a non-empty MP3.

View complete Python example
#!/usr/bin/env python3
"""Call the TTSMint reader API from a trusted server-side environment."""

import json
import os
import sys
import tempfile
from pathlib import Path
from urllib.error import HTTPError, URLError
from urllib.request import Request, urlopen


API_URL = "https://ttsmint.com/v1/audio/speech"
USER_AGENT = "TTSMintPythonExample/1.0"
REQUEST_FILE = Path(__file__).with_name("tts-reader-request.json")


def show_error(status, body):
    try:
        payload = json.loads(body.decode("utf-8"))
        error = payload.get("error", {}) if isinstance(payload, dict) else {}
        if isinstance(error, dict):
            print("HTTP {}: {} ({})".format(status, error.get("message", "Request failed"), error.get("code", "UNKNOWN_ERROR")), file=sys.stderr)
            return
    except (UnicodeDecodeError, json.JSONDecodeError, AttributeError):
        pass
    print("HTTP {}: the server did not return an audio response".format(status), file=sys.stderr)


def download_audio(output_path, api_key, opener=None):
    """Return True after an MP3 is atomically saved; otherwise keep old output."""
    if not api_key:
        print("Set TTSMINT_API_KEY in the server environment first.", file=sys.stderr)
        return False

    request_body = REQUEST_FILE.read_bytes()
    request = Request(
        API_URL,
        data=request_body,
        headers={
            "Authorization": "Bearer " + api_key,
            "Content-Type": "application/json",
            "Accept": "audio/mpeg",
            "User-Agent": USER_AGENT,
        },
        method="POST",
    )
    send = opener or urlopen
    try:
        response = send(request, timeout=60)
    except HTTPError as error:
        show_error(error.code, error.read())
        return False
    except URLError as error:
        print("Network request failed: {}".format(error.reason), file=sys.stderr)
        return False

    with response:
        content_type = response.headers.get_content_type()
        if response.status != 200 or content_type != "audio/mpeg":
            show_error(response.status, response.read())
            return False
        audio = response.read()

    if not audio:
        print("The server returned an empty audio response; output was left unchanged.", file=sys.stderr)
        return False

    target = Path(output_path)
    target.parent.mkdir(parents=True, exist_ok=True)
    temporary_path = None
    try:
        with tempfile.NamedTemporaryFile(dir=str(target.parent), prefix="." + target.name + ".", suffix=".tmp", delete=False) as temporary:
            temporary_path = temporary.name
            temporary.write(audio)
            temporary.flush()
            os.fsync(temporary.fileno())
        os.replace(temporary_path, target)
        temporary_path = None
    finally:
        if temporary_path and os.path.exists(temporary_path):
            os.unlink(temporary_path)
    print("Saved MP3 to {}".format(target))
    return True


def main(argv=None):
    arguments = list(argv if argv is not None else sys.argv[1:])
    output_path = arguments[0] if arguments else "speech.mp3"
    return 0 if download_audio(output_path, os.environ.get("TTSMINT_API_KEY")) else 1


if __name__ == "__main__":
    raise SystemExit(main())

Credits, previewing, and repeated requests

Each new request is quoted as ceil(Unicode code points ÷ 100) × voice Credit rate. At a 1× rate, 100 code points cost 1 Credit and 101 cost 2 Credits. Spaces, punctuation, and newlines count too. Check the active rate in the voice directory and your balance in Billing & credits before sending long text. Web tools and this API use the same account Credits.

A new operation reserves Credits before synthesis. A failed operation releases its reservation; a successful operation settles it. Generating audio to preview it can use Credits even if you never play or download it. A later download or RESULT_UNAVAILABLE error does not prove the successful synthesis was uncharged.

For the same account and key, the exact original input text and the same effective parameters can reuse a ready result for a fixed 300 seconds beginning when it becomes ready. Model and voice aliases may resolve to the same effective value, but input text is not trimmed or normalized. A cache hit is not charged again and does not extend the window. A different key, text, effective voice or speed, or a request after that window can start a new billable operation. Do not resend requests in a tight loop.

There is no subtitle output on this endpoint. Use the separate web tool for MP3 with SRT or WebVTT.

Errors and retries

Errors use a JSON body shaped like {"error":{"message":"…","type":"…","code":"…","param":"…"}}; param is optional. Check the HTTP status and parse JSON before treating a body as audio. A successful 200 response is raw MP3 bytes with Content-Type: audio/mpeg, not base64-encoded JSON.

StatusCommon codeWhat to check
400INVALID_JSON, INVALID_PARAM, INVALID_MODEL, INVALID_VOICE, INVALID_RESPONSE_FORMAT, UNSUPPORTED_PARAMETERCheck the field named by optional param, if present, along with the JSON shape and supported values.
401UNAUTHORIZEDUse an active tmcp_ key from the same account.
402INSUFFICIENT_CREDITSCheck the shared account balance before trying again.
403ACCOUNT_DISABLEDContact support if you think this is unexpected.
413TEXT_TOO_LONG / REQUEST_TOO_LARGEKeep input within 5,000 code points and the JSON body within 64 KiB.
422Policy rejectionReview the acceptable-use rules and revise the request.
429RATE_LIMITED, CONCURRENCY_LIMIT, GENERATION_RATE_LIMITHonor Retry-After when present. Limits can vary by key and account.
503SYNTHESIS_IN_PROGRESSHonor Retry-After (currently 2 seconds), keep the same key, exact text, and effective parameters, then retry a finite number of times. The service can join or reuse that operation; do not change the request while waiting.
502 / 503 / 504Upstream or service errorInspect the response and operation outcome before retrying. A failure to retrieve an already-generated result can follow a settled operation.

Current guards include up to five concurrent processing requests per user and a 60-per-minute new-operation limit. Production request limits are also applied per key and user and can be adjusted; honor response headers rather than assuming a permanent fixed quota.

Support and terms

See pricing, the guide, the FAQ, Terms, Privacy, and the Acceptable Use Policy.

If you need help, email ttsmintsupport@gmail.com. Include the approximate time and time zone, endpoint, HTTP status and error code, and the non-sensitive settings used. Never send your API key or private text/audio.