asyncapi: 3.0.0
info:
  title: SLNG Gateway API - Jambonz Bridges
  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/bridges/jambonz/stt/{model_variant}:
    address: /v1/bridges/jambonz/stt/{model_variant}
    title: Jambonz STT Bridge
    summary: Jambonz STT Bridge
    description: Reference for the Jambonz custom WebSocket STT bridge channel, including init, audio, stop messages and the model_variant routing parameter.
    tags:
      - name: Jambonz STT Bridge
    servers:
      - $ref: "#/servers/production"
      - $ref: "#/servers/staging"
    messages:
      JambonzStartMessage:
        $ref: "#/components/messages/JambonzStartMessage"
      JambonzStopMessage:
        $ref: "#/components/messages/JambonzStopMessage"
      JambonzTranscription:
        $ref: "#/components/messages/JambonzTranscription"
      JambonzSTTErrorResponse:
        $ref: "#/components/messages/JambonzSTTErrorResponse"
    bindings:
      ws:
        method: GET
        headers:
          $ref: "#/components/schemas/WebsocketHeaders"
        query:
          $ref: "#/components/schemas/WebsocketQueryParams"
  /v1/bridges/jambonz/tts/{model_variant}:
    address: /v1/bridges/jambonz/tts/{model_variant}
    title: Jambonz TTS Bridge
    summary: Jambonz TTS Bridge
    description: Reference for the Jambonz custom WebSocket TTS bridge channel, including stream, flush, stop messages, binary audio frames, and model_variant routing.
    tags:
      - name: Jambonz TTS Bridge
    servers:
      - $ref: "#/servers/production"
      - $ref: "#/servers/staging"
    messages:
      JambonzStreamMessage:
        $ref: "#/components/messages/JambonzStreamMessage"
      JambonzFlushMessage:
        $ref: "#/components/messages/JambonzFlushMessage"
      JambonzTtsStopMessage:
        $ref: "#/components/messages/JambonzTtsStopMessage"
      JambonzConnectMessage:
        $ref: "#/components/messages/JambonzConnectMessage"
      JambonzTTSErrorResponse:
        $ref: "#/components/messages/JambonzTTSErrorResponse"
      KeepaliveMessage:
        $ref: "#/components/messages/KeepaliveMessage"
    bindings:
      ws:
        method: GET
        headers:
          $ref: "#/components/schemas/WebsocketHeaders"
        query:
          $ref: "#/components/schemas/WebsocketQueryParams"
operations:
  jambonzSttBridgeReceiveStart:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1bridges~1jambonz~1stt~1%7Bmodel_variant%7D"
    summary: Start session on Jambonz STT Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1jambonz~1stt~1%7Bmodel_variant%7D/messages/JambonzStartMessage"
    description: Start session on Jambonz STT Bridge
    tags: []
  jambonzSttBridgeReceiveStop:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1bridges~1jambonz~1stt~1%7Bmodel_variant%7D"
    summary: Stop session on Jambonz STT Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1jambonz~1stt~1%7Bmodel_variant%7D/messages/JambonzStopMessage"
    description: Stop session on Jambonz STT Bridge
    tags: []
  jambonzSttBridgeSendTranscription:
    action: send
    channel:
      $ref: "#/channels/~1v1~1bridges~1jambonz~1stt~1%7Bmodel_variant%7D"
    summary: Receive transcription from Jambonz STT Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1jambonz~1stt~1%7Bmodel_variant%7D/messages/JambonzTranscription"
    description: Receive transcription from Jambonz STT Bridge
    tags: []
  jambonzSttBridgeSendError:
    action: send
    channel:
      $ref: "#/channels/~1v1~1bridges~1jambonz~1stt~1%7Bmodel_variant%7D"
    summary: Receive error from Jambonz STT Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1jambonz~1stt~1%7Bmodel_variant%7D/messages/JambonzSTTErrorResponse"
    description: Receive error from Jambonz STT Bridge
    tags: []
  jambonzTtsBridgeReceiveStream:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1bridges~1jambonz~1tts~1%7Bmodel_variant%7D"
    summary: Send stream message on Jambonz TTS Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1jambonz~1tts~1%7Bmodel_variant%7D/messages/JambonzStreamMessage"
    description: Send stream message on Jambonz TTS Bridge
    tags: []
  jambonzTtsBridgeReceiveFlush:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1bridges~1jambonz~1tts~1%7Bmodel_variant%7D"
    summary: Flush buffered audio on Jambonz TTS Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1jambonz~1tts~1%7Bmodel_variant%7D/messages/JambonzFlushMessage"
    description: Flush buffered audio on Jambonz TTS Bridge
    tags: []
  jambonzTtsBridgeReceiveStop:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1bridges~1jambonz~1tts~1%7Bmodel_variant%7D"
    summary: Stop synthesis on Jambonz TTS Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1jambonz~1tts~1%7Bmodel_variant%7D/messages/JambonzTtsStopMessage"
    description: Stop synthesis on Jambonz TTS Bridge
    tags: []
  jambonzTtsBridgeReceiveKeepalive:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1bridges~1jambonz~1tts~1%7Bmodel_variant%7D"
    summary: Send keepalive on Jambonz TTS Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1jambonz~1tts~1%7Bmodel_variant%7D/messages/KeepaliveMessage"
    description: Send keepalive on Jambonz TTS Bridge
    tags: []
  jambonzTtsBridgeSendConnect:
    action: send
    channel:
      $ref: "#/channels/~1v1~1bridges~1jambonz~1tts~1%7Bmodel_variant%7D"
    summary: Receive connect message from Jambonz TTS Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1jambonz~1tts~1%7Bmodel_variant%7D/messages/JambonzConnectMessage"
    description: Receive connect message from Jambonz TTS Bridge
    tags: []
  jambonzTtsBridgeSendError:
    action: send
    channel:
      $ref: "#/channels/~1v1~1bridges~1jambonz~1tts~1%7Bmodel_variant%7D"
    summary: Receive error from Jambonz TTS Bridge
    messages:
      - $ref: "#/channels/~1v1~1bridges~1jambonz~1tts~1%7Bmodel_variant%7D/messages/JambonzTTSErrorResponse"
    description: Receive error from Jambonz TTS Bridge
    tags: []
components:
  messages:
    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
    JambonzTTSErrorResponse:
      name: JambonzTTSErrorResponse
      title: Error Response (Jambonz TTS)
      summary: Error occurred during Jambonz TTS synthesis.
      contentType: application/json
      payload:
        type: object
        description: Error occurred during synthesis.
        required:
          - type
          - error
        properties:
          type:
            type: string
            const: error
          error:
            type: string
            description: Human-readable error description.
      examples:
        - name: jambonzTTSError
          summary: Jambonz TTS error
          payload:
            type: error
            error: Upstream synthesis service unavailable
    JambonzConnectMessage:
      name: JambonzConnectMessage
      title: Connect Message
      summary: Connection established with audio format information.
      contentType: application/json
      payload:
        type: object
        description: Connection established with audio format information.
        required:
          - type
          - data
        properties:
          type:
            type: string
            const: connect
          data:
            type: object
            description: Audio format configuration.
            properties:
              sample_rate:
                $ref: "#/components/schemas/SampleRate"
              base64_encoding:
                type: boolean
                description: Whether audio chunks are base64 encoded.
      examples:
        - name: jambonzConnect
          summary: Connection established
          payload:
            type: connect
            data:
              sample_rate: 16000
              base64_encoding: false
    JambonzTtsStopMessage:
      name: JambonzTtsStopMessage
      title: Stop Message (Jambonz TTS)
      summary: Stop synthesis and close the session.
      contentType: application/json
      payload:
        type: object
        description: Stop synthesis and close the session.
        required:
          - type
        properties:
          type:
            type: string
            const: stop
      examples:
        - name: jambonzTtsStop
          summary: Stop synthesis
          payload:
            type: stop
    JambonzFlushMessage:
      name: JambonzFlushMessage
      title: Flush Message
      summary: Flush buffered audio to the client.
      contentType: application/json
      payload:
        type: object
        description: Flush buffered audio to the client.
        required:
          - type
        properties:
          type:
            type: string
            const: flush
      examples:
        - name: jambonzFlush
          summary: Flush buffered audio
          payload:
            type: flush
    JambonzStreamMessage:
      name: JambonzStreamMessage
      title: Stream Message
      summary: Send text chunk to synthesize into audio.
      contentType: application/json
      payload:
        type: object
        description: Send text chunk to synthesize into audio.
        required:
          - type
          - text
        properties:
          type:
            type: string
            const: stream
          text:
            type: string
            description: Text chunk to synthesize.
          pronunciation:
            type: object
            description: Optional pronunciation hint applied to this text chunk. Forwarded to providers that support pronunciation dictionaries (e.g. IPA or SSML overrides).
            properties:
              mode:
                type: string
                description: Pronunciation override mode (e.g. `ipa`, `ssml`).
              name:
                type: string
                description: Identifier of the term whose pronunciation is being overridden.
              dictionary_id:
                type: string
                description: Pronunciation dictionary identifier.
      examples:
        - name: jambonzStream
          summary: Stream text for synthesis
          payload:
            type: stream
            text: Hello, how can I help you today?
    JambonzSTTErrorResponse:
      name: JambonzSTTErrorResponse
      title: Error Response (Jambonz STT)
      summary: Error occurred during Jambonz STT recognition.
      contentType: application/json
      payload:
        type: object
        description: Error occurred during recognition.
        required:
          - type
          - error
        properties:
          type:
            type: string
            const: error
          error:
            type: string
            description: Human-readable error description.
      examples:
        - name: jambonzSTTError
          summary: Jambonz STT error
          payload:
            type: error
            error: Upstream transcription service unavailable
    JambonzTranscription:
      name: JambonzTranscription
      title: Transcription
      summary: Transcription result with alternatives and metadata.
      contentType: application/json
      payload:
        type: object
        description: Transcription result with alternatives and metadata.
        required:
          - type
          - is_final
          - alternatives
        properties:
          type:
            type: string
            const: transcription
          is_final:
            type: boolean
            description: Whether this is a final (not interim) transcription.
          alternatives:
            type: array
            description: List of transcription alternatives ranked by confidence.
            items:
              type: object
              properties:
                confidence:
                  type: number
                  description: Confidence score (0-1).
                transcript:
                  type: string
                  description: Transcribed text.
          channel:
            type: integer
            description: Audio channel number.
          language:
            $ref: "#/components/schemas/LanguageCode"
      examples:
        - name: jambonzTranscriptionInterim
          summary: Interim transcription
          payload:
            type: transcription
            is_final: false
            alternatives:
              - confidence: 0.85
                transcript: Hello
            channel: 0
        - name: jambonzTranscriptionFinal
          summary: Final transcription
          payload:
            type: transcription
            is_final: true
            alternatives:
              - confidence: 0.97
                transcript: Hello world
            channel: 0
            language: en-US
    JambonzStopMessage:
      name: JambonzStopMessage
      title: Stop Message
      summary: End the Jambonz STT session and finalize transcription.
      contentType: application/json
      payload:
        type: object
        description: End the STT session and finalize transcription.
        required:
          - type
        properties:
          type:
            type: string
            const: stop
      examples:
        - name: jambonzStop
          summary: Stop Jambonz STT session
          payload:
            type: stop
    JambonzStartMessage:
      name: JambonzStartMessage
      title: Start Message
      summary: Initialize Jambonz STT session with language and audio configuration.
      contentType: application/json
      payload:
        type: object
        description: Initialize STT session with language and audio configuration.
        required:
          - type
          - encoding
        properties:
          type:
            type: string
            const: start
          language:
            $ref: "#/components/schemas/LanguageCode"
          format:
            type: string
            description: Audio format descriptor.
            enum:
              - raw
          encoding:
            type: string
            description: Audio encoding for streamed frames.
            enum:
              - LINEAR16
          sampleRateHz:
            type: number
            description: Audio sample rate in Hz.
            enum:
              - 8000
              - 16000
          interimResults:
            type: boolean
            description: Enable interim (partial) transcription results.
          hints:
            type: array
            description: Speech recognition hints/phrases.
            items:
              type: string
          boostValues:
            type: array
            description: Boost values corresponding to hints.
            items:
              type: number
      examples:
        - name: jambonzStart
          summary: Start Jambonz STT session
          payload:
            type: start
            language: en-US
            format: raw
            encoding: LINEAR16
            sampleRateHz: 8000
            interimResults: true
  schemas:
    SampleRate:
      type: integer
      description: Audio sample rate in Hz.
      enum:
        - 8000
        - 16000
        - 22050
        - 24000
        - 32000
        - 44100
        - 48000
    WebsocketHeaders:
      type: object
      properties:
        X-Region-Override:
          type: string
          description: Target region override. Auto-selected if not provided.
        X-World-Part-Override:
          type: string
          description: Target world part override. Auto-selected if not provided.
    WebsocketQueryParams:
      type: object
      properties:
        region:
          type: string
          description: Target region override as a query parameter. Auto-selected if not provided. Equivalent to the `X-Region-Override` header; the header takes precedence when both are set.
          enum:
            - ap-southeast-2
            - eu-north-1
            - us-east-1
        world-part:
          type: string
          description: Target world part override as a query parameter. Auto-selected if not provided. Equivalent to the `X-World-Part-Override` header; the header takes precedence when both are set.
          enum:
            - ap
            - eu
            - na
    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
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: |
        API key issued by SLNG. Pass as `Authorization: Bearer <token>` in the WebSocket upgrade request headers.