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

# Sync Text To Speech With Timestamps

`POST /text_to_speech/with_timestamps`

Synthesise speech and return audio with per-word alignment timestamps.

Resolves the voice preset, validates quota, then calls the versioned gRPC handler
with ``include_durations=True``.  Returns a ``TTSAudioResponse`` containing
base64-encoded audio and character-level start/end times in milliseconds.

Args:
    tts_request: TTS parameters (text, voice, model, output format, etc.).
    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:
    TTSAudioResponse: Base64-encoded audio and word-level alignment data.

Raises:
    NotSupportedModel: When the requested model does not support the voice.
    VoiceNotFound: When the voice preset cannot be resolved.
    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

- TTSAudioResponse — Response model for the synchronous text-to-speech with timestamps endpoint. This model contains the generated audio as a base64-encoded string and the alignment data for synchronizing text with the audio.
  - `audio_base64` string, required — Base64-encoded audio data
  - `alignment` Alignment, required — Represents the alignment data for text-to-speech with timestamps. This model contains the timing information for each character in the generated speech, allowing applications to synchronize visual elements with the audio.
    - `words` string[], required — List of characters from the transcript
    - `word_start_times_milliseconds` number[], required — Start time of each character in milliseconds
    - `word_end_times_milliseconds` number[], required — End time of each character in milliseconds

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