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

# Create audio

> Starts turning text into speech and returns straight away. The audio is ready when `status` becomes `completed`.

The response comes back straight away, usually with `status: "pending"` and no `attachment.url` yet. The audio is generated in the background:

1. **Poll:** call [Get audio](https://docs.olimi.ai/api-reference/endpoint/speech/get-tts.md) with the returned `id` every few seconds.
2. **Stop polling** when `status` is `completed` or `failed`.
3. **Download:** once it's `completed`, download the file from `attachment.url`.

Short text is usually ready within a few seconds.

The voice and language are checked before anything is created. An invalid pair returns `400` straight away. See [Errors](https://docs.olimi.ai/api-reference/endpoint/speech/text-to-speech.md#errors).

> [!NOTE]
>
> If the voice's engine fails, you don't get an error here. The audio's `status` becomes `failed` instead. Retry, or try another voice.


## OpenAPI

````yaml post /api/v2/tts
openapi: 3.0.1
info:
  title: Customer Management API
  description: API for managing customer lists and customers within those lists
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api-eg.olimi.ai
security:
  - bearerAuth: []
paths:
  /api/v2/tts:
    post:
      tags:
        - Text to Speech
      summary: Create audio
      description: >-
        Starts turning text into speech and returns straight away. The audio is
        ready when `status` becomes `completed`.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TtsCreate'
      responses:
        '201':
          description: The new audio, usually with `status` `pending`.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TtsRecordResponse'
        '400':
          description: >-
            `tts_language_not_supported` (the language doesn't exist or isn't
            available for speech), `tts_voice_not_supported` or
            `voice_language_not_compatible`. See
            [Errors](/api-reference/endpoint/speech/text-to-speech#errors).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '401':
          description: The `X-API-KEY` header is missing or the key isn't valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: The request body didn't pass validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationError'
      security:
        - apiKeyAuth: []
components:
  schemas:
    TtsCreate:
      type: object
      required:
        - input
        - languageId
        - voiceId
      properties:
        input:
          type: string
          minLength: 1
          description: The text to speak.
          example: أهلاً بيك، إزيك النهارده؟
        languageId:
          type: string
          format: uuid
          description: >-
            From [List
            languages](/api-reference/endpoint/speech/list-tts-languages).
          example: 2cdab2de-310d-59a3-ad68-b85b4526e37b
        voiceId:
          type: string
          format: uuid
          description: From [List voices](/api-reference/endpoint/speech/list-tts-voices).
          example: 118d2470-de1d-5093-86b3-f2d8adec3183
        name:
          type: string
          description: >-
            A label for the audio. Becomes the file name. Defaults to
            `TTS_<timestamp>`.
          example: greeting
    TtsRecordResponse:
      type: object
      properties:
        message:
          type: string
          example: Text-to-speech record fetched successfully
        data:
          $ref: '#/components/schemas/TtsRecord'
    ApiError:
      type: object
      properties:
        statusCode:
          type: integer
          example: 404
        errorCode:
          type: string
          description: Machine-readable error code.
          example: agent_not_found
        message:
          type: string
          description: Human-readable text. May change; don't match on it.
          example: Agent not found
    ValidationError:
      type: object
      properties:
        statusCode:
          type: integer
          example: 422
        message:
          type: array
          items:
            type: string
          description: What went wrong. Human-readable.
          example:
            - name must be shorter than or equal to 100 characters
        error:
          type: string
          example: Unprocessable Entity
    TtsRecord:
      type: object
      properties:
        id:
          type: string
          format: uuid
          description: The audio's ID.
          example: 457ede41-97c7-44c6-bdd8-b9e4ca37f812
        name:
          type: string
          description: Your label, or `TTS_<timestamp>` if you didn't send one.
          example: greeting
        input:
          type: string
          description: The text that was spoken.
          example: أهلاً بيك، إزيك النهارده؟
        status:
          type: string
          enum:
            - pending
            - completed
            - failed
          description: >-
            See [Status
            values](/api-reference/endpoint/speech/text-to-speech#status-values).
          example: completed
        duration:
          type: integer
          description: >-
            Length of the audio in seconds, rounded down. `0` until the audio is
            ready.
          example: 2
        responseFormat:
          type: string
          description: 'Always `pcm`: the encoding inside the WAV file.'
          example: pcm
        languageId:
          type: string
          format: uuid
          example: 2cdab2de-310d-59a3-ad68-b85b4526e37b
        voiceId:
          type: string
          format: uuid
          example: 118d2470-de1d-5093-86b3-f2d8adec3183
        attachment:
          $ref: '#/components/schemas/TtsAttachment'
        language:
          type: object
          properties:
            code:
              type: string
              example: ar-EG
            name:
              type: string
              example: Arabic - Egyptian
        voice:
          type: object
          properties:
            id:
              type: string
              format: uuid
              example: 118d2470-de1d-5093-86b3-f2d8adec3183
            name:
              type: string
              example: Farida
            voiceKey:
              type: string
              example: Kore
        createdAt:
          type: string
          format: date-time
          example: '2026-09-29T09:05:44.045Z'
        updatedAt:
          type: string
          format: date-time
          example: '2026-09-29T09:05:47.310Z'
    TtsAttachment:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: d853213e-03da-49af-8d7b-81a818d1a296
        originalName:
          type: string
          description: 'The file name: your `name` plus `.wav`.'
          example: greeting.wav
        mimeType:
          type: string
          example: audio/wav
        fileSize:
          type: string
          description: Size in bytes, as a string. `0` until the audio is ready.
          example: '128684'
        url:
          type: string
          nullable: true
          description: >-
            A temporary download link. Only present once `status` is
            `completed`; expires after one hour.
          example: >-
            https://<storage-host>/tts/d853213e-03da-49af-8d7b-81a818d1a296?X-Amz-Expires=3600&X-Amz-Signature=…
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.