Sarvam textToSpeech API

openapi: 3.1.0
info:
  title: Endpoints chat textToSpeech API
  version: 1.0.0
servers:
- url: https://api.sarvam.ai
  description: Production
tags:
- name: textToSpeech
paths:
  /text-to-speech:
    post:
      operationId: convert
      summary: Text to Speech
      description: 'Convert text into spoken audio. The output is a base64-encoded audio string that must be decoded before use.


        **Available Models:**

        - **bulbul:v3**: Latest model with improved quality, 30+ voices, and temperature control

        - **bulbul:v2**: Legacy model with pitch and loudness controls


        **Important Notes for bulbul:v3:**

        - Pitch and loudness parameters are NOT supported

        - Pace range: 0.5 to 2.0

        - Preprocessing is automatically enabled

        - Default sample rate is 24000 Hz

        - Supports sample rates: 8000, 16000, 22050, 24000 Hz (REST API also supports 32000, 44100, 48000 Hz)'
      tags:
      - textToSpeech
      parameters:
      - name: api-subscription-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sarvam_Model_API_TextToSpeechResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sarvam_Model_API_ErrorMessage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sarvam_Model_API_ErrorMessage'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sarvam_Model_API_ErrorMessage'
        '429':
          description: Quota Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sarvam_Model_API_ErrorMessage'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sarvam_Model_API_ErrorMessage'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Sarvam_Model_API_TextToSpeechRequest'
  /text-to-speech/stream:
    post:
      operationId: convert-stream
      summary: Text-to-Speech Stream Audio
      description: 'Converts the input text into a streamed spoken audio response.


        This endpoint supports streaming audio using the specified output codec (e.g., `audio/mpeg` for MP3). The response is returned as a binary audio stream, which can be played or saved directly by the client.


        Supports the `dict_id` parameter to apply a [pronunciation dictionary](https://docs.sarvam.ai/api-reference-docs/pronunciation-dictionary/create) during synthesis.'
      tags:
      - textToSpeech
      parameters:
      - name: api-subscription-key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success. Returns a streamed audio response in the requested format (e.g., `audio/mpeg` for MP3, `audio/wav` for WAV).
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sarvam_Model_API_ErrorMessage'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sarvam_Model_API_ErrorMessage'
        '422':
          description: Unprocessable Entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sarvam_Model_API_ErrorMessage'
        '429':
          description: Quota Exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sarvam_Model_API_ErrorMessage'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Sarvam_Model_API_ErrorMessage'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Sarvam_Model_API_TextToSpeechStreamRequest'
components:
  schemas:
    Sarvam_Model_API_TextToSpeechResponse:
      type: object
      properties:
        request_id:
          type:
          - string
          - 'null'
        audios:
          type: array
          items:
            type: string
          description: ' The output audio files in WAV format, encoded as base64 strings. Each string corresponds to one of the input texts.'
      required:
      - request_id
      - audios
      title: Sarvam_Model_API_TextToSpeechResponse
    Sarvam_Model_API_TextToSpeechStreamRequest:
      type: object
      properties:
        text:
          type: string
          description: 'The text to be converted into streamed speech.


            **Features:**

            - Max 3500 characters

            - Supports code-mixed text (English and Indic languages)


            **Important Note:**

            - For numbers larger than 4 digits, use commas (e.g., ''10,000'' instead of ''10000'')

            - This ensures proper pronunciation as a whole number'
        target_language_code:
          $ref: '#/components/schemas/Sarvam_Model_API_TextToSpeechLanguage'
          description: The language code in BCP-47 format.
        speaker:
          oneOf:
          - $ref: '#/components/schemas/Sarvam_Model_API_TextToSpeechSpeaker'
          - type: 'null'
          description: 'The speaker voice to be used for the output audio.


            **Default:** shubh (for bulbul:v3), anushka (for bulbul:v2)


            **Note:** Speaker selection must match the chosen model version.


            **Important:** Speaker names are case-sensitive and must be lowercase (e.g., `ritu` not `Ritu`).'
        pitch:
          type:
          - number
          - 'null'
          format: double
          description: 'Controls the pitch of the audio. Range: -0.75 to 0.75. Default is 0.0.


            **Note:** Only supported for bulbul:v2.'
        pace:
          type:
          - number
          - 'null'
          format: double
          default: 1
          description: 'Controls the speed of the audio. Default is 1.0.


            **Model-specific ranges:**

            - **bulbul:v3:** 0.5 to 2.0

            - **bulbul:v2:** 0.3 to 3.0'
        loudness:
          type:
          - number
          - 'null'
          format: double
          description: 'Controls the loudness of the audio. Range: 0.3 to 3.0. Default is 1.0.


            **Note:** Only supported for bulbul:v2.'
        speech_sample_rate:
          oneOf:
          - $ref: '#/components/schemas/Sarvam_Model_API_SpeechSampleRate'
          - type: 'null'
          default: 22050
          description: 'Specifies the sample rate of the output audio. Default is 22050 Hz.


            **Note:** OPUS codec only supports 8000, 12000, 16000, 24000, 48000 Hz.'
        enable_preprocessing:
          type: boolean
          default: false
          description: Controls whether normalization of English words and numeric entities is performed. Default is false.
        model:
          $ref: '#/components/schemas/Sarvam_Model_API_TextToSpeechModel'
          description: Specifies the model to use for text-to-speech conversion. Default is bulbul:v2.
        temperature:
          type:
          - number
          - 'null'
          format: double
          default: 0.6
          description: 'Controls the randomness of the output. Range: 0.01 to 1.0. Default is 0.6.


            **Note:** Only supported for bulbul:v3.'
        enable_cached_responses:
          type: boolean
          default: false
          description: Enable caching for the request. Default is false. Currently in beta.
        dict_id:
          type:
          - string
          - 'null'
          description: 'The ID of a pronunciation dictionary to apply during synthesis. When provided, matching words in the input text will be replaced with their custom pronunciations before generating speech.


            Create and manage dictionaries via the [Pronunciation Dictionary API](https://docs.sarvam.ai/api-reference-docs/pronunciation-dictionary/create). Only supported by **bulbul:v3**.'
        output_audio_codec:
          $ref: '#/components/schemas/Sarvam_Model_API_SpeechStreamCodec'
          description: Specifies the codec for the streamed output audio (e.g., 'mp3').
        output_audio_bitrate:
          $ref: '#/components/schemas/Sarvam_Model_API_SpeechStreamBitrate'
          description: Bitrate for the streamed output audio. Default is '128k'.
      required:
      - text
      title: Sarvam_Model_API_TextToSpeechStreamRequest
    TextToSpeechOutputAudioCodec:
      type: string
      enum:
      - mp3
      - linear16
      - mulaw
      - alaw
      - opus
      - flac
      - aac
      - wav
      description: Audio codec options for the non-streaming /text-to-speech endpoint
      title: TextToSpeechOutputAudioCodec
    Sarvam_Model_API_SpeechStreamBitrate:
      type: string
      enum:
      - 32k
      - 64k
      - 96k
      - 128k
      - 192k
      title: Sarvam_Model_API_SpeechStreamBitrate
    Sarvam_Model_API_TextToSpeechLanguage:
      type: string
      enum:
      - bn-IN
      - en-IN
      - gu-IN
      - hi-IN
      - kn-IN
      - ml-IN
      - mr-IN
      - od-IN
      - pa-IN
      - ta-IN
      - te-IN
      title: Sarvam_Model_API_TextToSpeechLanguage
    Sarvam_Model_API_ErrorMessage:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/Sarvam_Model_API_ErrorDetails'
          description: Error details
      required:
      - error
      title: Sarvam_Model_API_ErrorMessage
    Sarvam_Model_API_TextToSpeechRequest:
      type: object
      properties:
        text:
          $ref: '#/components/schemas/SarvamModelApiTextToSpeechRequestText'
          description: 'The text(s) to be converted into speech.


            **Features:**

            - Supports code-mixed text (English and Indic languages)


            **Model-specific limits:**

            - **bulbul:v3:** Max 2500 characters

            - **bulbul:v2:** Max 1500 characters


            **Important Note:**

            - For numbers larger than 4 digits, use commas (e.g., ''10,000'' instead of ''10000'')

            - This ensures proper pronunciation as a whole number'
        target_language_code:
          $ref: '#/components/schemas/Sarvam_Model_API_TextToSpeechLanguage'
          description: The language code in BCP-47 format.
        speaker:
          oneOf:
          - $ref: '#/components/schemas/Sarvam_Model_API_TextToSpeechSpeaker'
          - type: 'null'
          default: shubh
          description: "The speaker voice to be used for the output audio.\n\n**Default:** shubh (for bulbul:v3), anushka (for bulbul:v2)\n\n**Model Compatibility (Speakers compatible with respective model):**\n- **bulbul:v3:**\n  - shubh (default), aditya, ritu, priya, neha, rahul, pooja, rohan, simran, kavya, amit, dev, ishita, shreya, ratan, varun, manan, sumit, roopa, kabir, aayan, ashutosh, advait, anand, tanya, tarun, sunny, mani, gokul, vijay, shruti, suhani, mohit, kavitha, rehan, soham, rupali\n- **bulbul:v2:**\n  - Female: anushka, manisha, vidya, arya\n  - Male: abhilash, karun, hitesh\n\n**Note:** Speaker selection must match the chosen model version.\n\n**Important:** Speaker names are case-sensitive and must be lowercase (e.g., `ritu` not `Ritu`)."
        pitch:
          type:
          - number
          - 'null'
          format: double
          description: 'Controls the pitch of the audio. Lower values result in a deeper voice, while higher values make it sharper. The suitable range is between -0.75 and 0.75. Default is 0.0.


            **Note:** This parameter is only supported for bulbul:v2. It is NOT supported for bulbul:v3.'
        pace:
          type:
          - number
          - 'null'
          format: double
          default: 1
          description: 'Controls the speed of the audio. Lower values result in slower speech, while higher values make it faster. Default is 1.0.


            **Model-specific ranges:**

            - **bulbul:v3:** 0.5 to 2.0

            - **bulbul:v2:** 0.3 to 3.0'
        loudness:
          type:
          - number
          - 'null'
          format: double
          description: 'Controls the loudness of the audio. Lower values result in quieter audio, while higher values make it louder. The suitable range is between 0.3 and 3.0. Default is 1.0.


            **Note:** This parameter is only supported for bulbul:v2. It is NOT supported for bulbul:v3.'
        speech_sample_rate:
          oneOf:
          - $ref: '#/components/schemas/Sarvam_Model_API_SpeechSampleRate'
          - type: 'null'
          default: 22050
          description: 'Specifies the sample rate of the output audio. Supported values are 8000, 16000, 22050, 24000, 32000, 44100, 48000 Hz.


            **Note:** Higher sample rates (32000, 44100, 48000 Hz) are only available with bulbul:v3 via the REST API, not in streaming mode.


            **Default:** 24000 Hz'
        enable_preprocessing:
          type: boolean
          default: false
          description: 'Controls whether normalization of English words and numeric entities (e.g., numbers, dates) is performed. Set to true for better handling of mixed-language text.


            **Model-specific behavior:**

            - **bulbul:v3:** Not Supported

            - **bulbul:v2:** Default is false'
        model:
          $ref: '#/components/schemas/Sarvam_Model_API_TextToSpeechModel'
          description: 'Specifies the model to use for text-to-speech conversion.


            **Available models:**

            - **bulbul:v3:** Latest model with improved quality, 30+ voices, pace, and temperature control

            - **bulbul:v2:** Legacy model with pitch, loudness, and pace controls'
        output_audio_codec:
          oneOf:
          - $ref: '#/components/schemas/TextToSpeechOutputAudioCodec'
          - type: 'null'
          default: wav
          description: Specifies the audio codec for the output audio file. Different codecs offer various compression and quality characteristics.
        temperature:
          type:
          - number
          - 'null'
          format: double
          default: 0.6
          description: 'Temperature controls how much randomness and expressiveness the TTS model uses while generating speech.


            Lower values produce more stable and consistent output, while higher values sound more expressive but may introduce artifacts or errors. The suitable range is between 0.01 and 2.0. Default is 0.6.


            **Note:** This parameter is only supported for bulbul:v3. It has no effect on bulbul:v2.'
        dict_id:
          type:
          - string
          - 'null'
          description: 'The ID of a pronunciation dictionary to apply during synthesis. When provided, matching words in the input text will be replaced with their custom pronunciations before generating speech.


            Create and manage dictionaries via the [Pronunciation Dictionary API](https://docs.sarvam.ai/api-reference-docs/pronunciation-dictionary/create). Only supported by **bulbul:v3**.'
        enable_cached_responses:
          type: boolean
          default: false
          description: 'Enable caching for the request. When enabled, identical requests will return cached audio instead of regenerating. Default is false.


            **Note:** Currently in beta and only available for bulbul:v1 and bulbul:v2 models.'
      required:
      - text
      - target_language_code
      title: Sarvam_Model_API_TextToSpeechRequest
    Sarvam_Model_API_TextToSpeechSpeaker:
      type: string
      enum:
      - anushka
      - abhilash
      - manisha
      - vidya
      - arya
      - karun
      - hitesh
      - aditya
      - ritu
      - priya
      - neha
      - rahul
      - pooja
      - rohan
      - simran
      - kavya
      - amit
      - dev
      - ishita
      - shreya
      - ratan
      - varun
      - manan
      - sumit
      - roopa
      - kabir
      - aayan
      - shubh
      - ashutosh
      - advait
      - anand
      - tanya
      - tarun
      - sunny
      - mani
      - gokul
      - vijay
      - shruti
      - suhani
      - mohit
      - kavitha
      - rehan
      - soham
      - rupali
      title: Sarvam_Model_API_TextToSpeechSpeaker
    Sarvam_Model_API_TextToSpeechModel:
      type: string
      enum:
      - bulbul:v2
      - bulbul:v3
      title: Sarvam_Model_API_TextToSpeechModel
    Sarvam_Model_API_ErrorCode:
      type: string
      enum:
      - invalid_request_error
      - internal_server_error
      - unprocessable_entity_error
      - insufficient_quota_error
      - invalid_api_key_error
      - authentication_error
      - not_found_error
      - rate_limit_exceeded_error
      title: Sarvam_Model_API_ErrorCode
    SarvamModelApiTextToSpeechRequestText:
      oneOf:
      - type: string
      description: 'The text(s) to be converted into speech.


        **Features:**

        - Supports code-mixed text (English and Indic languages)


        **Model-specific limits:**

        - **bulbul:v3:** Max 2500 characters

        - **bulbul:v2:** Max 1500 characters


        **Important Note:**

        - For numbers larger than 4 digits, use commas (e.g., ''10,000'' instead of ''10000'')

        - This ensures proper pronunciation as a whole number'
      title: SarvamModelApiTextToSpeechRequestText
    Sarvam_Model_API_SpeechSampleRate:
      type: string
      enum:
      - '8000'
      - '16000'
      - '22050'
      - '24000'
      - '32000'
      - '44100'
      - '48000'
      title: Sarvam_Model_API_SpeechSampleRate
    Sarvam_Model_API_ErrorDetails:
      type: object
      properties:
        request_id:
          type:
          - string
          - 'null'
        message:
          type: string
          description: Message describing the error
        code:
          $ref: '#/components/schemas/Sarvam_Model_API_ErrorCode'
          description: Error code for the specific error that has occurred. Refer to the error code documentation for more details.
      required:
      - request_id
      - message
      - code
      title: Sarvam_Model_API_ErrorDetails
    Sarvam_Model_API_SpeechStreamCodec:
      type: string
      enum:
      - mp3
      - linear16
      - mulaw
      - alaw
      - opus
      - flac
      - aac
      - wav
      title: Sarvam_Model_API_SpeechStreamCodec
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api-subscription-key
    HTTPBearer:
      type: http
      scheme: bearer