---
title: "Sync Text To Speech"
method: POST
path: "/text_to_speech"
tags: ["Synchronous"]
---

# Sync Text To Speech

`POST /text_to_speech`

Synthesise speech and return the audio file directly.

Validates quota, synthesises audio via :func:`_generate_tts_bytes`, writes the
result to a temporary file, and returns it as a ``FileResponse``.  The temp file is
deleted in a background task after the response is sent.

Args:
    tts_request: TTS parameters (text, voice, model, output format, etc.).
    background_tasks: FastAPI background-task queue used to schedule temp-file cleanup.
    token_service: Injected token validation service.
    _request: Raw FastAPI ``Request`` used for rate-limiting.
    x_api_key: Bearer API key from the ``x-api-key`` header.
    version: API version extracted from the ``version`` request header.
    tts_service_stub: gRPC stub connected to the XCODEC synthesis server.

Returns:
    FileResponse: Audio file in the format requested by ``tts_request.output_format``.

Raises:
    UsageLimitExceeded: When the token has exhausted its quota.

## Headers

- `version` 'v1'
- `X-Api-Key` string

## Request body

- TTSRequest
  - `__dev_toggles` DevToggles — Hidden dev-only flags for disabling external services during concurrency profiling. Accepted under the ``__dev_toggles`` JSON key. Silently ignored outside ENVIRONMENT=dev.
    - `disable_token_validation` boolean
    - `disable_postgresql` boolean
    - `disable_mongodb` boolean
    - `disable_rate_limiter` boolean
    - `disable_concurrency_limiter` boolean
    - `disable_pubsub` boolean
    - `disable_language_detector` boolean
    - `disable_sentence_splitter` boolean
    - `disable_normalizer` boolean
    - `disable_phonemizer` boolean
    - `disable_stp` boolean
    - `disable_xcodec` boolean
    - `disable_transcript_validation` boolean
    - `disable_stp_short_target_standalone` boolean, nullable
  - `model_id` 'async_flash_v1.0' | 'async_flash_v1.5' | 'async_pro_v1.0'
  - `normalize` boolean — Whether to normalize the input text. If False, the input text will be used as is.
  - `experimental_streaming_mode` boolean — Whether to stream audio in experimental mode.
  - `experimental_stp_v2` boolean — Use v2 STP prompt format (pr_speech_start/end). Only has effect when experimental_streaming_mode=True.
  - `transcript` string, required
  - `previous_request_id` string, uuid, nullable — ID returned in the X-Request-Id header of a previous TTS response. When provided, the last sentence of that request is appended AFTER the voice reference, enabling voice continuity across requests. Effective only for STP-based models (async_flash_v1.5, async_pro_v1.0). Silently falls back to the voice reference alone when the entry has expired, is missing, or belongs to a different token / voice / model / experimental_stp_v2 setting.
  - `language` 'en' | 'fr' | 'it' | 'de' | 'es' | 'pt' | 'ar' | 'ru' | 'ro' | 'ja' | 'he' | 'hy' | 'tr' | 'hi' | 'zh' | 'cmn' | 'ur'
  - `lang_detection_mode` 'llm' | 'fasttext'
  - `voice` VoiceIdSpecifier, required
    - `mode` 'id', required
    - `id` string, uuid, required
    - `__experimental_controls` object, nullable
  - `output_format` union — Default is raw / pcm_s16le / 44100 Hz
    - RawOutputFormat
      - `container` 'raw', required
      - `encoding` 'pcm_f32le' | 'pcm_s16le' | 'pcm_mulaw'
      - `sample_rate` integer, required — Sample rate in Hz (e.g., 44100)
      - `bit_rate` integer, nullable
    - WavOutputFormat
      - `container` 'wav', required
      - `encoding` 'pcm_f32le' | 'pcm_s16le'
      - `sample_rate` integer, required
      - `bit_rate` integer, nullable
    - Mp3OutputFormat
      - `container` 'mp3', required
      - `encoding` 'pcm_f32le' | 'pcm_s16le'
      - `bit_rate` integer
      - `sample_rate` integer, required
  - `sentence_splitter_chunk_size` integer, nullable — Number of characters to split the transcript into chunks. None if based on sentences.
  - `duration` number, nullable
  - `stability` integer — TTS's stability.
  - `speed_control` number — TTS's speed control.

## Response `200`

Successful Response

## Other responses

- `422` — Validation Error
- `429` — Too Many Requests / Concurrency / QUOTA EXCEEDED

---

[API](https://skmtc.dev/async/apis/text-to-speech-api-service.md) · [All operations](https://skmtc.dev/async/apis/text-to-speech-api-service/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/async/text-to-speech-api-service/revisions/9bfc541b6e9a/schema)