asyncapi: 3.0.0
info:
  title: SLNG Gateway API - Deepgram (WebSocket)
  version: 0.2.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
servers:
  production:
    host: api.slng.ai
    protocol: wss
    description: Production
  staging:
    host: stageapi.slng.ai
    protocol: wss
    description: Staging
channels:
  /v1/stt/deepgram/nova:2:
    address: /v1/stt/deepgram/nova:2
    title: nova:2 WebSocket
    summary: nova:2 - websocket
    description: Speech-to-Text API for converting audio files to text using Deepgram nova. Real-time speech-to-text transcription with ultra-low latency using Deepgram's Nova model. Optimized for streaming audio with intelligent Voice Activity Detection (VAD) and speaker diarization.
    tags:
      - name: Nova 2
    servers:
      - $ref: "#/servers/production"
      - $ref: "#/servers/staging"
    messages:
      request:
        $ref: "#/components/messages/SttWebsocketRequest"
      response:
        $ref: "#/components/messages/SttWebsocketResponse"
    bindings:
      ws:
        method: GET
        headers:
          $ref: "#/components/schemas/WebsocketHeaders"
  /v1/stt/deepgram/nova:3:
    address: /v1/stt/deepgram/nova:3
    title: nova:3 WebSocket
    summary: nova:3 - websocket
    description: Speech-to-Text API for converting audio files to text using Deepgram nova. Real-time speech-to-text transcription with ultra-low latency using Deepgram's Nova model. Optimized for streaming audio with intelligent Voice Activity Detection (VAD) and speaker diarization.
    tags:
      - name: Nova 3
    servers:
      - $ref: "#/servers/production"
      - $ref: "#/servers/staging"
    messages:
      request:
        $ref: "#/components/messages/SttWebsocketRequest"
      response:
        $ref: "#/components/messages/SttWebsocketResponse"
    bindings:
      ws:
        method: GET
        headers:
          $ref: "#/components/schemas/WebsocketHeaders"
  /v1/stt/deepgram/nova:3-medical:
    address: /v1/stt/deepgram/nova:3-medical
    title: nova:3-medical WebSocket
    summary: nova:3-medical - websocket
    description: Speech-to-Text API for converting audio files to text using Deepgram nova. Real-time speech-to-text transcription with ultra-low latency using Deepgram's Nova model. Optimized for streaming audio with intelligent Voice Activity Detection (VAD) and speaker diarization.
    tags:
      - name: Nova 3 Medical
    servers:
      - $ref: "#/servers/production"
      - $ref: "#/servers/staging"
    messages:
      request:
        $ref: "#/components/messages/SttWebsocketRequest"
      response:
        $ref: "#/components/messages/SttWebsocketResponse"
    bindings:
      ws:
        method: GET
        headers:
          $ref: "#/components/schemas/WebsocketHeaders"
  /v1/tts/deepgram/aura:2:
    address: /v1/tts/deepgram/aura:2
    title: aura:2 WebSocket
    summary: aura:2 - websocket
    description: Text-to-Speech API for generating speech from text using Deepgram aura. Real-time conversational TTS designed for voice agents with ultra-low latency. Establishes a WebSocket connection for real-time text-to-speech. Audio data is sent as raw binary WebSocket frames (not JSON audio_chunk messages).
    tags:
      - name: Aura 2 (Deepgram)
    servers:
      - $ref: "#/servers/production"
      - $ref: "#/servers/staging"
    messages:
      request:
        $ref: "#/components/messages/TtsWebsocketRequest"
      response:
        $ref: "#/components/messages/TtsWebsocketResponse"
    bindings:
      ws:
        method: GET
        headers:
          $ref: "#/components/schemas/WebsocketHeaders"
operations:
  sttDeepgramNova2Send:
    action: send
    channel:
      $ref: "#/channels/~1v1~1stt~1deepgram~1nova:2"
    summary: Send audio frames to Deepgram Nova 2
    messages:
      - $ref: "#/channels/~1v1~1stt~1deepgram~1nova:2/messages/request"
    description: Send audio frames to Deepgram Nova 2
    tags: []
  sttDeepgramNova2Receive:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1stt~1deepgram~1nova:2"
    summary: Receive transcripts from Deepgram Nova 2
    messages:
      - $ref: "#/channels/~1v1~1stt~1deepgram~1nova:2/messages/response"
    description: Receive transcripts from Deepgram Nova 2
    tags: []
  sttDeepgramNova3Send:
    action: send
    channel:
      $ref: "#/channels/~1v1~1stt~1deepgram~1nova:3"
    summary: Send audio frames to Deepgram Nova 3
    messages:
      - $ref: "#/channels/~1v1~1stt~1deepgram~1nova:3/messages/request"
    description: Send audio frames to Deepgram Nova 3
    tags: []
  sttDeepgramNova3Receive:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1stt~1deepgram~1nova:3"
    summary: Receive transcripts from Deepgram Nova 3
    messages:
      - $ref: "#/channels/~1v1~1stt~1deepgram~1nova:3/messages/response"
    description: Receive transcripts from Deepgram Nova 3
    tags: []
  sttDeepgramNova3MedicalSend:
    action: send
    channel:
      $ref: "#/channels/~1v1~1stt~1deepgram~1nova:3-medical"
    summary: Send audio frames to Deepgram Nova 3 Medical
    messages:
      - $ref: "#/channels/~1v1~1stt~1deepgram~1nova:3-medical/messages/request"
    description: Send audio frames to Deepgram Nova 3 Medical
    tags: []
  sttDeepgramNova3MedicalReceive:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1stt~1deepgram~1nova:3-medical"
    summary: Receive transcripts from Deepgram Nova 3 Medical
    messages:
      - $ref: "#/channels/~1v1~1stt~1deepgram~1nova:3-medical/messages/response"
    description: Receive transcripts from Deepgram Nova 3 Medical
    tags: []
  ttsDeepgramAura2Send:
    action: send
    channel:
      $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2"
    summary: Send synthesis requests to Deepgram Aura 2
    messages:
      - $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2/messages/request"
    description: Send synthesis requests to Deepgram Aura 2
    tags: []
  ttsDeepgramAura2Receive:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2"
    summary: Receive audio chunks from Deepgram Aura 2
    messages:
      - $ref: "#/channels/~1v1~1tts~1deepgram~1aura:2/messages/response"
    description: Receive audio chunks from Deepgram Aura 2
    tags: []
components:
  messages:
    TtsWebsocketResponse:
      name: TtsWebsocketResponse
      title: TTS WebSocket Response
      payload:
        $ref: "#/components/schemas/TtsWebsocketMessage"
    TtsWebsocketRequest:
      name: TtsWebsocketRequest
      title: TTS WebSocket Request
      payload:
        $ref: "#/components/schemas/TtsWebsocketRequestMessage"
    SttWebsocketResponse:
      name: SttWebsocketResponse
      title: STT WebSocket Response
      payload:
        $ref: "#/components/schemas/SttWebsocketMessage"
    SttWebsocketRequest:
      name: SttWebsocketRequest
      title: STT WebSocket Request
      payload:
        $ref: "#/components/schemas/SttWebsocketRequestMessage"
  schemas:
    TtsWebsocketMessage:
      oneOf:
        - title: Ready Message
          type: object
          description: Indicates the session is ready to receive messages.
          required:
            - type
            - session_id
          properties:
            type:
              const: ready
            session_id:
              type: string
              description: Unique session identifier
        - title: Audio Chunk
          type: object
          description: Chunk of base64-encoded audio data.
          required:
            - type
            - data
          properties:
            type:
              const: audio_chunk
            data:
              type: string
              format: byte
              description: Base64-encoded audio data
            sequence:
              type: integer
              description: Sequence number for ordering chunks
        - title: Segment Start
          type: object
          description: Signals the start of a synthesized segment.
          required:
            - type
            - segment_id
          properties:
            type:
              const: segment_start
            segment_id:
              type: string
              description: Unique segment identifier
        - title: Segment End
          type: object
          description: Signals the end of a synthesized segment.
          required:
            - type
            - segment_id
          properties:
            type:
              const: segment_end
            segment_id:
              type: string
              description: Unique segment identifier
        - title: Flushed
          type: object
          description: Acknowledges that buffered output was flushed.
          required:
            - type
          properties:
            type:
              const: flushed
        - title: Cleared
          type: object
          description: Acknowledges that queued output was cleared.
          required:
            - type
          properties:
            type:
              const: cleared
        - title: Audio End
          type: object
          description: Signals the end of audio generation.
          required:
            - type
          properties:
            type:
              const: audio_end
            duration:
              type: number
              description: Total audio duration
        - title: Error Message
          type: object
          description: Indicates an error occurred during synthesis.
          required:
            - type
            - code
            - message
          properties:
            type:
              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
    TtsWebsocketRequestMessage:
      oneOf:
        - title: Init Message
          type: object
          description: Initialize a session with model and voice configuration before sending text.
          required:
            - type
            - model
          properties:
            type:
              const: init
              type: string
              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)
        - title: Text Message
          type: object
          description: Send text to synthesize into audio output.
          required:
            - type
            - text
          properties:
            type:
              const: text
            text:
              type: string
              description: Text to synthesize
            flush:
              type: boolean
              description: Whether to flush remaining audio immediately after this text
        - title: Flush Message
          type: object
          description: Force any buffered text/audio to be finalized and delivered.
          required:
            - type
          properties:
            type:
              const: flush
        - title: Clear Message
          type: object
          description: Clear any queued text/audio from the current session.
          required:
            - type
          properties:
            type:
              const: clear
        - title: Cancel Message
          type: object
          description: Cancel the current generation and stop any further audio.
          required:
            - type
          properties:
            type:
              const: cancel
    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
        - geneing/kokoro:v1
        - myshell/melo:v1
        - rime/arcana:3-en
        - rime/arcana:3-fr
        - rime/arcana:3-hi
        - rime/arcana:ar
        - rime/arcana:de
        - rime/arcana:en
        - rime/arcana:es
        - rime/arcana:fr
    WebsocketHeaders:
      type: object
      properties:
        X-Region-Override:
          type: string
          description: Optional. Specify a target region for this model. If not provided, the system will automatically select an appropriate region.
        Upgrade:
          type: string
          enum:
            - websocket
        Connection:
          type: string
          enum:
            - Upgrade
    SttWebsocketMessage:
      oneOf:
        - title: Ready Message
          type: object
          description: Indicates the session is ready to receive audio.
          required:
            - type
            - session_id
          properties:
            type:
              const: ready
            session_id:
              type: string
              description: Unique session identifier
        - title: Partial Transcript
          type: object
          description: Interim transcription result (when enable_partials is true).
          required:
            - type
            - transcript
          properties:
            type:
              const: partial_transcript
            transcript:
              type: string
              description: Transcribed text so far
            confidence:
              type: number
              description: Confidence score (0-1)
        - title: Final Transcript
          type: object
          description: Final transcription result with optional metadata.
          required:
            - type
            - transcript
          properties:
            type:
              const: final_transcript
            transcript:
              type: string
              description: Complete transcribed text
            confidence:
              type: number
              description: Overall confidence score (0-1)
            language:
              $ref: "#/components/schemas/LanguageCode"
            duration:
              type: number
              description: Audio duration
        - title: Error Message
          type: object
          description: Indicates an error occurred during recognition.
          required:
            - type
            - code
            - message
          properties:
            type:
              const: error
            code:
              type: string
              description: Error code (e.g., auth_error, config_error, rate_limit, provider_error)
            message:
              type: string
              description: Human-readable error description
    SttWebsocketRequestMessage:
      oneOf:
        - title: Init Message
          type: object
          description: Initialize a session with recognition configuration before streaming audio.
          required:
            - type
          properties:
            type:
              const: init
              type: string
              default: init
            config:
              type: object
              description: Recognition configuration options
              properties:
                language:
                  $ref: "#/components/schemas/LanguageCode"
                sample_rate:
                  $ref: "#/components/schemas/SampleRate"
                encoding:
                  type: string
                  description: Audio encoding format
                  enum:
                    - linear16
                    - mp3
                    - opus
                enable_vad:
                  type: boolean
                  description: Enable Voice Activity Detection
                enable_diarization:
                  type: boolean
                  description: Enable speaker diarization
                enable_word_timestamps:
                  type: boolean
                  description: Include word-level timestamps in transcripts
                enable_partials:
                  type: boolean
                  description: Enable partial/interim transcription results
        - title: Audio Message
          type: object
          description: Stream an audio frame to be transcribed.
          required:
            - type
            - data
          properties:
            type:
              const: audio
            data:
              type: string
              format: byte
              description: Base64-encoded audio data
        - title: Finalize Message
          type: object
          description: Signal that no more audio frames will be sent.
          required:
            - type
          properties:
            type:
              const: finalize