Skip to main content
Cast controls delivery across a script: emotion, intensity, and performance units. Use Speak when you already know the exact text and only need ordinary speech synthesis. Use Cast when the delivery itself is part of the artifact. All Cast API paths live under /v1/cast/* and require cast:render.

​
1. Read live capabilities

Start every editor or automation from the capability response:
A typical response looks like this. The live list is authoritative; emotions and voices are filtered by account policy:
Do not assume every voice from the general catalog works on Cast, and do not hardcode an emotion that this response did not advertise.

​
2. Direct a script

Give Cast plain text. Non-empty lines are preserved as performance units; plain paragraphs are split by sentence:
Cast returns directed lines under lines:
Every emotion and intensity in that response is one Cast capabilities advertises, so a directed line can be sent straight to /v1/cast/speech or /v1/cast/render_jobs unchanged. Treat that result as an editable draft. Your application can let a producer change any advertised emotion or intensity before rendering.

​
3. Preview one line

Render one directed line synchronously while tuning delivery:
The response is WAV audio. Confirm stock_dorit_en_us (or any other id) is in the live voices[] list first. A voice outside Cast capabilities returns 422 unsupported_voice; refresh capabilities instead of retrying the same request.

​
4. Render a long project

Use the Cast workspace in the console to create and edit a project. The durable API submission takes that project’s cast_project_id, one compatible voice, and the final directed lines:
The API returns 202 with job_id, status, and a status_url to poll. Monitor render progress there, and download the completed artifact from the Cast project in the console. Reuse the same Idempotency-Key only when retrying the identical render. A different body with the same key returns 409 idempotency_conflict.

​
Failure handling

  • 403 forbidden: the key lacks cast:render.
  • 403 cast_emotion_unavailable: the requested emotion is not enabled for the account; render controls from capabilities.
  • 422 unsupported_voice: choose a voice returned by Cast capabilities.
  • 422 unsupported_emotion / 422 unsupported_intensity: the direction is not in the advertised palette. Refresh capabilities; do not retry the same body.
  • 429 rate_limit_exceeded: honor Retry-After.
  • A long-form submission failure does not make a preview unsafe to retry; use a new logical idempotency key only when the render content changes.

Cast API reference

Exact capability, direction, preview, and render schemas.

Speak

Use ordinary synthesis when you do not need directed performance.

Voice catalog

Browse stock and designed voices, then confirm Cast compatibility.

Errors and limits

Stable request errors, idempotency, and retry behavior.