Timbreby Uploading

Timbre API

Text to speech and zero-shot voice cloning in ten languages, streamed. One base URL, one key.

Opening soon · keys by request Request access →

Base URL   https://api.uploading.tech/v1
Model      timbre-1   (served today by Qwen3-TTS 1.7B, Apache-2.0)

Authentication

Send your secret key as a bearer token. Keys look like tk_live_…, are shown once when created in the console, and can be revoked there at any time. Keep them on your server, never in a browser or app bundle.

Authorization: Bearer tk_live_…

POST /v1/tts

Speak text in a voice. Returns audio bytes, or a chunked stream with streaming: true.

FieldTypeNotes
textstring, requiredUp to 10,000 characters per request. Long text is split at punctuation and every piece keeps the same voice.
reference_idstringA voice from /v1/voices (yours or a library voice), or a character id (chr_…) from a project. Omit for the default voice.
formatmp3 · wav · pcm · opusDefault mp3. pcm is 16-bit mono at 24 kHz.
streamingbooleanSend audio as it is made (first audio in about a tenth of a second at the server).
latencynormal · balancedAccepted. Both values run the same pipeline today.
languagestringzh en ja ko de fr es it pt ru. Detected when omitted.
checkbooleanChinese and English only (other languages: 422 check_unsupported_language). Each piece is heard by a speech recogniser (SenseVoice) and generated again, up to three takes, until it says its text (at most 5 % character error, length 0.8–1.25×); if no take passes, the closest one plays. It never falls back to unchecked audio: when the recogniser is unavailable the request gets 503 verifier_unavailable and nothing is billed. The response says what happened in X-Checked, X-Check-Pieces, X-Check-Accepted (pieces that passed) and X-Check-Takes. Slower: first audio waits for the first piece to be generated and heard.
curl https://api.uploading.tech/v1/tts \
  -H "Authorization: Bearer $TIMBRE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Hello from Timbre.", "reference_id": "VOICE_ID", "format": "mp3"}' \
  --output hello.mp3

OpenAI-compatible: POST /v1/audio/speech

Code written for OpenAI's speech endpoint works by changing the base URL and key. voice is a Timbre voice id; response_format accepts mp3 wav pcm opus flac (mp3, wav and pcm stream). speed must be 1.0.

from openai import OpenAI
client = OpenAI(base_url="https://api.uploading.tech/v1", api_key="tk_live_…")
client.audio.speech.with_streaming_response.create(
    model="timbre-1", voice="VOICE_ID", input="Hello from Timbre.",
).stream_to_file("hello.mp3")
import OpenAI from "openai";
import fs from "node:fs";
const client = new OpenAI({ baseURL: "https://api.uploading.tech/v1", apiKey: process.env.TIMBRE_API_KEY });
const audio = await client.audio.speech.create({ model: "timbre-1", voice: "VOICE_ID", input: "Hello from Timbre." });
fs.writeFileSync("hello.mp3", Buffer.from(await audio.arrayBuffer()));

Models

timbre-1 is an alias for a dated snapshot, today timbre-1-2026-11-08. Pin the snapshot to never change version; use the alias to move with us. Every audio response names the snapshot that spoke in X-Model. GET /v1/models lists them; changes are announced in the changelog.

Voices

CallWhat it does
POST /v1/voicesMultipart: audio (3–30 s of speech, WAV / FLAC / OGG / MP3, under 10 MB), name, text (what the audio says) and consent=true. Returns {"id": "v_…"}.
GET /v1/voicesYour voices and the library voices ("preset": true).
GET /v1/voices/{id}One voice.
DELETE /v1/voices/{id}Deletes the voice and its reference audio immediately. A voice a project character uses answers 409 voice_in_use; give the character another voice first.

Sending consent=true states that the speaker agreed to their voice being cloned for your use. See the acceptable-use policy.

Projects and characters

A project is a show, a book or any series. Each character in it maps to one voice. Use the character id (chr_…) wherever a voice id goes (reference_id, voice). Scripts keep the same ids from episode to episode; to recast a character, change its voice once. Same routes under /v1/console/projects in the console.

CallWhat it does
POST /v1/projects{"name", "kind": "show" | "book" | "other", "notes"?} → the project with id (prj_…).
GET /v1/projectsYour projects, newest first, with character_count.
GET /v1/projects/{id}One project and its characters.
PATCH /v1/projects/{id}Any of name, kind, notes; fields you leave out stay as they are.
DELETE /v1/projects/{id}Deletes the project and its characters (not the voices).
POST /v1/projects/{id}/characters{"name", "voice", "notes"?}: names are unique in a project (case-insensitive); voice is a library voice or one of yours.
PATCH /v1/projects/{id}/characters/{cid}Any of name, voice, notes. The id does not change.
DELETE /v1/projects/{id}/characters/{cid}Deletes the character.

GET /v1/wallet

{"balance_bytes": 1000000, "balance_usd_cents": 1000, "reserved_bytes": 0, "concurrency_limit": 5}

balance_bytes is what you can spend now; reserved_bytes is held by requests in flight.

Billing

  • $10 per million UTF-8 bytes of text. An English letter is 1 byte; a Chinese character is 3. 100,000 bytes free on sign-up.
  • Prepaid packs from the console; see pricing. No subscription. Credit is valid for 12 months from purchase; unused paid credit is refundable within 14 days.
  • Charged only for requests that return audio. A failed or cancelled request costs nothing.
  • Send an Idempotency-Key header to retry safely: the same key never charges twice.
  • 402 insufficient_balance when the balance cannot cover the whole request.

Rate limits

120 requests a minute per key, and a cap on requests in flight per account. Every keyed response carries x-ratelimit-limit-requests, x-ratelimit-remaining-requests and x-ratelimit-reset-requests; a 429 carries Retry-After in seconds.

TierTotal purchasesRequests in flightRequests / min / key
Tier 1Any5120
Tier 2$100 or more15120
Tier 3$1,000 or more50120
DedicatedBy agreementCustomCustom

Errors

Errors use OpenAI's shape. Every response, error or not, carries x-request-id; quote it when you write to us. Send X-Client-Request-Id to have your own id echoed back.

{"error": {"message": "This request needs 1200 bytes; …", "type": "billing_error", "param": null, "code": "insufficient_balance"}}
StatuscodeWhen
401missing_key · invalid_keyNo key, or an unknown or revoked one.
402insufficient_balanceTop up in the console. Nothing was reserved.
404voice_not_found · not_foundNo such voice on this account, or no such route.
409already_completed · in_progress · idempotency_mismatchAn Idempotency-Key that was used before.
422invalid_request and othersA field is missing or out of range; param names it.
429rate_limited · concurrency_limitWait Retry-After seconds.
5xxsynthesis_failed · internal_errorNot charged. Safe to retry with the same Idempotency-Key.

Your data

  • Your text, your audio and your voices are never used to train any model.
  • Reference audio is kept only while the voice exists; delete it any time with DELETE /v1/voices/{id}.
  • Logs keep lengths, timings and byte counts, not the text or the audio.

About this demo

  • Serving: the live demo runs Qwen3-TTS 1.7B (Apache-2.0) on one A100 in the US (Iowa) and one in Tokyo (Google Cloud). A browser in the Americas is served from the US; elsewhere, by whichever answers faster. Rate-limited per visitor.
  • Your recording: transcribed once to check you read the sentence shown, held in memory for 15 minutes, then deleted. It is never written to disk and never trained on. Please clone only your own voice.
  • Library voices: held-out speakers from AISHELL-3 (Apache-2.0) and LibriTTS-R (CC BY 4.0), never in our training. The page shows takes the scorer heard as read right. Names and portraits are illustrative: the portraits are generated images, not the speakers.
  • Research preview.