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

# Synthesize speech

Kick off one-shot synthesis jobs for short responses. This endpoint reuses the same provider layer and cache that powers the streaming WebSocket experience.

<Callout>
  Reuse identical `tts_config` inputs to hit the cache and avoid extra provider round-trips.
</Callout>


## OpenAPI

````yaml POST /speak
openapi: 3.1.0
info:
  title: Sayna API
  description: >-
    Real-time voice processing server with Speech-to-Text (STT) and
    Text-to-Speech (TTS) services
  contact:
    name: Sayna
    url: https://api.sayna.ai
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  version: 0.1.0
servers:
  - url: https://api.sayna.ai
    description: Production API
  - url: http://localhost:3001
    description: Local development
security: []
tags:
  - name: health
    description: Health check endpoints
  - name: voices
    description: TTS voice management
  - name: tts
    description: Text-to-speech synthesis
  - name: livekit
    description: LiveKit room and token management
  - name: recordings
    description: Recording download operations
  - name: sip
    description: SIP webhook configuration management
  - name: websocket
    description: WebSocket API for real-time communication
paths:
  /speak:
    post:
      tags:
        - tts
      summary: Handler for the /speak endpoint
      operationId: speak_handler
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SpeakRequest'
        required: true
      responses:
        '200':
          description: Audio generated successfully
          headers:
            x-audio-format:
              schema:
                type: string
              description: Audio format (linear16, mp3, etc.)
            x-sample-rate:
              schema:
                type: integer
                format: int32
                minimum: 0
              description: Sample rate in Hz
          content:
            audio/pcm: {}
        '400':
          description: Invalid request (empty text)
        '500':
          description: TTS synthesis failed
      security:
        - auth: []
components:
  schemas:
    SpeakRequest:
      type: object
      description: Request body for the speak endpoint
      required:
        - text
        - tts_config
      properties:
        text:
          type: string
          description: The text to synthesize
          example: Hello, world!
        tts_config:
          $ref: '#/components/schemas/TTSWebSocketConfig'
          description: TTS configuration, including an optional provider auth override.
    TTSWebSocketConfig:
      type: object
      description: TTS configuration for WebSocket messages.
      required:
        - provider
        - model
      properties:
        audio_format:
          type:
            - string
            - 'null'
          description: Audio format preference
          example: linear16
        auth:
          oneOf:
            - type: 'null'
            - $ref: '#/components/schemas/ProviderAuthInput'
              description: |-
                Optional provider auth override for this session or request.

                Examples by provider:
                - Deepgram / ElevenLabs / Cartesia: `{ "api_key": "..." }`
                - Google: `{ "credentials": "/path/to/creds.json" }` or
                  `{ "credentials": { ...service account json... } }`
                - Azure: `{ "api_key": "...", "region": "eastus" }`
        connection_timeout:
          type:
            - integer
            - 'null'
          format: int64
          description: Connection timeout in seconds
          example: 30
          minimum: 0
        model:
          type: string
          description: Model to use for TTS
          example: aura-asteria-en
        pronunciations:
          type: array
          items:
            $ref: '#/components/schemas/Pronunciation'
          description: Pronunciation replacements to apply before TTS
        provider:
          type: string
          description: Provider name (e.g., "deepgram")
          example: deepgram
        request_timeout:
          type:
            - integer
            - 'null'
          format: int64
          description: Request timeout in seconds
          example: 60
          minimum: 0
        sample_rate:
          type:
            - integer
            - 'null'
          format: int32
          description: Sample rate preference
          example: 24000
          minimum: 0
        speaking_rate:
          type:
            - number
            - 'null'
          format: float
          description: Speaking rate (0.25 to 4.0, 1.0 is normal)
          example: 1
        voice_id:
          type:
            - string
            - 'null'
          description: Voice ID or name to use for synthesis
          example: aura-asteria-en
    ProviderAuthInput:
      allOf:
        - type: object
          description: Provider-specific auth fields.
      description: |-
        Raw provider auth input received from API callers.

        The outer provider field determines how these fields are interpreted.
    Pronunciation:
      type: object
      description: Pronunciation replacement configuration
      required:
        - word
        - pronunciation
      properties:
        pronunciation:
          type: string
          description: Pronunciation to use instead
          example: A P I
        word:
          type: string
          description: Word to replace
          example: API
  securitySchemes:
    auth:
      type: http
      scheme: bearer
      bearerFormat: Token
      description: >-
        Authentication token for protected endpoints. Can be provided as
        `Authorization: Bearer <token>` or `?api_key=<token>`. Required when
        AUTH_REQUIRED is enabled.

````