> ## Documentation Index
> Fetch the complete documentation index at: https://docs.breezeblue.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Convert with timestamps

> Generate speech with word timestamps. Returns one complete JSON response, or a background job with delivery=async.

<section className="api-next-steps" aria-label="Continue building">
  ## Continue building

  <Columns cols={2}>
    <Card title="Write instructions" icon="sliders-horizontal" href="/guides/voice-instruction-prompting">Choose intent, emotion, and delivery.</Card>
    <Card title="Speech timing" icon="clock" href="/guides/speech-timing">Build captions with word timing.</Card>
    <Card title="Convert text to speech" icon="braces" href="/api-reference/text-to-speech/convert-text-to-speech">Generate audio without word timing.</Card>
    <Card title="Streaming timestamps" icon="radio" href="/api-reference/text-to-speech/stream-speech-with-word-timestamps">Stream audio with word timing.</Card>
  </Columns>
</section>


## OpenAPI

````yaml /openapi.json post /v1/text-to-speech/{voice_id}/with-timestamps
openapi: 3.1.0
info:
  title: Breeze Developer API
  description: >-
    Breeze Developer API for models, voices, text-to-speech, history, balance,
    usage, and browser-managed API keys.
  version: 1.0.0
servers:
  - url: https://api.breeze.blue
security: []
tags:
  - name: Models
    description: Supported TTS models.
  - name: Text to Speech
    description: Text-to-speech synthesis and instruction enhancement.
  - name: Voices
    description: Saved voices and voice settings.
  - name: Voice Previews
    description: Create, audition, and save temporary voice previews.
  - name: Account
    description: Balance, usage, and API keys.
  - name: History
    description: Generated audio history.
paths:
  /v1/text-to-speech/{voice_id}/with-timestamps:
    post:
      tags:
        - Text to Speech
      summary: Convert with timestamps
      description: >-
        Generate speech with word timestamps. Returns one complete JSON
        response, or a background job with delivery=async.
      operationId: tts_generate_with_timestamps
      parameters:
        - name: voice_id
          in: path
          required: true
          schema:
            title: Voice Id
            type: string
          description: >-
            Voice ID to use for speech generation. See [List
            voices](https://docs.breezeblue.ai/api-reference/voices/list-voices).
        - name: output_format
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Output Format
            default: mp3
          description: >-
            Audio encoding: mp3, wav, flac, pcm, aac, or opus. Optional sample
            rate and bitrate profiles follow ordinary synchronous TTS, e.g.
            wav_48000. Default: mp3. See [Output
            formats](https://docs.breezeblue.ai/concepts/output-format).
        - name: delivery
          in: query
          required: false
          schema:
            type: string
            pattern: ^(sync|async)$
            default: sync
            title: Delivery
          description: >-
            sync (default) returns audio_base64 and word_timestamps. async
            returns a job ID immediately; poll Get generation job for the
            result. See [Async
            jobs](https://docs.breezeblue.ai/guides/text-to-speech#async-jobs).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TtsConvertWithTimestampsRequest'
      responses:
        '200':
          description: >-
            Complete audio and word timestamps. The history-item-id header
            identifies the saved audio.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SpeechWithTimestampsResponse'
          headers:
            history-item-id:
              description: History item ID for the generated audio.
              schema:
                type: string
            x-breeze-api-key-id:
              description: >-
                Public API key identifier used to authenticate the request, when
                an API key was used.
              schema:
                type: string
        '202':
          description: >-
            Accepted background TTS job. Poll Get generation job for
            word_timestamps and the audio download URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncTtsJobResponse'
          headers:
            x-breeze-api-key-id:
              description: >-
                Public API key identifier used to authenticate the request, when
                an API key was used.
              schema:
                type: string
        '400':
          description: HTTP 400 error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: HTTP 401 error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: HTTP 403 error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: HTTP 404 error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: HTTP 422 error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorResponse'
        '429':
          description: HTTP 429 error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '502':
          description: HTTP 502 error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: HTTP 503 error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '504':
          description: HTTP 504 error response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - ApiKeyAuth: []
      x-codeSamples:
        - lang: cURL
          label: cURL
          source: |-
            curl \
              --request POST \
              --url "https://api.breeze.blue/v1/text-to-speech/voc_xeh3w54cqvnp/with-timestamps" \
              --header "xi-api-key: $BREEZE_API_KEY" \
              --header "Content-Type: application/json" \
              --data '{
              "text": "Hello world.",
              "model_id": "breeze-tts-2-multilingual",
              "language_code": "en"
            }'
        - lang: Python
          source: >-
            import base64

            from pathlib import Path

            from breeze_blue import BreezeBlue


            client = BreezeBlue()

            result =
            client.text_to_speech.convert_with_timestamps("voc_example",
            text="Hello world.", model_id="breeze-tts-2-multilingual",
            output_format="wav")

            Path("speech.wav").write_bytes(base64.b64decode(result["audio_base64"]))

            print(result["word_timestamps"])
        - lang: TypeScript
          source: >-
            import { writeFile } from "node:fs/promises";

            import { BreezeBlueClient } from "@breeze.blue/sdk";

            const client = new BreezeBlueClient();

            const result = await
            client.textToSpeech.convertWithTimestamps("voc_example", { text:
            "Hello world.", modelId: "breeze-tts-2-multilingual" }, {
            outputFormat: "wav" });

            await writeFile("speech.wav", Buffer.from(result.audioBase64,
            "base64"));

            console.log(result.wordTimestamps);
components:
  schemas:
    TtsConvertWithTimestampsRequest:
      properties:
        text:
          type: string
          minLength: 1
          title: Text
          description: >-
            Text to synthesize. Up to 1000 characters by default; accounts with
            an approved higher limit may send up to their configured limit, at
            most 2000 characters. See [Audio
            tags](https://docs.breezeblue.ai/guides/audio-tags).
        model_id:
          anyOf:
            - type: string
              maxLength: 120
              minLength: 1
            - type: 'null'
          title: Model Id
          description: >-
            Model ID for speech generation. Selected automatically when omitted.
            See [List
            models](https://docs.breezeblue.ai/api-reference/models/list-models).
        language_code:
          anyOf:
            - type: string
              maxLength: 2
              minLength: 2
              pattern: ^[A-Za-z]{2}$
            - type: 'null'
          title: Language Code
          description: >-
            ISO 639-1 two-letter language code supported by the selected model.
            See [supported language
            codes](https://docs.breezeblue.ai/concepts/multilingual).
        instructions:
          anyOf:
            - type: string
            - type: 'null'
          title: Instructions
          description: >-
            Performance instructions, written in the same language as the input
            text. See [Expressive
            controls](https://docs.breezeblue.ai/guides/text-to-speech#tuning-expressive-controls),
            [Voice instruction
            prompting](https://docs.breezeblue.ai/guides/voice-instruction-prompting).
        voice_settings:
          anyOf:
            - $ref: '#/components/schemas/TtsVoiceSettingsPayload'
            - type: 'null'
          description: >-
            Optional per-request voice settings override. See [Voice
            settings](https://docs.breezeblue.ai/concepts/voices#voice-settings).
      additionalProperties: false
      type: object
      required:
        - text
      title: TtsConvertWithTimestampsRequest
      description: Speech with complete word timing; ordinary TTS fields only.
    SpeechWithTimestampsResponse:
      properties:
        audio_base64:
          description: >-
            Complete audio encoded as base64. Decode before saving or playback.
            See [Decode audio and
            timing](https://docs.breezeblue.ai/guides/speech-timing).
          title: Audio Base64
          type: string
        content_type:
          description: MIME type of the decoded audio, matching output_format.
          title: Content Type
          type: string
        word_timestamps:
          description: >-
            Complete word/token list, relative to the delivered audio in
            seconds. See [Speech
            timing](https://docs.breezeblue.ai/guides/speech-timing).
          items:
            $ref: '#/components/schemas/WordTimestampResponse'
          title: Word Timestamps
          type: array
      required:
        - audio_base64
        - content_type
        - word_timestamps
      title: SpeechWithTimestampsResponse
      type: object
    AsyncTtsJobResponse:
      properties:
        generation_job_id:
          title: Generation Job Id
          type: string
        history_item_id:
          title: History Item Id
          type: string
        status:
          title: Status
          type: string
      required:
        - generation_job_id
        - history_item_id
        - status
      title: AsyncTtsJobResponse
      type: object
    ErrorResponse:
      properties:
        ok:
          default: false
          title: Ok
          type: boolean
        code:
          title: Code
          type: string
        detail:
          title: Detail
          type: string
        error:
          title: Error
          type: string
        meta:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          default: null
          title: Meta
      required:
        - code
        - detail
        - error
      title: ErrorResponse
      type: object
    ValidationErrorResponse:
      properties:
        ok:
          default: false
          title: Ok
          type: boolean
        code:
          title: Code
          type: string
        detail:
          title: Detail
          type: string
        error:
          title: Error
          type: string
        meta:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Meta
      required:
        - code
        - detail
        - error
      title: ValidationErrorResponse
      type: object
    TtsVoiceSettingsPayload:
      properties:
        guidance_scale:
          anyOf:
            - type: number
              maximum: 10
              minimum: 1
            - type: 'null'
          title: Guidance Scale
          description: >-
            Generation guidance strength. Accepted range: 1.0 to 10.0. See
            [Voice
            settings](https://docs.breezeblue.ai/concepts/voices#voice-settings).
          default: 1
        speed:
          type: number
          maximum: 2
          minimum: 0.5
          title: Speed
          description: >-
            Speech speed multiplier that preserves pitch. Range: 0.5–2.0;
            default: 1.0.
          default: 1
        volume:
          type: number
          maximum: 2
          minimum: 0.01
          title: Volume
          description: >-
            Request-only linear amplitude multiplier. Range: 0.01–2.0 (1%–200%);
            default: 1.0. Values above 1.0 may clip peaks. Does not normalize
            loudness.
          default: 1
      additionalProperties: false
      type: object
      title: TtsVoiceSettingsPayload
    WordTimestampResponse:
      properties:
        index:
          description: Word/token index, shared across fragments of the same word.
          minimum: 0
          title: Index
          type: integer
        word:
          title: Word
          type: string
        start:
          description: Start in seconds from the generated audio origin.
          minimum: 0
          title: Start
          type: number
        end:
          description: End in seconds from the generated audio origin.
          minimum: 0
          title: End
          type: number
      required:
        - index
        - word
        - start
        - end
      title: WordTimestampResponse
      type: object
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: xi-api-key
      description: Breeze Developer API key.

````