New: AI video tools. Cut, clip, caption and dub your videos. See all video tools →
Voice Creator Pro logoVoice Creator Pro
Try For Free
Agent

Speak text out loud in a saved voice

POST
/api/v1/speak

REST mirror of the vcp_speak MCP tool for non-MCP agents and scripts.

Streams speech with the resolved voice/model. deliver: play plays it here (desktop UI via GET /api/v1/events/speak when subscribed, else the default output device) and blocks until done. deliver: url plays nothing on this machine and returns a progressive stream URL immediately. Speech is ephemeral — nothing is written to history.

Request Body

application/json
  1. body
text*Text

Text to speak

Length1 <= length
voice?|

Saved voice name or ID. If omitted, the configured default agent voice is used.

model?|

Streaming-capable TTS model family. If omitted, uses the configured default agent model, then the active model (switching to a streaming model if needed).

language?|

Target language. Defaults to Auto.

deliver?Deliver

'play' streams to this machine's speakers/app and blocks until done. 'url' plays nothing here and returns a progressive stream URL immediately for the caller to play.

Default"play"
Value in"play""url"

Response Body

Successful Response

application/json
  1. response
success*Success

Whether speech generation was started/delivered

voice_id*Voice Id

Resolved voice ID

voice_name?|

Resolved voice display name

model*Model

Model family used for generation

session_id*Session Id

Streaming session ID (sessions expire ~10 minutes after generation)

streaming?Streaming

Audio is streamed as it is generated

Defaulttrue
played_via*Played Via

'app' (desktop UI played it), 'local' (speakers), or 'none' (deliver=url — caller plays)

stream_url?|

deliver=url only: progressive WAV URL, playable while generation runs

status_url?|

deliver=url only: session status endpoint, to distinguish finished from failed

Example Request
curl -X POST 'http://127.0.0.1:8100/api/v1/speak' \  -H 'Content-Type: application/json' \  -d '{  "text": "Build finished, all tests passing."}'
Example Response
{  "success": true,  "voice_id": "string",  "voice_name": "string",  "model": "string",  "session_id": "string",  "streaming": true,  "played_via": "string",  "stream_url": "string",  "status_url": "string"}

Image Cancel POST

Stop a running generation. Images already finished stay available.

OpenAI-compatible text-to-speech POST

Drop-in for OpenAI's `POST /v1/audio/speech`, so OpenAI-compatible clients (OpenClaw, etc.) can point a `baseUrl` at this server. Send the API key as `Authorization: Bearer <key>`. OpenAI model/voice names fall back to the configured agent defaults. Speech is ephemeral — nothing is written to history, nothing plays on this machine.