# Speak text out loud in a saved voice

- **Method:** `POST`
- **Path:** `/api/v1/speak`
- **Operation ID:** `speak_api_v1_speak_post`
- **Tags:** Agent

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.

## Effective servers

- `http://127.0.0.1:8100`

  Voice Creator Pro on this computer

## Request body

**Required:** `true`

**Content type:** `application/json`

schema: `SpeakRequest`

- **`text` (required)**: `string`, minLength: `1`

  Text to speak
- **`deliver`**: `string`, possible values: `"play", "url"`, default: `"play"`

  '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.
- **`language`**: `string | null`

  Target language. Defaults to Auto.
- **`model`**: `string | null`

  Streaming-capable TTS model family. If omitted, uses the configured default agent model, then the active model (switching to a streaming model if needed).
- **`voice`**: `string | null`

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

**Example:**

```json
{
  "text": "Build finished, all tests passing.",
  "voice": "Morgan",
  "model": "qwen3-tts",
  "language": "English",
  "deliver": "play"
}
```

## Responses

### 200 Successful Response

**Content type:** `application/json`

schema: `SpeakResponse`

- **`model` (required)**: `string`

  Model family used for generation
- **`played_via` (required)**: `string`

  'app' (desktop UI played it), 'local' (speakers), or 'none' (deliver=url — caller plays)
- **`session_id` (required)**: `string`

  Streaming session ID (sessions expire \~10 minutes after generation)
- **`success` (required)**: `boolean`

  Whether speech generation was started/delivered
- **`voice_id` (required)**: `string`

  Resolved voice ID
- **`status_url`**: `string | null`

  deliver=url only: session status endpoint, to distinguish finished from failed
- **`stream_url`**: `string | null`

  deliver=url only: progressive WAV URL, playable while generation runs
- **`streaming`**: `boolean`, default: `true`

  Audio is streamed as it is generated
- **`voice_name`**: `string | null`

  Resolved voice display name

**Example:**

```json
{
  "success": true,
  "voice_id": "",
  "voice_name": "",
  "model": "",
  "session_id": "",
  "streaming": true,
  "played_via": "",
  "stream_url": "",
  "status_url": ""
}
```

### 400 No voice resolved (none passed, no default configured) or unknown model.

### 404 The requested voice was not found.

### 422 Validation Error

**Content type:** `application/json`

schema: `HTTPValidationError`

- **`detail`**: `array`

  **Items:**

  schema: `ValidationError`
  - **`loc` (required)**: `array of (string | integer)`
  - **`msg` (required)**: `string`
  - **`type` (required)**: `string`
  - **`ctx`**: `object`
  - **`input`**: `any`

**Example:**

```json
{
  "detail": [
    {
      "loc": [
        ""
      ],
      "msg": "",
      "type": "",
      "input": null,
      "ctx": {}
    }
  ]
}
```

### 500 Generation failed.

### 504 Generation timed out (600s limit).

## Schemas

- `HTTPValidationError` — shown above.
- `SpeakRequest` — shown above.
- `SpeakResponse` — shown above.
- `ValidationError` — shown above.