openapi: 3.0.3
info:
  title: SLNG Gateway API - Sarvam AI TTS
  version: 0.1.0
  description: Unified API for speech-to-text and text-to-speech services.
  contact:
    name: SLNG Support
    email: support@slng.ai
servers:
  - url: https://api.slng.ai
    description: Production
  - url: https://stageapi.slng.ai
    description: Staging
security:
  - BearerAuth: []
paths:
  /v1/tts/sarvam/bulbul:v3:
    post:
      operationId: sarvam/bulbul:v3
      summary: Bulbul v3
      description: Synthesize speech using Sarvam AI Bulbul with high-quality multilingual TTS for Indian languages and 30+ speaker voices.
      tags:
        - Sarvam AI Bulbul v3
      parameters:
        - $ref: "#/components/parameters/XWorldPartSarvam"
      requestBody:
        $ref: "#/components/requestBodies/SarvamBulbulTtsRequestBody"
      responses:
        "200":
          $ref: "#/components/responses/SarvamTtsSynthesisSuccess"
        "400":
          $ref: "#/components/responses/ProviderBadRequest"
        "401":
          $ref: "#/components/responses/ProviderUnauthorized"
        "500":
          $ref: "#/components/responses/ProviderInternalServerError"
        "503":
          $ref: "#/components/responses/ProviderServiceUnavailable"
  /v1/tts/sarvam/bulbul-stream:v3:
    post:
      operationId: sarvam/bulbul-stream:v3
      summary: Bulbul Stream v3
      description: |
        HTTP-streaming multilingual TTS for Indian languages with 30+ speaker voices. Returns raw audio bytes (chunked) in the codec selected via `output_audio_codec`. Unlike `sarvam/bulbul:v3`, no `X-Duration` header is sent and no JSON envelope is used.
      tags:
        - Sarvam AI Bulbul Stream v3
      parameters:
        - $ref: "#/components/parameters/XWorldPartSarvam"
      requestBody:
        $ref: "#/components/requestBodies/SarvamBulbulStreamTtsRequestBody"
      responses:
        "200":
          $ref: "#/components/responses/SarvamTtsStreamingSuccess"
        "400":
          $ref: "#/components/responses/ProviderBadRequest"
        "401":
          $ref: "#/components/responses/ProviderUnauthorized"
        "500":
          $ref: "#/components/responses/ProviderInternalServerError"
        "503":
          $ref: "#/components/responses/ProviderServiceUnavailable"
tags:
  - name: Sarvam AI Bulbul v3
    description: Sarvam AI Bulbul TTS with multilingual Indian language support.
  - name: Sarvam AI Bulbul Stream v3
    description: Sarvam AI Bulbul HTTP-streaming TTS with raw audio responses.
components:
  responses:
    ProviderServiceUnavailable:
      description: Service unavailable.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProviderErrorResponse"
    ProviderInternalServerError:
      description: Internal server error from the provider.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProviderErrorResponse"
          examples:
            processing-error:
              summary: Processing error
              value:
                error: Service error
                details: Internal processing error
    ProviderUnauthorized:
      description: Invalid or missing API key.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProviderErrorResponse"
    ProviderBadRequest:
      description: Bad request - invalid parameters provided.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProviderErrorResponse"
          examples:
            validation-error:
              summary: Validation error
              value:
                error: Validation error
                details: "Missing required field: text"
    SarvamTtsSynthesisSuccess:
      description: Synthesis successful.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SarvamTtsResponse"
          examples:
            basic:
              summary: Basic synthesis
              value:
                audios:
                  - UklGRgAA...
    SarvamTtsStreamingSuccess:
      description: Synthesis successful. Returns binary audio in the codec specified by `output_audio_codec` (chunked stream).
      content:
        application/octet-stream:
          schema:
            $ref: "#/components/schemas/AudioBinary"
  schemas:
    ProviderErrorResponse:
      type: object
      description: |
        Provider error response. Contains error information from the upstream provider.
        Common errors include invalid speakers, unsupported languages, or malformed requests.
      properties:
        error:
          type: string
          description: Error type or category (e.g., "TTS service error", "Validation error").
          example: TTS service error
        status:
          type: number
          description: Original HTTP status code from the provider (may differ from gateway response code).
          example: 400
        details:
          type: string
          description: |
            Detailed error message from the provider. For TTS errors, this typically includes
            the specific validation failure (e.g., invalid speaker ID for the selected model/language).
          example: "Rime TTS API error: 400 Bad Request - Invalid argument: Invalid speaker: aurelie"
      required:
        - error
    SarvamTtsResponse:
      type: object
      description: Sarvam AI TTS response format.
      properties:
        audios:
          type: array
          description: Array of base64-encoded audio strings.
          items:
            type: string
    AudioBinary:
      type: string
      format: binary
      description: Binary audio data.
    SarvamBulbulStreamV3Request:
      type: object
      description: Sarvam AI Bulbul streaming TTS request.
      required:
        - text
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 3500
          description: Text to synthesize. Supports code-mixed text (English and Indic languages).
        target_language_code:
          type: string
          description: Language code in BCP-47 format for text normalization.
          enum:
            - bn-IN
            - en-IN
            - gu-IN
            - hi-IN
            - kn-IN
            - ml-IN
            - mr-IN
            - od-IN
            - pa-IN
            - ta-IN
            - te-IN
          default: en-IN
        speaker:
          type: string
          description: Speaker voice for the output audio.
          enum:
            - shubh
            - aditya
            - ritu
            - priya
            - neha
            - rahul
            - pooja
            - rohan
            - simran
            - kavya
            - amit
            - dev
            - ishita
            - shreya
            - ratan
            - varun
            - manan
            - sumit
            - roopa
            - kabir
            - aayan
            - ashutosh
            - advait
            - amelia
            - sophia
            - anand
            - tanya
            - tarun
            - sunny
            - mani
            - gokul
            - vijay
            - shruti
            - suhani
            - mohit
            - kavitha
            - rehan
            - soham
            - rupali
          default: shubh
        model:
          type: string
          description: Sarvam TTS model identifier.
          enum:
            - bulbul:v3
          default: bulbul:v3
        output_audio_codec:
          type: string
          description: Output audio codec. Determines the response `Content-Type`.
          enum:
            - mp3
            - wav
            - aac
            - opus
            - flac
            - linear16
            - mulaw
            - alaw
          default: mp3
        output_audio_bitrate:
          type: string
          description: Output audio bitrate.
          enum:
            - 32k
            - 64k
            - 128k
            - 192k
            - 256k
          default: 128k
        pace:
          type: number
          description: Speech speed (0.5 to 2.0).
          minimum: 0.5
          maximum: 2
          default: 1
        speech_sample_rate:
          type: integer
          description: Output sample rate in Hz.
          default: 22050
        temperature:
          type: number
          description: Controls expressiveness (0.01 to 1.0).
          minimum: 0.01
          maximum: 1
          default: 0.6
        enable_preprocessing:
          type: boolean
          description: Normalize English words and numbers before synthesis.
          default: false
    SarvamBulbulV3Request:
      type: object
      description: Sarvam AI Bulbul TTS request.
      required:
        - text
        - target_language_code
      properties:
        text:
          type: string
          minLength: 1
          maxLength: 2500
          description: Text to synthesize. Supports code-mixed text (English and Indic languages).
        target_language_code:
          type: string
          description: Language code in BCP-47 format for text normalization.
          enum:
            - bn-IN
            - en-IN
            - gu-IN
            - hi-IN
            - kn-IN
            - ml-IN
            - mr-IN
            - od-IN
            - pa-IN
            - ta-IN
            - te-IN
          default: en-IN
        speaker:
          type: string
          description: Speaker voice for the output audio.
          enum:
            - shubh
            - aditya
            - ritu
            - priya
            - neha
            - rahul
            - pooja
            - rohan
            - simran
            - kavya
            - amit
            - dev
            - ishita
            - shreya
            - ratan
            - varun
            - manan
            - sumit
            - roopa
            - kabir
            - aayan
            - ashutosh
            - advait
            - amelia
            - sophia
            - anand
            - tanya
            - tarun
            - sunny
            - mani
            - gokul
            - vijay
            - shruti
            - suhani
            - mohit
            - kavitha
            - rehan
            - soham
            - rupali
          default: shubh
        model:
          type: string
          description: Sarvam TTS model identifier.
          enum:
            - bulbul:v3
          default: bulbul:v3
        pace:
          type: number
          description: Speech speed (0.5 to 2.0). Default is 1.0.
          minimum: 0.5
          maximum: 2
          default: 1
        temperature:
          type: number
          description: Controls expressiveness (0.01 to 2.0). Default is 0.6.
          minimum: 0.01
          maximum: 2
          default: 0.6
        speech_sample_rate:
          type: string
          description: Output sample rate in Hz.
          enum:
            - "8000"
            - "16000"
            - "22050"
            - "24000"
            - "32000"
            - "44100"
            - "48000"
          default: "24000"
        output_audio_codec:
          type: string
          description: Output audio codec.
          enum:
            - mp3
            - linear16
            - mulaw
            - alaw
            - opus
            - flac
            - aac
            - wav
  requestBodies:
    SarvamBulbulTtsRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SarvamBulbulV3Request"
          examples:
            english:
              summary: Basic synthesis
              value:
                text: Hello, how are you today?
                target_language_code: en-IN
                speaker: shubh
            hindi:
              summary: Hindi synthesis with options
              value:
                text: नमस्ते, आज आप कैसे हैं?
                target_language_code: hi-IN
                speaker: aditya
                pace: 1.2
                speech_sample_rate: "16000"
    SarvamBulbulStreamTtsRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/SarvamBulbulStreamV3Request"
          examples:
            english:
              summary: Basic streaming synthesis
              value:
                text: Hello, this is a streamed Sarvam synthesis request.
                target_language_code: en-IN
                speaker: shubh
                model: bulbul:v3
                output_audio_codec: mp3
            hindi:
              summary: Hindi streaming synthesis
              value:
                text: नमस्ते, आज आप कैसे हैं?
                target_language_code: hi-IN
                speaker: aditya
                output_audio_codec: mp3
                output_audio_bitrate: 128k
  parameters:
    XWorldPartSarvam:
      name: X-World-Part-Override
      in: header
      required: false
      description: Target world part override. Auto-selected if not provided.
      schema:
        type: string
        enum:
          - ap
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        API key issued by SLNG. Pass as `Authorization: Bearer <token>`.