# OpenAI-compatible text-to-speech

- **Method:** `POST`
- **Path:** `/v1/audio/speech`
- **Operation ID:** `openai_speech_v1_audio_speech_post`
- **Tags:** Agent

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.

## Effective servers

- `http://127.0.0.1:8100`

  Voice Creator Pro on this computer

## Request body

**Required:** `true`

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

schema: `OpenAISpeechRequest`

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

  Text to synthesize
- **`instructions`**: `string | null`

  Accepted for OpenAI compatibility; ignored.
- **`model`**: `string | null`

  VCP model family. OpenAI model names (tts-1, gpt-4o-mini-tts, ...) are accepted and ignored — the configured default agent model is used instead.
- **`response_format`**: `string`, possible values: `"mp3", "wav"`, default: `"mp3"`

  Audio container. mp3 (64kbps, default) or wav (PCM16).
- **`speed`**: `number | null`

  Accepted for OpenAI compatibility; ignored.
- **`voice`**: `string | null`

  Saved voice name or ID. Unknown names (e.g. OpenAI's 'alloy') fall back to the configured default agent voice.

**Example:**

```json
{
  "input": "Hello from an agent.",
  "model": "qwen3-tts",
  "voice": "Morgan",
  "response_format": "mp3",
  "speed": 1,
  "instructions": ""
}
```

## Responses

### 200 Audio bytes, streamed progressively while synthesis runs.

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

`any`

**Example:**

```json
null
```

**Content type:** `audio/mpeg`

**Content type:** `audio/wav`

### 400 No voice resolved, or mp3 requested without bundled ffmpeg.

### 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.

## Schemas

- `HTTPValidationError` — shown above.
- `OpenAISpeechRequest` — shown above.
- `ValidationError` — shown above.