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:
The response lists Cast-compatible voices, emotions, intensity_tiers, and languages. Do not assume every voice from the general voice catalog works on Cast, and do not hardcode an emotion that the capability 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:
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. 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, cast_project_id, status, and progress. Monitor render progress 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.
  • 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.