API documentation

Convert text into audio with an asynchronous API. Submit text, poll for completion, then download the MP3. All endpoints use https://toneborne.com.

1. Create an API key

Create a named key in your dashboard. Copy it when it appears — it is shown only once. Send it in the Authorization header on every request. Never expose it in browser or mobile client code.

2. Submit a generation

curl -X POST https://toneborne.com/v1/generations \
  -H "Authorization: Bearer $TONEBORNE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: generation-123-take-1" \
  -d '{"title":"Growing herbs at home",
       "text":"A sunny windowsill is a good place to start a small herb garden.",
       "voice":"take4"}'

A new job returns HTTP 202 with an id and status. The supported voice is take4 (default English voice). Title is optional. The combined trimmed title and text may contain up to 10,000 Unicode characters. Spaces and punctuation count; client-side markup is sent as text. Send plain English text.

{
  "id": "gen_…",
  "status": "queued",
  "chars": 85,
  "free_characters": 85,
  "paid_characters": 0,
  "audio_url": null
}

This is an illustrative response. Use a new Idempotency-Key for a new take. Retrying the same key and payload returns the existing job without reserving characters again; reusing it with different content returns 409.

3. Poll and download

curl https://toneborne.com/v1/generations/GENERATION_ID \
  -H "Authorization: Bearer $TONEBORNE_KEY"

# When status is "done":
curl https://toneborne.com/v1/generations/GENERATION_ID/audio \
  -H "Authorization: Bearer $TONEBORNE_KEY" \
  --output narration.mp3

Poll every five seconds. Status moves from queued to processing, then done or failed. Generation is asynchronous and depends on available worker capacity. Check progress for current work. Audio is retained for seven days; download it promptly.

4. Save your audio

Download and store the MP3 for use in your projects. Toneborne download links require authentication, and generated audio is retained for seven days. Use your own stored copy when sharing or publishing.

Endpoints

Credits and limits

Every account has 1,000,000 free characters per calendar month (UTC), shared by the playground and every API key. We reserve free characters first, then purchased credits. Successful jobs consume the reservation. Failed or timed-out jobs return it to the original allowance month or purchased balance.

Pay-as-you-go packs cost $5 per million with a 10-million minimum. Active Studio members pay $3 per million. Purchased characters do not expire. Revoking a key prevents future calls but does not cancel jobs already submitted.

Up to three generations may be pending per account. The API allows 180 requests per minute per account and generation submission allows 30 per minute, subject to queue limits. Request history includes generation submissions, polling, downloads and errors after authentication.

Errors

Errors return a JSON error string. Retry transient failures with backoff, keeping the original Idempotency-Key when retrying a submission.