asyncapi: 3.0.0
info:
  title: SLNG Gateway API - Sarvam AI TTS
  version: 0.1.0
  description: SLNG Gateway API
  contact:
    name: SLNG Support
    url: https://slng.ai
    email: support@slng.ai
  license:
    name: Proprietary
  tags:
    - name: STT
      description: Speech-to-Text services
    - name: Unmute STT Bridge
      description: SLNG native WebSocket STT protocol bridge.
    - name: Unmute TTS Bridge
      description: SLNG native WebSocket TTS protocol bridge.
servers:
  production:
    host: api.slng.ai
    protocol: wss
    description: Production
    security:
      - $ref: "#/components/securitySchemes/bearer"
  staging:
    host: stageapi.slng.ai
    protocol: wss
    description: Staging
    security:
      - $ref: "#/components/securitySchemes/bearer"
channels:
  /v1/tts/sarvam/bulbul:v3:
    address: /v1/tts/sarvam/bulbul:v3
    title: Bulbul v3
    summary: Bulbul v3
    description: Stream multilingual Indian-language speech from Sarvam AI Bulbul v3 over WebSocket with 30+ speaker voices and SLNG's unified low-latency TTS protocol.
    tags:
      - name: Sarvam AI Bulbul v3
    servers:
      - $ref: "#/servers/production"
      - $ref: "#/servers/staging"
    messages:
      SarvamBulbulTtsInitRequest:
        $ref: "#/components/messages/SarvamBulbulTtsInitRequest"
      TtsTextMessage:
        $ref: "#/components/messages/TtsTextMessage"
      TtsFlushMessage:
        $ref: "#/components/messages/TtsFlushMessage"
      TtsClearMessage:
        $ref: "#/components/messages/TtsClearMessage"
      TtsCloseMessage:
        $ref: "#/components/messages/TtsCloseMessage"
      KeepaliveMessage:
        $ref: "#/components/messages/KeepaliveMessage"
      TtsReadyResponse:
        $ref: "#/components/messages/TtsReadyResponse"
      SarvamBulbulTtsAudioResponse:
        $ref: "#/components/messages/SarvamBulbulTtsAudioResponse"
      TtsSegmentStart:
        $ref: "#/components/messages/TtsSegmentStart"
      TtsSegmentEnd:
        $ref: "#/components/messages/TtsSegmentEnd"
      TtsFlushed:
        $ref: "#/components/messages/TtsFlushed"
      TtsCleared:
        $ref: "#/components/messages/TtsCleared"
      TtsAudioEnd:
        $ref: "#/components/messages/TtsAudioEnd"
      TtsErrorResponse:
        $ref: "#/components/messages/TtsErrorResponse"
    bindings:
      ws:
        method: GET
        headers:
          $ref: "#/components/schemas/WebsocketHeadersSarvam"
operations:
  ttsSarvamBulbulV3ReceiveInit:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3"
    summary: Initialize session on Bulbul v3
    messages:
      - $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3/messages/SarvamBulbulTtsInitRequest"
    description: Initialize session on Bulbul v3
    tags: []
  ttsSarvamBulbulV3ReceiveText:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3"
    summary: Send text to Bulbul v3
    messages:
      - $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3/messages/TtsTextMessage"
    description: Send text to Bulbul v3
    tags: []
  ttsSarvamBulbulV3ReceiveFlush:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3"
    summary: Flush buffered output on Bulbul v3
    messages:
      - $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3/messages/TtsFlushMessage"
    description: Flush buffered output on Bulbul v3
    tags: []
  ttsSarvamBulbulV3ReceiveClear:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3"
    summary: Clear queued output on Bulbul v3
    messages:
      - $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3/messages/TtsClearMessage"
    description: Clear queued output on Bulbul v3
    tags: []
  ttsSarvamBulbulV3ReceiveClose:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3"
    summary: Close session on Bulbul v3
    messages:
      - $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3/messages/TtsCloseMessage"
    description: Close session on Bulbul v3
    tags: []
  ttsSarvamBulbulV3ReceiveKeepalive:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3"
    summary: Send keepalive on Bulbul v3
    messages:
      - $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3/messages/KeepaliveMessage"
    description: Send keepalive on Bulbul v3
    tags: []
  ttsSarvamBulbulV3SendReady:
    action: send
    channel:
      $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3"
    summary: Receive ready signal from Bulbul v3
    messages:
      - $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3/messages/TtsReadyResponse"
    description: Receive ready signal from Bulbul v3
    tags: []
  ttsSarvamBulbulV3SendAudio:
    action: send
    channel:
      $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3"
    summary: Receive audio response from Bulbul v3
    messages:
      - $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3/messages/SarvamBulbulTtsAudioResponse"
    description: Receive audio response from Bulbul v3
    tags: []
  ttsSarvamBulbulV3SendSegmentStart:
    action: send
    channel:
      $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3"
    summary: Receive segment start from Bulbul v3
    messages:
      - $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3/messages/TtsSegmentStart"
    description: Receive segment start from Bulbul v3
    tags: []
  ttsSarvamBulbulV3SendSegmentEnd:
    action: send
    channel:
      $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3"
    summary: Receive segment end from Bulbul v3
    messages:
      - $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3/messages/TtsSegmentEnd"
    description: Receive segment end from Bulbul v3
    tags: []
  ttsSarvamBulbulV3SendFlushed:
    action: send
    channel:
      $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3"
    summary: Receive flushed confirmation from Bulbul v3
    messages:
      - $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3/messages/TtsFlushed"
    description: Receive flushed confirmation from Bulbul v3
    tags: []
  ttsSarvamBulbulV3SendCleared:
    action: send
    channel:
      $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3"
    summary: Receive cleared confirmation from Bulbul v3
    messages:
      - $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3/messages/TtsCleared"
    description: Receive cleared confirmation from Bulbul v3
    tags: []
  ttsSarvamBulbulV3SendAudioEnd:
    action: send
    channel:
      $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3"
    summary: Receive audio end from Bulbul v3
    messages:
      - $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3/messages/TtsAudioEnd"
    description: Receive audio end from Bulbul v3
    tags: []
  ttsSarvamBulbulV3SendError:
    action: send
    channel:
      $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3"
    summary: Receive error from Bulbul v3
    messages:
      - $ref: "#/channels/~1v1~1tts~1sarvam~1bulbul:v3/messages/TtsErrorResponse"
    description: Receive error from Bulbul v3
    tags: []
components:
  schemas:
    WebsocketHeadersSarvam:
      type: object
      properties:
        X-World-Part-Override:
          type: string
          description: "Target world part override. Auto-selected if not provided. Available world parts: `ap`."
          enum:
            - ap
  messages:
    TtsErrorResponse:
      name: TtsErrorResponse
      title: Error Response
      summary: Indicates an error occurred during synthesis.
      contentType: application/json
      payload:
        type: object
        description: Indicates an error occurred during synthesis.
        required:
          - type
          - code
          - message
        properties:
          type:
            type: string
            const: error
          code:
            type: string
            description: Error code.
            enum:
              - auth_error
              - config_error
              - rate_limit
              - provider_error
          message:
            type: string
            description: Human-readable error description
      examples:
        - name: ttsError
          summary: TTS error response
          payload:
            type: error
            code: provider_error
            message: Provider returned an unexpected error
    TtsAudioEnd:
      name: TtsAudioEnd
      title: Audio End
      summary: Signals the end of audio generation.
      contentType: application/json
      payload:
        type: object
        description: Signals the end of audio generation.
        required:
          - type
        properties:
          type:
            type: string
            const: audio_end
          duration:
            type: number
            description: Total audio duration
      examples:
        - name: audioEnd
          summary: Audio generation complete
          payload:
            type: audio_end
            duration: 3.5
    TtsCleared:
      name: TtsCleared
      title: Cleared
      summary: Acknowledges that queued output was cleared.
      contentType: application/json
      payload:
        type: object
        description: Acknowledges that queued output was cleared.
        required:
          - type
        properties:
          type:
            type: string
            const: cleared
      examples:
        - name: cleared
          summary: Clear acknowledged
          payload:
            type: cleared
    TtsFlushed:
      name: TtsFlushed
      title: Flushed
      summary: Acknowledges that buffered output was flushed.
      contentType: application/json
      payload:
        type: object
        description: Acknowledges that buffered output was flushed.
        required:
          - type
        properties:
          type:
            type: string
            const: flushed
      examples:
        - name: flushed
          summary: Flush acknowledged
          payload:
            type: flushed
    TtsSegmentEnd:
      name: TtsSegmentEnd
      title: Segment End
      summary: Signals the end of a synthesized segment.
      contentType: application/json
      payload:
        type: object
        description: Signals the end of a synthesized segment.
        required:
          - type
          - segment_id
        properties:
          type:
            type: string
            const: segment_end
          segment_id:
            type: string
            description: Unique segment identifier
      examples:
        - name: segmentEnd
          summary: Segment end signal
          payload:
            type: segment_end
            segment_id: seg_001
    TtsSegmentStart:
      name: TtsSegmentStart
      title: Segment Start
      summary: Signals the start of a synthesized segment.
      contentType: application/json
      payload:
        type: object
        description: Signals the start of a synthesized segment.
        required:
          - type
          - segment_id
        properties:
          type:
            type: string
            const: segment_start
          segment_id:
            type: string
            description: Unique segment identifier
      examples:
        - name: segmentStart
          summary: Segment start signal
          payload:
            type: segment_start
            segment_id: seg_001
    SarvamBulbulTtsAudioResponse:
      name: SarvamBulbulTtsAudioResponse
      title: Audio Response (Sarvam Bulbul)
      summary: Audio response from Sarvam Bulbul TTS with metadata.
      contentType: application/json
      payload:
        type: object
        description: Audio response from Sarvam Bulbul TTS containing base64-encoded audio with request metadata.
        required:
          - type
          - data
        properties:
          type:
            type: string
            const: audio
          data:
            type: object
            required:
              - request_id
              - content_type
              - audio
            properties:
              request_id:
                type: string
                description: Unique identifier for the request
              content_type:
                type: string
                description: MIME type of the audio data (e.g., audio/pcm)
              audio:
                type: string
                format: byte
                description: Base64-encoded audio data
      examples:
        - name: sarvamAudio
          summary: Receive audio from Sarvam Bulbul
          payload:
            type: audio
            data:
              request_id: 20260320_9a16651d-38fa-430a-b688-7d0bea33972f
              content_type: audio/pcm
              audio: KAVWBYAFcgVtBUE...
    TtsReadyResponse:
      name: TtsReadyResponse
      title: Ready Response
      summary: Indicates the session is ready to receive messages.
      contentType: application/json
      payload:
        type: object
        description: Indicates the session is ready to receive messages.
        required:
          - type
          - session_id
        properties:
          type:
            type: string
            const: ready
          session_id:
            type: string
            description: Unique session identifier
      examples:
        - name: ready
          summary: TTS session ready
          payload:
            type: ready
            session_id: sess_tts_abc123
    KeepaliveMessage:
      name: KeepaliveMessage
      title: Keepalive Message
      summary: Keep the WebSocket connection alive during silence.
      contentType: application/json
      payload:
        type: object
        description: Prevents the connection from being closed due to inactivity. Send periodically during silence to maintain the session.
        required:
          - type
        properties:
          type:
            type: string
            const: keepalive
      examples:
        - name: keepalive
          summary: Send keepalive
          payload:
            type: keepalive
    TtsCloseMessage:
      name: TtsCloseMessage
      title: Close Message
      summary: Close the session and stop any further audio.
      contentType: application/json
      payload:
        type: object
        description: Close the session and stop any further audio.
        required:
          - type
        properties:
          type:
            type: string
            const: close
      examples:
        - name: close
          summary: Close the session
          payload:
            type: close
    TtsClearMessage:
      name: TtsClearMessage
      title: Clear Message
      summary: Clear any queued text/audio from the current session.
      contentType: application/json
      payload:
        type: object
        description: Clear any queued text/audio from the current session.
        required:
          - type
        properties:
          type:
            type: string
            const: clear
      examples:
        - name: clear
          summary: Clear queued text/audio
          payload:
            type: clear
    TtsFlushMessage:
      name: TtsFlushMessage
      title: Flush Message
      summary: Force any buffered text/audio to be finalized and delivered.
      contentType: application/json
      payload:
        type: object
        description: Force any buffered text/audio to be finalized and delivered.
        required:
          - type
        properties:
          type:
            type: string
            const: flush
      examples:
        - name: flush
          summary: Flush buffered audio
          payload:
            type: flush
    TtsTextMessage:
      name: TtsTextMessage
      title: Text Message
      summary: Send text to synthesize into audio output.
      contentType: application/json
      payload:
        type: object
        description: Send text to synthesize into audio output.
        required:
          - type
          - text
        properties:
          type:
            type: string
            const: text
          text:
            type: string
            description: Text to synthesize
          flush:
            type: boolean
            description: Whether to flush remaining audio immediately after this text
      examples:
        - name: textMessage
          summary: Send text to synthesize
          payload:
            type: text
            text: Hello, this is a test of text-to-speech synthesis.
    SarvamBulbulTtsInitRequest:
      name: SarvamBulbulTtsInitRequest
      title: Init Request (Sarvam Bulbul)
      summary: Initialize a Sarvam Bulbul TTS session with provider-specific configuration.
      contentType: application/json
      payload:
        type: object
        description: Initialize a Sarvam Bulbul TTS session with voice, language, and audio configuration options specific to Sarvam AI.
        required:
          - type
          - model
        properties:
          type:
            type: string
            const: init
            default: init
          model:
            type: string
            description: Sarvam TTS model identifier.
            enum:
              - bulbul:v3
            default: bulbul:v3
          voice:
            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
          config:
            type: object
            description: Sarvam Bulbul synthesis configuration options
            properties:
              language:
                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
              encoding:
                type: string
                description: Output audio codec.
                enum:
                  - mp3
                  - linear16
                  - mulaw
                  - alaw
                  - opus
                  - flac
                  - aac
                  - wav
              speech_sample_rate:
                type: string
                description: Output sample rate in Hz.
                enum:
                  - "8000"
                  - "16000"
                  - "22050"
                  - "24000"
                  - "32000"
                  - "44100"
                  - "48000"
                default: "24000"
              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
              output_audio_bitrate:
                type: string
                description: Output audio bitrate (WebSocket streaming only).
              min_buffer_size:
                type: integer
                description: Minimum buffer size before sending audio chunks (WebSocket streaming only).
              max_chunk_length:
                type: integer
                description: Maximum text chunk length for synthesis (WebSocket streaming only).
      examples:
        - name: sarvamBulbulInit
          summary: Initialize Sarvam Bulbul TTS session
          payload:
            type: init
            model: bulbul:v3
            voice: shubh
            config:
              language: en-IN
              speech_sample_rate: "24000"
              encoding: linear16
              pace: 1
              temperature: 0.6
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: |
        API key issued by SLNG. Pass as `Authorization: Bearer <token>` in the WebSocket upgrade request headers.