Your first speech request.

Quickstart

1. Create an API key

   Continue with Google using your invited CastReader account and activate your developer workspace. Open API keys, give your key a name and create it. Expiration defaults to Never; choose 7, 30 or 90 days if you prefer. Copy the secret when it is shown once and keep it on your server.

2. Add your voice

   In My voices, choose Record myself, Invite a friend or Upload audio. Use a clear recording up to 4 MiB that you own or have permission to clone. A saved recording starts as Processing. Wait for Readybefore generating speech, then listen to the preview and copy the voice ID. You can also create a voice through the API.

3. Generate your first MP3

   Set your API key below. The example uses speech:generate; listing voices and reading usage need voices:read and usage:read on the same key.

   TerminalCopy code

   export CASTREADER_API_KEY="YOUR_API_KEY"
   # Resolve your network region first. Requires jq; sends no text or audio.
   export CASTREADER_API_BASE=$(curl --fail --silent --show-error \
     'https://voice.castreader.com/v1/route' \
     -H "Authorization: Bearer $CASTREADER_API_KEY" | jq -er '.base_url')

   Replace voice_YOUR_ID below with a Ready voice in the returned region. Your key and wallet are shared. See regional routing for resource lookup and retry rules.

   cURL · MP3Copy code

   curl "$CASTREADER_API_BASE/audio/speech" \
     -H "Authorization: Bearer $CASTREADER_API_KEY" \
     -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: example-speech-0001' \
     --data '{"model":"clone-v1","voice_id":"voice_YOUR_ID",
       "text":"Hello from my application.","language":"en",
       "output_format":"mp3","speed":1}' \
     --fail-with-body --dump-header speech.headers --output speech.mp3

   Open speech.mp3 to listen. Keep example-speech-0001 for retries of this exact request; choose a new idempotency key only for a new generation. Change output_format to wav and the output filename to speech.wav for WAV audio, using a new idempotency key for that separate generation. Response headers and the receipt are saved to speech.headers. If cURL exits with an error, inspect the response before playing the file.

4. Check your usage

   Open Usage to see the request, billable characters, trial use and exact charge. Or read it from your backend:

   cURL · UsageCopy code

   curl "$CASTREADER_API_BASE/usage" \
     -H "Authorization: Bearer $CASTREADER_API_KEY" \
     --fail-with-body

5. Add credits when you need them

   Your 3,000 trial characters are used first while valid and available. Open API billing for your balance, prepaid top-ups and payment history. Credits are separate from CastReader Pro. View pricing →

Authentication and API keys

Sign in with the Google identity already linked to your CastReader account. Console manages keys using your login session; your backend authenticates with an API key. Email codes are a backup sign-in method for eligible accounts. A CastReader subscription does not include API credits.

Send a project key in the Authorization header on public API requests; GET /v1/health is the only endpoint that does not require a key. Console uses your signed-in account to manage keys; API requests use Bearer authentication.

Authorization: Bearer YOUR_API_KEY

Create keys in Console → API keys. The full secret is displayed once. Expiration defaults to Never; 7-, 30- and 90-day options are available. Under advanced settings, limit scopes, allowed voices or a monthly budget to match your integration. A voice-restricted key cannot register a new voice.

Keep keys in your server’s secret manager. Rotate a key when replacing a credential; copy its replacement secret once and update your backend. An optional overlap lets the old key remain valid until the earlier of the overlap deadline and its existing expiry. Revoke a compromised key immediately. Revoked or expired keys return 401.

Every request checks project access, scopes and voice restrictions. The key creator must retain an active Owner, Admin or Developer role and an available verified account. Keep the permanent API key out of browser JavaScript, mobile binaries, URLs and public repositories.

Voice registration and permission

Each workspace allows two active voices and 5 new registrations per UTC day. GET /v1/models reports active_voice_limit and daily_voice_registrations for the deployment. Processing and deleting voices count toward the active limit; failed, revoked and deleted voices do not. Deleting a voice does not restore that day’s registration allowance. Exceeding either limit returns 429 with voice_registration_limit.

List voices with GET /v1/voices?limit=20. The response is {data: [...], has_more: true, next_cursor: "..."}. The default page size is 20; limit accepts 1–100. If has_more is true, pass the returned next_cursor unchanged as the next request’s cursor query parameter. Encode it with your URL builder; treat it as opaque. The last page has next_cursor: null. Results are ordered newest first and each page checks your current project and voice permissions.

Use a key with voices:write and unrestricted voice access to register a new voice. The multipart fields below use self only when you are the speaker.

curl "$CASTREADER_API_BASE/voices" \
  -H "Authorization: Bearer $CASTREADER_API_KEY" \
  -H 'Idempotency-Key: example-voice-0001' \
  -F 'name=My voice' -F 'language=en' \
  -F 'reference_audio=@reference.wav;type=audio/wav' \
  -F 'consent_type=self' -F 'subject_name=Your name' \
  -F 'consent_confirmed=true' -F 'terms_version=voice-consent-v1' \
  --fail-with-body

For another speaker, use consent_type=authorized and include proof_reference, an 8–1,000 character reference to their explicit permission. Always provide subject_name, consent_confirmed=true and terms_version=voice-consent-v1. Optional reference_text is limited to 600 Unicode code points.

Supported upload MIME types are audio/wav, audio/x-wav, audio/mpeg, audio/mp4, audio/webm, audio/ogg and audio/flac. The name is 1–80 characters and the subject name is 1–120. The reference language must be enabled.

The Voice response contains id, object: voice, name, status, language, voice_version, created_at, updated_at and nullable error. States are processing, ready, failed, revoked, deleting and deleted. The preview endpoint can return 404 when no preview is available.

Renaming changes only the display name. Deleting revokes permission before asynchronous artifact cleanup. A voice ID from another project grants no access. Read the data and consent policy.

Use a recording you own or have explicit speaker permission to clone. A publicly available demo recording is not a grant to publish or commercially offer the cloned voice. Internal test samples remain private and do not replace the permission required for your use.

Generate speech

Send the following JSON fields to POST /v1/audio/speechwith a ready voice ID and an Idempotency-Key. Complete requests return MP3 or WAV audio. For the first cURL request, follow the quickstart. Keep the input within the model limits before submitting.

Speech request body

This configuration permits 120 normalized code points per short request and these languages: en. Check GET /v1/models on the deployment you call. A JSON request has a 64 KiB body limit.

For audio word timings, add return_timestamps: true. Read the v3 speech timestamp guide for examples, word-group behavior, queued jobs and billing.

Read the metering receipt

Complete audio responses include X-Request-ID, X-Model-Revision, X-Voice-Version, X-Billable-Characters, X-Trial-Characters, X-Charged-USD, X-Idempotency-Replayed and X-Result-Expires-At.

GET /v1/requests/{request_id} returns id, status, voice_id, pinned model/voice/price versions, creation and completion dates, result_url, timestamps_url, error and usage. Usage contains billable_characters, trial_characters, charged_usd, reserved_usd and metering_version. USD decimals are strings; the active reservation becomes a charge only on success.

Result URLs are relative authenticated API paths. Output audio is retained privately for at most 24 hours, according to result_expires_at. The original key or another currently authorized key in the project can retrieve it. Voice revocation blocks retained downloads immediately; expired results return 410.

Usage and API billing

API usage costs $12 per million normalized Unicode code points, calculated at $0.000012 per character. The current enrollment configuration provides 3,000 trial characters; expiry and daily allowance also apply. Review pricing and inspect your actual wallet before generating.

POST /v1/usage/estimate accepts the speech body and returns billable_characters, trial_characters, estimated_charge_usd, maximum_charge_usd, balance_sufficient, metering and price versions. It creates no reservation. Trial availability and existing reservations can change between the estimate and generation; an estimate does not authorize an otherwise restricted request.

The balance endpoint returns wallet fields for an Owner-created key: workspaceId, paidBalanceMicrousd, paidReservedMicrousd, availablePaidMicrousd, paidDebtMicrousd, trialRemainingCharacters, trialReservedCharacters and trialExpiresAt. Monetary values are integer strings in micro-USD.

A member-created key receives project_id, nullable monthly_budget_usd, charged_usd, reserved_usd and workspace_wallet_visible: false. Workspace funds remain restricted to Owner and Billing users in Console.

Owner and Billing users can open API billing to start a Stripe Checkout top-up within the amount range shown for that deployment. On return, Console checks the workspace’s payment record for up to a minute and refreshes the wallet after confirmation. A delayed confirmation remains pending; use Check payment status or Refresh instead of paying again. Payment history includes recorded top-ups and refunds. The billing portal is available when configured and this workspace has a payment customer.

Idempotency, errors and retries

Speech and voice registration require an 8–128 character Idempotency-Key containing ASCII letters, numbers, dots, underscores, colons or hyphens. Give each logical operation its own key and retain it alongside the request ID. Retry the same input with the same key; changed input returns 409.

A completed speech retry returns the original retained result without another charge. An in-flight conflict includes the original request ID in error details; the top-level error request ID identifies the error response itself. Query the original operation after a network failure. Retry retryable errors with bounded exponential backoff and jitter, honoring Retry-After.

Never automatically mint a new key after an ambiguous timeout. A deliberate new attempt after a confirmed terminal failure requires a new key. Expired audio returns 410 and cannot be recovered by retrying the old request.

{
  "error": {
    "code": "concurrency_limit_exceeded",
    "message": "Generation capacity is currently occupied.",
    "request_id": "req_ERROR_RESPONSE_ID",
    "retryable": true
  }
}

Authentication and validation errors do not charge. Other 5xx responses can leave an operation awaiting reconciliation: inspect its receipt before starting again. A network timeout alone is not proof of zero usage.

Maintenance and feature availability

If speech processing is temporarily unavailable while admission remains enabled, you can still save recordings and create friend invitations in the console, subject to workspace limits. Saved voices stay in Processing until the service can prepare them. Existing previews remain accessible. This differs from an explicit admission pause, described below.

During an admission pause, new generation and voice registration return 503 with admission_paused and retryable: true. Completed speech retries can still replay the retained result with the original idempotency key. Read existing requests, check their receipts and retry new work with bounded backoff after service resumes.

A full admission pause also blocks new top-ups. Existing reads, authorized retained downloads, key revocation, voice deletion and payment webhook processing remain available while the overall service is enabled. Turning off the entire service returns 404 instead. A configured feature or worker is not a health check: consult the service status and actual API response.

The preview rate limit is 60 public API requests per minute per key, including polling. Generation also obeys workspace and service concurrency limits. Use moderate polling intervals and back off on 429.

Generation reserves funds and capacity first, then charges after verified audio is durably stored. If a timed-out worker may still be running, its reservation remains until reconciliation establishes the outcome. A client disconnect does not prove that nothing was charged.

HTTP reference

Use Authorization: Bearer <key>. JSON requests require Content-Type: application/json; unknown fields are rejected. Audio endpoints return binary or NDJSON as documented. The OpenAPI document contains the full schemas and response types.

/v1/balance is an alias for /v1/billing/balance. Advanced, separately enabled endpoints remain documented in the OpenAPI specification and advanced reference.

Node.js and Python

The repository contains private Node.js 22+ and Python 3.11+ clients in packages/voice-api-sdk. They are not published npm or PyPI packages. Use the supplied source files and their README. Both clients support complete MP3/WAV generation, optional v3 timestamps, request receipts and safe retries. cURL works immediately without installing a client.

// Preview source client, Node.js 22+. Run on your backend.
import { writeFile } from 'node:fs/promises';
import { VoiceAPI } from './index.mjs';

const client = new VoiceAPI({
  apiKey: process.env.CASTREADER_API_KEY,
  baseURL: process.env.CASTREADER_API_BASE,
});
const result = await client.speech({
  voice_id: process.env.CASTREADER_VOICE_ID,
  text: 'Hello from my application.',
  language: 'en',
}, { idempotencyKey: 'sdk-example-speech-0001' });
await writeFile('speech.mp3', result.audio);
console.log(result.requestId, result.chargedUSD);

# Preview source client, Python 3.11+. Run on your backend.
import os
from pathlib import Path
from voice_api import VoiceAPI

client = VoiceAPI(os.environ['CASTREADER_API_KEY'],
                  os.environ['CASTREADER_API_BASE'])
result = client.speech('Hello from my application.',
                       os.environ['CASTREADER_VOICE_ID'],
                       idempotency_key='sdk-example-speech-0001')
Path('speech.mp3').write_bytes(result['audio'])
print(result['request_id'], result['charged_usd'])

SDK retries within one generating operation retain its idempotency key. A new method call without the previous key creates a new logical request. Store the key before starting the operation so your application can reconcile process crashes or ambiguous responses.

Advanced reference

Complete MP3 and WAV generation is the current product. Streaming, long jobs, realtime and automatic recharge are not open in this release. These implementation references are for separately enabled integrations; they are not required for your first request.