asyncapi: 3.0.0
info:
  title: SLNG Gateway API - Reson8 STT
  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
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/stt/reson8/reson8stt:v1:
    address: /v1/stt/reson8/reson8stt:v1
    title: Reson8 STT v1
    summary: Reson8 STT v1
    description: Real-time speech-to-text transcription using Reson8 via WebSocket. Supports streaming audio with word-level timestamps, confidence scores, and partial results.
    tags:
      - name: Reson8 STT v1
    servers:
      - $ref: "#/servers/production"
      - $ref: "#/servers/staging"
    messages:
      Reson8SttInitRequest:
        $ref: "#/components/messages/Reson8SttInitRequest"
      SttAudioMessage:
        $ref: "#/components/messages/SttAudioMessage"
      SttFinalizeMessage:
        $ref: "#/components/messages/SttFinalizeMessage"
      SttCloseMessage:
        $ref: "#/components/messages/SttCloseMessage"
      KeepaliveMessage:
        $ref: "#/components/messages/KeepaliveMessage"
      SttReadyResponse:
        $ref: "#/components/messages/SttReadyResponse"
      SttPartialTranscript:
        $ref: "#/components/messages/SttPartialTranscript"
      SttFinalTranscript:
        $ref: "#/components/messages/SttFinalTranscript"
      Reson8SttFlushConfirmation:
        $ref: "#/components/messages/Reson8SttFlushConfirmation"
      SttErrorResponse:
        $ref: "#/components/messages/SttErrorResponse"
    bindings:
      ws:
        method: GET
        headers:
          $ref: "#/components/schemas/WebsocketHeadersReson8"
operations:
  sttReson8Reson8sttV1ReceiveInit:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1"
    summary: Initialize session on Reson8 STT v1
    messages:
      - $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1/messages/Reson8SttInitRequest"
    description: Initialize session on Reson8 STT v1
    tags: []
  sttReson8Reson8sttV1ReceiveAudio:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1"
    summary: Send audio frame to Reson8 STT v1
    messages:
      - $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1/messages/SttAudioMessage"
    description: Send audio frame to Reson8 STT v1
    tags: []
  sttReson8Reson8sttV1ReceiveFinalize:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1"
    summary: Force-finalize buffered audio on Reson8 STT v1
    messages:
      - $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1/messages/SttFinalizeMessage"
    description: Force-finalize buffered audio on Reson8 STT v1
    tags: []
  sttReson8Reson8sttV1ReceiveClose:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1"
    summary: Close audio stream on Reson8 STT v1
    messages:
      - $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1/messages/SttCloseMessage"
    description: Close audio stream on Reson8 STT v1
    tags: []
  sttReson8Reson8sttV1ReceiveKeepalive:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1"
    summary: Send keepalive on Reson8 STT v1
    messages:
      - $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1/messages/KeepaliveMessage"
    description: Send keepalive on Reson8 STT v1
    tags: []
  sttReson8Reson8sttV1SendReady:
    action: send
    channel:
      $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1"
    summary: Receive ready signal from Reson8 STT v1
    messages:
      - $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1/messages/SttReadyResponse"
    description: Receive ready signal from Reson8 STT v1
    tags: []
  sttReson8Reson8sttV1SendPartialTranscript:
    action: send
    channel:
      $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1"
    summary: Receive partial transcript from Reson8 STT v1
    messages:
      - $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1/messages/SttPartialTranscript"
    description: Receive partial transcript from Reson8 STT v1
    tags: []
  sttReson8Reson8sttV1SendFinalTranscript:
    action: send
    channel:
      $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1"
    summary: Receive final transcript from Reson8 STT v1
    messages:
      - $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1/messages/SttFinalTranscript"
    description: Receive final transcript from Reson8 STT v1
    tags: []
  sttReson8Reson8sttV1SendFlushConfirmation:
    action: send
    channel:
      $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1"
    summary: Receive flush confirmation from Reson8 STT v1
    messages:
      - $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1/messages/Reson8SttFlushConfirmation"
    description: Receive flush confirmation from Reson8 STT v1
    tags: []
  sttReson8Reson8sttV1SendError:
    action: send
    channel:
      $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1"
    summary: Receive error from Reson8 STT v1
    messages:
      - $ref: "#/channels/~1v1~1stt~1reson8~1reson8stt:v1/messages/SttErrorResponse"
    description: Receive error from Reson8 STT v1
    tags: []
components:
  schemas:
    WebsocketHeadersReson8:
      type: object
      properties:
        X-World-Part-Override:
          type: string
          description: "Target world part override. Auto-selected if not provided. Available world parts: `eu`."
          enum:
            - 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
  messages:
    Reson8SttInitRequest:
      name: Reson8SttInitRequest
      title: Init Request (Reson8)
      summary: Initialize a Reson8 STT session with provider-specific recognition configuration.
      contentType: application/json
      payload:
        type: object
        description: Initialize a Reson8 STT session with provider-specific configuration options before streaming audio.
        required:
          - type
        properties:
          type:
            type: string
            const: init
          config:
            type: object
            description: Reson8 recognition configuration options
            properties:
              encoding:
                type: string
                description: Audio encoding format.
                default: pcm_s16le
                enum:
                  - pcm_s16le
              sample_rate:
                type: integer
                description: Audio sample rate in Hz.
                default: 16000
              channels:
                type: integer
                description: Number of audio channels.
                default: 1
              custom_model_id:
                type: string
                description: ID of a custom model to bias transcription.
              include_timestamps:
                type: boolean
                description: Add start_ms and duration_ms to transcript and word objects.
                default: false
              include_words:
                type: boolean
                description: Add word-level detail array to transcript responses.
                default: false
              include_confidence:
                type: boolean
                description: Add confidence score (0-1) to each word object.
                default: false
              enable_partials:
                type: boolean
                description: Enable interim (partial) results and the is_final flag on transcripts.
                default: true
      examples:
        - name: reson8Init
          summary: Initialize Reson8 STT with default settings
          payload:
            type: init
            config:
              encoding: pcm_s16le
              sample_rate: 16000
              channels: 1
              enable_partials: true
    Reson8SttFlushConfirmation:
      name: Reson8SttFlushConfirmation
      title: Flush Confirmation (Reson8)
      summary: Acknowledges flush completion from Reson8.
      contentType: application/json
      payload:
        type: object
        description: Acknowledges that a flush request has been processed by the Reson8 server.
        required:
          - type
        properties:
          type:
            type: string
            const: flush_confirmation
          id:
            type: string
            description: Caller-defined identifier echoed back from the flush request.
      examples:
        - name: flushConfirmation
          summary: Flush confirmation response
          payload:
            type: flush_confirmation
            id: flush-001
    SttAudioMessage:
      name: SttAudioMessage
      title: Audio Message
      summary: Stream an audio frame to be transcribed.
      contentType: application/json
      payload:
        type: object
        description: Stream an audio frame to be transcribed.
        required:
          - type
          - data
        properties:
          type:
            type: string
            const: audio
          data:
            type: string
            format: byte
            description: Base64-encoded audio data
      examples:
        - name: audioFrame
          summary: Send a base64-encoded audio frame
          payload:
            type: audio
            data: UklGRiQAAABXQVZFZm10IBAAAAABAAEA...
    SttFinalizeMessage:
      name: SttFinalizeMessage
      title: Finalize Message
      summary: Force-finalize buffered audio tokens without closing the connection.
      contentType: application/json
      payload:
        type: object
        description: Mid-stream flush — forces the server to finalize any buffered audio and return results. The connection remains open for further audio.
        required:
          - type
        properties:
          type:
            type: string
            const: finalize
      examples:
        - name: finalize
          summary: Force-finalize buffered audio
          payload:
            type: finalize
    SttCloseMessage:
      name: SttCloseMessage
      title: Close Message
      summary: Signal end of audio stream and close the connection.
      contentType: application/json
      payload:
        type: object
        description: Signal that no more audio will be sent. The server processes remaining audio, sends final results, then closes the connection.
        required:
          - type
        properties:
          type:
            type: string
            const: close
      examples:
        - name: close
          summary: Close the audio stream
          payload:
            type: close
    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
    SttReadyResponse:
      name: SttReadyResponse
      title: Ready Response
      summary: Indicates the session is ready to receive audio.
      contentType: application/json
      payload:
        type: object
        description: Indicates the session is ready to receive audio.
        required:
          - type
          - session_id
        properties:
          type:
            type: string
            const: ready
          session_id:
            type: string
            description: Unique session identifier
      examples:
        - name: ready
          summary: Session ready response
          payload:
            type: ready
            session_id: sess_abc123
    SttPartialTranscript:
      name: SttPartialTranscript
      title: Partial Transcript
      summary: Interim transcription result (when enable_partials is true).
      contentType: application/json
      payload:
        type: object
        description: Interim transcription result (when enable_partials is true).
        required:
          - type
          - transcript
        properties:
          type:
            type: string
            const: partial_transcript
          transcript:
            type: string
            description: Transcribed text so far
          confidence:
            type: number
            description: Confidence score (0-1)
      examples:
        - name: partial
          summary: Partial transcription result
          payload:
            type: partial_transcript
            transcript: Hello wor
            confidence: 0.85
    SttFinalTranscript:
      name: SttFinalTranscript
      title: Final Transcript
      summary: Final transcription result with optional metadata.
      contentType: application/json
      payload:
        type: object
        description: Final transcription result with optional metadata.
        required:
          - type
          - transcript
        properties:
          type:
            type: string
            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
      examples:
        - name: finalTranscript
          summary: Final transcription result
          payload:
            type: final_transcript
            transcript: Hello world, this is a test.
            confidence: 0.95
            language: en
            duration: 2.5
    SttErrorResponse:
      name: SttErrorResponse
      title: Error Response
      summary: Indicates an error occurred during recognition.
      contentType: application/json
      payload:
        type: object
        description: Indicates an error occurred during recognition.
        required:
          - type
          - code
          - message
        properties:
          type:
            type: string
            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
      examples:
        - name: authError
          summary: Authentication error
          payload:
            type: error
            code: auth_error
            message: Invalid or expired API key
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: |
        API key issued by SLNG. Pass as `Authorization: Bearer <token>` in the WebSocket upgrade request headers.