Skip to main content
Nothing here holds a session. You send audio and get text; you send text and get audio. What happens in between is the ordinary message path. Authentication is identical to the text endpoints — the subject’s bearer token, plus Patchwork-Connection if you route by connection. Provider keys are ours; the browser only ships and plays audio. If the workspace’s API has no voice provider configured, every endpoint here returns 503 voice_unavailable. That is a normal deployment state, not a fault.

​
Transcribe

POST /v1/voice/transcribe multipart/form-data, not JSON.
​
file
required
The recorded utterance.
​
string
Optional hint. Detected when omitted.
​
string
required
The transcript. Empty for a silent take.
​
number
Provider confidence, when it reports one.

​
Speak

POST /v1/voice/speak
​
string
required
What to say.
​
string
default:"markdown"
What the text is, not what comes back. markdown is rendered into something worth hearing before synthesis; plain is spoken as given. Anything else is 422 voice_invalid_format.
​
string
A voice from GET /v1/voice/voices. The platform default applies when omitted.
​
string
Optional language hint.
Returns raw audio bytes, not the JSON envelope — the one endpoint in the platform that does. The Content-Type is whatever the provider produced. Patchwork-Voice-Cache: hit | miss says whether the clip was served from cache, so repeated playback of the same reply costs nothing. Text that renders to nothing — markdown that was all formatting, say — is 422 voice_empty_text.

​
Voices

GET /v1/voice/voices
​
string
required
Pass as voice_id to Speak.
​
string
required
Display name for a picker.
​
string
Provider grouping.
​
string
A sample clip, for auditioning inside the picker.

​
Errors

​
Endpoints

Each has its own page in the sidebar, generated from the spec:
  • POST /v1/voice/transcribe — audio in, text out
  • POST /v1/voice/speak — text in, audio out
  • GET /v1/voice/voices — available voices
Voice is metered separately from agent runs, so these appear on their own in Activity. For the React SDK, which wraps all three, see the Voice guide.