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

# Text to speech

> Synchronous TTS. Returns base64-encoded audio after generation completes.

`POST /v1/tts` is the simplest way to generate audio: send text, get a complete audio file back as base64. Use this when you have a single utterance and want to write the result to a file or play it back after generation completes.

If you need to start playback before generation finishes, use [Streaming TTS](/api-reference/http/streaming-tts) instead.

## Examples

<CodeGroup>
  ```python Python theme={null}
  from kova_tts import KovaTTSClient, AudioResponseFormat

  client = KovaTTSClient(api_key="kova_sk_...")
  result = client.tts(
      text="Welcome to Kova.",
      voice="cal",
      response_format=AudioResponseFormat(encoding="mp3"),
      timestamps=True,
  )
  client.write_audio_file(result.audio, "welcome.mp3")
  if result.timestamps:
      print(result.timestamps.words)
  ```

  ```ts Node.js theme={null}
  import { KovaTTSClient } from "@kova-ai/tts";

  const client = new KovaTTSClient({ apiKey: "kova_sk_..." });
  const result = await client.tts({
    text: "Welcome to Kova.",
    voice: "cal",
    response_format: { encoding: "mp3" },
    timestamps: true,
  });
  await client.writeAudioFile(result.audio, "welcome.mp3");
  console.log(result.timestamps?.words);
  ```

  ```bash cURL theme={null}
  curl https://api.kova.ai/v1/tts \
    -H "x-api-key: $KOVA_API_KEY" \
    -H "content-type: application/json" \
    -d '{
      "text": "Welcome to Kova.",
      "voice": "cal",
      "response_format": {"encoding": "mp3"},
      "timestamps": true
    }' \
    | jq -r .audio | base64 -d > welcome.mp3
  ```
</CodeGroup>

## response\_format

`response_format` accepts an object or, for backward compatibility, a bare encoding string (e.g. `"mp3"`).

| encoding        | sample\_rate                                            | bitrate                        | Notes                                                                                |
| --------------- | ------------------------------------------------------- | ------------------------------ | ------------------------------------------------------------------------------------ |
| `mp3` (default) | 16000–48000 Hz (default 32000)                          | `32–320 kbps` (default `128k`) | Compressed; best general-purpose default.                                            |
| `wav`           | 8000–48000 Hz (default 32000)                           | n/a                            | Uncompressed; one header per file.                                                   |
| `pcm`           | 8000–48000 Hz (default 32000)                           | n/a                            | Raw signed 16-bit little-endian. Best for streaming if you assemble your own header. |
| `linear16`      | 8000–48000 Hz (default 32000)                           | n/a                            | Equivalent to `pcm` but emits a WAV header per chunk during streaming.               |
| `opus`          | one of 8000, 12000, 16000, 24000, 48000 (default 48000) | `32–192 kbps` (default `64k`)  | Compressed, low-latency.                                                             |
| `mulaw`         | 8000 Hz only                                            | n/a                            | Telephony (G.711).                                                                   |
| `alaw`          | 8000 Hz only                                            | n/a                            | Telephony (G.711).                                                                   |

<Tip>Encoding aliases are accepted and normalized: `linear_pcm` / `linear-pcm` / `pcm_s16le` / `raw` / `mu-law` / `μ-law` / `ulaw` / `u-law` / `a-law`. Documented names are canonical.</Tip>

## See also

* [Streaming TTS](/api-reference/http/streaming-tts) — same request shape, lower time-to-first-audio.
* [Voices](/voices) — available speaker ids.
* [Errors](/errors) — what 4xx and 5xx bodies look like.


## OpenAPI

````yaml POST /v1/tts
openapi: 3.1.0
info:
  title: Kova TTS Inference API
  version: 0.1.0
servers:
  - url: https://api.kova.ai
security: []
paths:
  /v1/tts:
    post:
      summary: Text to speech
      operationId: sync_tts__post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TTSRequest'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SyncTTSResponse'
          description: Successful Response
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - xApiKey: []
components:
  schemas:
    TTSRequest:
      additionalProperties: false
      properties:
        normalize_text:
          default: false
          title: Normalize Text
          type: boolean
        response_format:
          $ref: '#/components/schemas/AudioResponseFormat'
        temperature:
          anyOf:
            - type: number
            - type: 'null'
          title: Temperature
        text:
          title: Text
          type: string
        timestamps:
          default: false
          title: Timestamps
          type: boolean
        voice:
          title: Voice
          type: string
      required:
        - text
        - voice
      title: TTSRequest
      type: object
    SyncTTSResponse:
      properties:
        audio:
          title: Audio
          type: string
        timestamps:
          anyOf:
            - $ref: '#/components/schemas/SyncTimestamps'
            - type: 'null'
      required:
        - audio
      title: SyncTTSResponse
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    AudioResponseFormat:
      additionalProperties: false
      properties:
        bitrate:
          anyOf:
            - type: string
            - type: integer
            - type: 'null'
          title: Bitrate
        encoding:
          default: mp3
          title: Encoding
          type: string
        sample_rate:
          anyOf:
            - type: integer
            - type: 'null'
          title: Sample Rate
      title: AudioResponseFormat
      type: object
    SyncTimestamps:
      properties:
        end_seconds:
          items:
            type: number
          title: End Seconds
          type: array
        start_seconds:
          items:
            type: number
          title: Start Seconds
          type: array
        words:
          items:
            type: string
          title: Words
          type: array
      required:
        - words
        - start_seconds
        - end_seconds
      title: SyncTimestamps
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
  securitySchemes:
    xApiKey:
      in: header
      name: x-api-key
      type: apiKey

````