---
title: "Text to speech"
method: POST
path: "/v1/tools/text-to-speech"
tags: ["Tools"]
---

# Text to speech

`POST /v1/tools/text-to-speech`

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.

## Request body

- 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, nullable — ISO-639-1 language hint for pronunciation (e.g. `en`, `es`, `zh`).
  - `pronunciationReplacements` PronunciationReplacement[]
    - `original` string, required
    - `replacement` string, required
  - `autoExpandPronunciationReplacements` boolean — 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` number — Speech rate multiplier, between 0.5 (half speed) and 2 (double speed). Defaults to the voice's default speed.
  - `numResults` integer — Number of output results to generate. Defaults to 1.
  - `isOutputTemporary` boolean — 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 — 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.

- StartToolExecutionResponse — Returned when a tool execution is started. Use `toolExecutionId` to poll for results or cancel.
  - `toolExecutionId` string, required — Execution id (e.g. `vg_tool_...`).

## Other responses

- `default` — Error

---

[API](https://skmtc.dev/videogen/apis/videogen-api.md) · [All operations](https://skmtc.dev/videogen/apis/videogen-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/videogen/videogen-api/revisions/33dda0455d67/schema)