asyncapi: 3.0.0
info:
  title: SLNG Gateway API - Deepgram 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/deepgram/aura:2:
    address: /v1/tts/deepgram/aura:2
    title: Aura 2
    summary: Aura 2
    description: Stream low-latency conversational text-to-speech from Deepgram Aura 2 over WebSocket as raw binary frames, optimized for ultra-low-latency voice agents.
    tags:
      - name: Deepgram Aura 2
    servers:
      - $ref: "#/servers/production"
      - $ref: "#/servers/staging"
    messages:
      TtsInitRequest:
        $ref: "#/components/messages/TtsInitRequest"
      TtsTextMessage:
        $ref: "#/components/messages/TtsTextMessage"
      TtsFlushMessage:
        $ref: "#/components/messages/TtsFlushMessage"
      TtsClearMessage:
        $ref: "#/components/messages/TtsClearMessage"
      TtsCloseMessage:
        $ref: "#/components/messages/TtsCloseMessage"
      DeepgramAuraTtsBinaryAudio:
        $ref: "#/components/messages/DeepgramAuraTtsBinaryAudio"
      TtsFlushed:
        $ref: "#/components/messages/TtsFlushed"
      TtsCleared:
        $ref: "#/components/messages/TtsCleared"
      TtsErrorResponse:
        $ref: "#/components/messages/TtsErrorResponse"
    bindings:
      ws:
        method: GET
        headers:
          $ref: "#/components/schemas/WebsocketHeadersDeepgramAura"
operations:
  ttsDeepgramAura2ReceiveInit:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2"
    summary: Initialize session on Aura 2
    messages:
      - $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2/messages/TtsInitRequest"
    description: Initialize session on Aura 2
    tags: []
  ttsDeepgramAura2ReceiveText:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2"
    summary: Send text to Aura 2
    messages:
      - $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2/messages/TtsTextMessage"
    description: Send text to Aura 2
    tags: []
  ttsDeepgramAura2ReceiveFlush:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2"
    summary: Flush buffered output on Aura 2
    messages:
      - $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2/messages/TtsFlushMessage"
    description: Flush buffered output on Aura 2
    tags: []
  ttsDeepgramAura2ReceiveClear:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2"
    summary: Clear queued output on Aura 2
    messages:
      - $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2/messages/TtsClearMessage"
    description: Clear queued output on Aura 2
    tags: []
  ttsDeepgramAura2ReceiveClose:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2"
    summary: Close session on Aura 2
    messages:
      - $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2/messages/TtsCloseMessage"
    description: Close session on Aura 2
    tags: []
  ttsDeepgramAura2SendBinaryAudio:
    action: send
    channel:
      $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2"
    summary: Receive binary audio from Aura 2
    messages:
      - $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2/messages/DeepgramAuraTtsBinaryAudio"
    description: Receive binary audio from Aura 2
    tags: []
  ttsDeepgramAura2SendFlushed:
    action: send
    channel:
      $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2"
    summary: Receive flushed confirmation from Aura 2
    messages:
      - $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2/messages/TtsFlushed"
    description: Receive flushed confirmation from Aura 2
    tags: []
  ttsDeepgramAura2SendCleared:
    action: send
    channel:
      $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2"
    summary: Receive cleared confirmation from Aura 2
    messages:
      - $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2/messages/TtsCleared"
    description: Receive cleared confirmation from Aura 2
    tags: []
  ttsDeepgramAura2SendError:
    action: send
    channel:
      $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2"
    summary: Receive error from Aura 2
    messages:
      - $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2/messages/TtsErrorResponse"
    description: Receive error from Aura 2
    tags: []
components:
  schemas:
    WebsocketHeadersDeepgramAura:
      type: object
      properties:
        X-World-Part-Override:
          type: string
          description: "Target world part override. Auto-selected if not provided. Available world parts: `na`, `eu`."
          enum:
            - na
            - eu
    LanguageCode:
      type: string
      description: ISO-639-1 language code.
      enum:
        - en
        - ja
        - zh
        - de
        - hi
        - fr
        - ko
        - pt
        - it
        - es
        - id
        - nl
        - tr
        - fil
        - pl
        - sv
        - bg
        - ro
        - ar
        - cs
        - el
        - fi
        - hr
        - ms
        - sk
        - da
        - ta
        - uk
        - ru
        - hu
        - no
        - vi
    SampleRate:
      type: integer
      description: Audio sample rate in Hz.
      enum:
        - 8000
        - 16000
        - 22050
        - 24000
        - 32000
        - 44100
        - 48000
    TtsModel:
      type: string
      description: TTS model identifier.
      enum:
        - aura:2
        - eleven:3
        - eleven-flash:2
        - eleven-flash:2.5
        - eleven-multilingual:2
        - canopylabs/orpheus:en
        - deepgram/aura:2
        - deepgram/aura:2-en
        - deepgram/aura:2-es
        - rime/arcana:3-en
        - rime/arcana:3-es
        - rime/arcana:3-hi
        - rime/arcana:ar
        - rime/arcana:de
        - rime/arcana:en
        - rime/arcana:es
        - rime/arcana:fr
  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
    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
    DeepgramAuraTtsBinaryAudio:
      name: DeepgramAuraTtsBinaryAudio
      title: Binary Audio Frame
      summary: Raw binary audio frame from Deepgram Aura.
      contentType: application/octet-stream
      payload:
        type: object
        description: Raw binary audio data sent as a WebSocket binary frame. This is NOT a JSON message — it is a raw audio buffer. The encoding and sample rate match the query parameters used when opening the connection. The object schema below is for documentation purposes only as required by the AsyncAPI tooling.
        required:
          - type
        properties:
          type:
            type: string
            const: binary
            description: Placeholder discriminator. The actual message is a raw binary WebSocket frame, not JSON.
      examples:
        - name: binaryAudioFrame
          summary: Raw binary audio buffer (e.g. linear16 PCM at 24kHz)
          payload: 0000FF00000000FF00000000010101010101010100000000FFFFFFFFFFFEFEFDFEFEFEFEFDFDFEFEFEFEFEFEFEFEFEFFFFFFFFFEFEFEFEFF0001000001020303030303030303030201010000FFFFFEFDFDFDFDFEFFFFFFFF0001020303020201000000FFFDFCFBFAFAFBFAF9F8F7F7F7F6F6F4F2F2F3F7FC000406090F14191A19181715110E0A05FEF9F6F3F0EEECEBEBECEEF2F6F9FC0005090D0F101010100E0C080401
    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.
    TtsInitRequest:
      name: TtsInitRequest
      title: Init Request
      summary: Initialize a TTS session with model and voice configuration.
      contentType: application/json
      payload:
        type: object
        description: Initialize a session with model and voice configuration before sending text.
        required:
          - type
          - model
        properties:
          type:
            type: string
            const: init
            default: init
          model:
            $ref: "#/components/schemas/TtsModel"
          voice:
            type: string
            description: Voice identifier
          config:
            type: object
            description: Synthesis configuration options
            properties:
              sample_rate:
                $ref: "#/components/schemas/SampleRate"
              encoding:
                type: string
                description: Audio encoding format
                enum:
                  - linear16
                  - mp3
                  - opus
              language:
                $ref: "#/components/schemas/LanguageCode"
              speed:
                type: number
                description: Speech speed multiplier (e.g., 1.0 for normal)
      examples:
        - name: ttsInit
          summary: Initialize Aura 2 TTS session
          payload:
            type: init
            model: aura:2
            voice: aura-2-thalia-en
            config:
              sample_rate: 24000
              encoding: linear16
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: |
        API key issued by SLNG. Pass as `Authorization: Bearer <token>` in the WebSocket upgrade request headers.