> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.videogen.io/rest-api-reference/tools/text-to-speech/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.videogen.io/_mcp/server.

# Text to speech

POST https://api.videogen.io/v1/tools/text-to-speech
Content-Type: application/json

Convert text into a spoken audio file. Only voices with `supportsDirectToolExecution` set to true can be used. Optionally choose a voice, language, speed, and pronunciation overrides.

Reference: https://docs.videogen.io/rest-api-reference/tools/text-to-speech

## Authentication

- `Authorization` header (bearer token, required) — API key from [app.videogen.io/api](https://app.videogen.io/api). The full key is only shown once when you create it.

## Request

### Body (application/json)

This endpoint expects a TextToSpeechRequest.

- `ttsText` (string, required)
- `voiceId` (string, required) — Catalog `displayName` (e.g. `Matilda`) or voice id from `GET /v1/resources/tts-voices` (e.g. `vg_voic_...`). Only voices with `supportsDirectToolExecution` set to true are accepted.
- `speechLanguageCode` (string, optional, nullable) — ISO-639-1 language hint for pronunciation (e.g. `en`, `es`, `zh`).
- `pronunciationReplacements` (list of PronunciationReplacement, optional)
- `autoExpandPronunciationReplacements` (boolean, optional) — When true, automatically expands numbers, symbols, acronyms, and other non-word tokens into their spoken forms before synthesis so the voice pronounces them correctly (e.g. `$100` → `one hundred dollars`, `NASA` → `nasa`, `3rd` → `third`). Defaults to false when omitted.
- `voiceSpeed` (double, optional) — Speech rate multiplier, between 0.5 (half speed) and 2 (double speed). Defaults to the voice's default speed.
- `numResults` (integer, optional, default: 1) — Number of output results to generate. Defaults to 1.
- `isOutputTemporary` (boolean, optional, default: false) — When true, generated files are temporary. Temporary files are guaranteed to be available for 24 hours, after which they may be archived at any time. Temporary files are not analyzed (no description, transcript, or embedding will be generated), so they will not appear in search results. Defaults to false.
- `hideFromUi` (boolean, optional, default: false) — When true, generated files are hidden from the VideoGen Media page by default. They remain accessible through the API. Defaults to false.

## Response

### 202

Execution accepted; poll until complete.

- `toolExecutionId` (string, required) — Execution id (e.g. `vg_tool_...`).

## Types

### PronunciationReplacement

- `original` (string, required)
- `replacement` (string, required)

## Examples

**Request**

```json
{
  "ttsText": "Welcome to VideoGen, your AI-powered video creation assistant.",
  "voiceId": "vg_voic_7t1wdka3tmk"
}
```

**Response**

```json
{
  "toolExecutionId": "vg_tool_ccm3abc123defcm3xyz789ghi"
}
```

**SDK Code**

```typescript
import { VideoGen } from "@videogen/sdk";

const client = new VideoGen({ apiKey: "sk_videogen_live_..." });

await client.tools.textToSpeech({
  ttsText: "Welcome to VideoGen, your AI-powered video creation assistant.",
  voiceId: "vg_voic_7t1wdka3tmk",
});
```

```python
from videogen import VideoGen

client = VideoGen(api_key="sk_videogen_live_...")

client.tools.text_to_speech(
    tts_text="Welcome to VideoGen, your AI-powered video creation assistant.",
    voice_id="vg_voic_7t1wdka3tmk",
)
```

> HTTP API with TypeScript and Python SDKs for generating image, video, and audio assets with VideoGen.