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

# Stream speech with word timestamps

> Stream speech and word timestamps as newline-delimited JSON (NDJSON). Each line contains audio, timing updates, or an error. See [Speech timing](https://docs.breezeblue.ai/guides/speech-timing) for stream handling.

<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 with timestamps" icon="braces" href="/api-reference/text-to-speech/convert-with-timestamps">Get complete audio with word timing.</Card>
    <Card title="Output formats" icon="file-audio" href="/concepts/output-format">Choose and decode an audio format.</Card>
  </Columns>
</section>


## OpenAPI

````yaml /openapi.json post /v1/text-to-speech/{voice_id}/stream/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}/stream/with-timestamps:
    post:
      tags:
        - Text to Speech
      summary: Stream speech with word timestamps
      description: >-
        Stream speech and word timestamps as newline-delimited JSON (NDJSON).
        Each line contains audio, timing updates, or an error. See [Speech
        timing](https://docs.breezeblue.ai/guides/speech-timing) for stream
        handling.
      operationId: tts_stream_with_timestamps
      parameters:
        - name: voice_id
          in: path
          required: true
          schema:
            title: Voice Id
            type: string
          description: >-
            Voice ID. 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: pcm
          description: >-
            Audio encoding: pcm, mp3, or wav. Default: pcm. Decode audio_base64
            before playing. See [Output
            formats](https://docs.breezeblue.ai/concepts/output-format).
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TtsWithTimestampsRequest'
      responses:
        '200':
          description: >-
            NDJSON; each line is a speech timing chunk. A stream error instead
            contains an error object with code and message.
          content:
            application/x-ndjson:
              schema:
                $ref: '#/components/schemas/SpeechTimingChunkResponse'
          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
        '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'
        '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/stream/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",
              "timestamp_mode": "chunk"
            }'
        - lang: Python
          source: >-
            from breeze_blue import BreezeBlue


            client = BreezeBlue()

            with client.text_to_speech.stream_with_timestamps("voc_example",
            text="Hello world.") as stream:
                for chunk in stream:
                    print(chunk["word_timestamps"])
        - lang: TypeScript
          source: >-
            import { BreezeBlueClient } from "@breeze.blue/sdk";

            const client = new BreezeBlueClient();

            const stream = await
            client.textToSpeech.streamWithTimestamps("voc_example", { text:
            "Hello world." });

            for await (const chunk of stream) console.log(chunk.wordTimestamps);
components:
  schemas:
    TtsWithTimestampsRequest:
      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).
        timestamp_mode:
          type: string
          enum:
            - chunk
            - lookahead
          title: Timestamp Mode
          default: chunk
          description: >-
            See [Streaming timing
            modes](https://docs.breezeblue.ai/guides/speech-timing#streaming-audio-with-timing).
      additionalProperties: false
      type: object
      required:
        - text
      title: TtsWithTimestampsRequest
    SpeechTimingChunkResponse:
      properties:
        audio_base64:
          description: >-
            Base64 audio bytes; may be empty for metadata-only updates. See
            [Decode audio and
            timing](https://docs.breezeblue.ai/guides/speech-timing).
          title: Audio Base64
          type: string
        word_timestamps:
          items:
            $ref: '#/components/schemas/WordTimestampResponse'
          title: Word Timestamps
          type: array
          description: >-
            See [Speech
            timing](https://docs.breezeblue.ai/guides/speech-timing).
      required:
        - audio_base64
        - word_timestamps
      title: SpeechTimingChunkResponse
      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.

````