/v1/cast/* and require cast:render.
Settings and customization
Use the same voice throughout a render; per-line voice changes are unsupported.
The capability response is authoritative for the account’s available controls.
1. Read live capabilities
Start every editor or automation from the capability response:2. Direct a script
Give Cast plain text. Non-empty lines are preserved as performance units; plain paragraphs are split by sentence:lines:
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: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 directed lines
The API accepts one top-levelvoice for the entire script or lines array.
Select it from Cast capabilities. Lines support text, emotion, and
intensity; per-line voice changes are not supported. A console project and
cast_project_id are not required.
Submit the final directed lines:
202 with job_id, status, and a status_url to poll.
Poll the returned status_url until status is done or error. When done,
retrieve /v1/cast/render_jobs/{job_id}/audio with the same authenticated client.
MCP clients use get_cast_render and then get_cast_audio. Keep the original
job ID; do not resubmit after an uncertain timeout. The public render route
does not promise idempotent resubmission.
A successful job can report emotion_applied and emotion_applied_lines.
These are server-reported application indicators, not a listening assessment.
Failure handling
403 forbidden: the key lackscast: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: honorRetry-After.- Preserve the original job ID on pending work. If submission times out before returning an ID, reconcile the outcome before attempting another render.
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.