openapi: 3.0.3
info:
  title: SLNG Gateway API - SLNG STT
  version: 0.1.0
  description: Unified API for speech-to-text and text-to-speech services.
  contact:
    name: SLNG Support
    email: support@slng.ai
servers:
  - url: https://api.slng.ai
    description: Production
  - url: https://stageapi.slng.ai
    description: Staging
security:
  - BearerAuth: []
paths:
  /v1/stt/slng/openai/whisper:large-v3:
    post:
      operationId: sttWhisperLargeV3Receive
      summary: Whisper Large v3
      description: Receive transcripts from Whisper Large v3
      tags:
        - Whisper Large v3
      parameters:
        - $ref: "#/components/parameters/XWorldPartSlngWhisper"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/WhisperTranscriptionRequest"
            examples:
              binary:
                summary: Binary audio upload
                value:
                  audio: <binary>
                  language: en
          application/json:
            schema:
              $ref: "#/components/schemas/WhisperTranscriptionRequest"
            examples:
              url:
                summary: URL-based transcription
                value:
                  url: https://docs.slng.ai/audio/hello.wav
                  language: en
      responses:
        "200":
          $ref: "#/components/responses/WhisperTranscriptionSuccess"
        "400":
          $ref: "#/components/responses/WhisperBadRequest"
        "401":
          $ref: "#/components/responses/ProviderUnauthorized"
        "413":
          $ref: "#/components/responses/WhisperPayloadTooLarge"
        "500":
          $ref: "#/components/responses/WhisperInternalServerError"
        "503":
          $ref: "#/components/responses/ProviderServiceUnavailable"
  /v1/stt/slng/deepgram/nova:3-en:
    post:
      operationId: slng/deepgram/nova:3-en
      summary: Nova 3 (English)
      description: Transcribe English audio using SLNG-hosted Deepgram Nova 3.
      tags:
        - Deepgram Nova 3
      parameters:
        - $ref: "#/components/parameters/XRegionSlngNovaEn"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/SlngDeepgramNova3EnRequest"
            examples:
              binary:
                summary: Binary audio upload
                value:
                  audio: <binary>
                  language: en
          application/json:
            schema:
              $ref: "#/components/schemas/SlngDeepgramNova3EnRequest"
            examples:
              url:
                summary: URL-based transcription
                value:
                  url: https://docs.slng.ai/audio/hello.wav
                  language: en
      responses:
        "200":
          $ref: "#/components/responses/SlngDeepgramSttSuccess"
        "400":
          $ref: "#/components/responses/ProviderBadRequest"
        "401":
          $ref: "#/components/responses/ProviderUnauthorized"
        "413":
          $ref: "#/components/responses/ProviderPayloadTooLarge"
        "500":
          $ref: "#/components/responses/ProviderInternalServerError"
        "503":
          $ref: "#/components/responses/ProviderServiceUnavailable"
  /v1/stt/slng/deepgram/nova:3-es:
    post:
      operationId: slng/deepgram/nova:3-es
      summary: Nova 3 (Spanish)
      description: Transcribe Spanish audio using SLNG-hosted Deepgram Nova 3.
      tags:
        - Deepgram Nova 3
      parameters:
        - $ref: "#/components/parameters/XRegionSlngNovaEs"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/SlngDeepgramNova3EsRequest"
            examples:
              binary:
                summary: Binary audio upload
                value:
                  audio: <binary>
                  language: es
          application/json:
            schema:
              $ref: "#/components/schemas/SlngDeepgramNova3EsRequest"
            examples:
              url:
                summary: URL-based transcription
                value:
                  url: https://docs.slng.ai/audio/hello-es.wav
                  language: es
      responses:
        "200":
          $ref: "#/components/responses/SlngDeepgramSttSuccess"
        "400":
          $ref: "#/components/responses/ProviderBadRequest"
        "401":
          $ref: "#/components/responses/ProviderUnauthorized"
        "413":
          $ref: "#/components/responses/ProviderPayloadTooLarge"
        "500":
          $ref: "#/components/responses/ProviderInternalServerError"
        "503":
          $ref: "#/components/responses/ProviderServiceUnavailable"
  /v1/stt/slng/deepgram/nova:3-hi:
    post:
      operationId: slng/deepgram/nova:3-hi
      summary: Nova 3 (Hindi)
      description: Transcribe Hindi audio using SLNG-hosted Deepgram Nova 3.
      tags:
        - Deepgram Nova 3
      parameters:
        - $ref: "#/components/parameters/XRegionSlngNovaHi"
        - $ref: "#/components/parameters/XWorldPartSlngNovaHi"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/SlngDeepgramNova3HiRequest"
            examples:
              binary:
                summary: Binary audio upload
                value:
                  audio: <binary>
                  language: hi
          application/json:
            schema:
              $ref: "#/components/schemas/SlngDeepgramNova3HiRequest"
            examples:
              url:
                summary: URL-based transcription
                value:
                  url: https://docs.slng.ai/audio/hello-hi.wav
                  language: hi
      responses:
        "200":
          $ref: "#/components/responses/SlngDeepgramSttSuccess"
        "400":
          $ref: "#/components/responses/ProviderBadRequest"
        "401":
          $ref: "#/components/responses/ProviderUnauthorized"
        "413":
          $ref: "#/components/responses/ProviderPayloadTooLarge"
        "500":
          $ref: "#/components/responses/ProviderInternalServerError"
        "503":
          $ref: "#/components/responses/ProviderServiceUnavailable"
  /v1/stt/slng/deepgram/nova:3-multi:
    post:
      operationId: slng/deepgram/nova:3-multi
      summary: Nova 3 (Multi-Language)
      description: Transcribe multi-language audio using SLNG-hosted Deepgram Nova 3.
      tags:
        - Deepgram Nova 3
      parameters:
        - $ref: "#/components/parameters/XRegionSlngNovaMulti"
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: "#/components/schemas/SlngDeepgramNova3MultiRequest"
            examples:
              binary:
                summary: Binary audio upload
                value:
                  audio: <binary>
                  language: multi
          application/json:
            schema:
              $ref: "#/components/schemas/SlngDeepgramNova3MultiRequest"
            examples:
              url:
                summary: URL-based transcription
                value:
                  url: https://docs.slng.ai/audio/hello.wav
                  language: multi
      responses:
        "200":
          $ref: "#/components/responses/SlngDeepgramSttSuccess"
        "400":
          $ref: "#/components/responses/ProviderBadRequest"
        "401":
          $ref: "#/components/responses/ProviderUnauthorized"
        "413":
          $ref: "#/components/responses/ProviderPayloadTooLarge"
        "500":
          $ref: "#/components/responses/ProviderInternalServerError"
        "503":
          $ref: "#/components/responses/ProviderServiceUnavailable"
tags:
  - name: Whisper Large v3 (Compressed)
    description: Compressed Whisper Large v3 for faster processing.
  - name: Deepgram Nova 3
    description: Deepgram Nova 3 with VAD and speaker diarization.
  - name: Whisper Large v3
    description: Whisper Large v3 with 99+ language support.
components:
  schemas:
    SlngDeepgramNova3MultiRequest:
      allOf:
        - $ref: "#/components/schemas/SttAudioRequestBase"
        - $ref: "#/components/schemas/SlngDeepgramSttOptionsBase"
        - type: object
          properties:
            language:
              $ref: "#/components/schemas/SlngDeepgramNova3MultiLanguage"
    SlngDeepgramNova3MultiLanguage:
      type: string
      description: Supported language code. Nova 3 Multi auto-detects language; only `multi` is accepted.
      example: multi
      default: multi
      enum:
        - multi
    SlngDeepgramSttOptionsBase:
      type: object
      description: SLNG-hosted Deepgram STT processing options.
      properties:
        model:
          type: string
          description: Model name override.
          default: nova-3
        enable_partials:
          type: boolean
          description: Enable partial/interim transcription results for streaming.
          default: true
        punctuate:
          type: boolean
          description: Add punctuation and capitalization.
          default: false
        smart_format:
          type: boolean
          description: Apply formatting to improve readability (dates, times, numbers, etc.).
          default: false
        utterances:
          type: boolean
          description: Segment transcript into utterances.
          default: false
        paragraphs:
          type: boolean
          description: Add paragraph formatting.
          default: false
        numerals:
          type: boolean
          description: Convert spoken numbers to digits.
          default: false
        profanity_filter:
          type: boolean
          description: Filter profanity from transcript.
          default: false
        redact:
          type: array
          description: Redact sensitive information (pci, ssn, numbers).
          items:
            type: string
            enum:
              - pci
              - ssn
              - numbers
        detect_language:
          type: boolean
          description: Auto-detect spoken language.
          default: false
        filler_words:
          type: boolean
          description: Include filler words (uh, um) in transcript.
          default: false
        multichannel:
          type: boolean
          description: Enable multi-channel audio processing.
          default: false
        keywords:
          type: array
          description: Keywords to boost recognition accuracy.
          items:
            type: string
        encoding:
          type: string
          description: Input audio encoding.
          default: linear16
          enum:
            - linear16
            - flac
            - mulaw
            - amr-nb
            - amr-wb
            - opus
            - speex
            - mp3
            - mp4
            - webm
            - aac
            - ogg
        sample_rate:
          type: integer
          description: Input audio sample rate in Hz.
          default: 16000
        channels:
          type: integer
          description: Number of audio channels.
          minimum: 1
        endpointing:
          oneOf:
            - type: integer
              minimum: 0
            - type: boolean
          default: 10
          description: Time in milliseconds of silence before finalizing speech. Enabled by default at 10ms on Deepgram's side. Set to false to disable endpointing entirely.
        utterance_end_ms:
          type: integer
          minimum: 200
          maximum: 5000
          default: 1000
          description: Time in milliseconds of silence between words before sending an UtteranceEnd message. Default is 1000ms, minimum 200ms, maximum 5000ms. Requires interim_results (enable_partials) to be true.
        tag:
          type: string
          description: Tag for request tracking.
    SttAudioRequestBase:
      type: object
      properties:
        audio:
          type: string
          format: binary
          description: Audio file (multipart) or base64-encoded audio (JSON).
        url:
          type: string
          description: Publicly accessible audio URL.
          example: https://docs.slng.ai/audio/hello.wav
    SlngDeepgramNova3HiRequest:
      allOf:
        - $ref: "#/components/schemas/SttAudioRequestBase"
        - $ref: "#/components/schemas/SlngDeepgramSttOptionsBase"
        - type: object
          properties:
            language:
              $ref: "#/components/schemas/SlngDeepgramNova3HiLanguage"
    SlngDeepgramNova3HiLanguage:
      type: string
      description: Supported language codes for the Hindi variant.
      example: hi
      enum:
        - hi
        - en
    SlngDeepgramNova3TaRequest:
      allOf:
        - $ref: "#/components/schemas/SttAudioRequestBase"
        - $ref: "#/components/schemas/SlngDeepgramSttOptionsBase"
        - type: object
          properties:
            language:
              $ref: "#/components/schemas/SlngDeepgramNova3TaLanguage"
    SlngDeepgramNova3TaLanguage:
      type: string
      description: Supported language codes for the Tamil variant.
      example: ta
      enum:
        - ta
        - en
    SlngDeepgramNova3EsRequest:
      allOf:
        - $ref: "#/components/schemas/SttAudioRequestBase"
        - $ref: "#/components/schemas/SlngDeepgramSttOptionsBase"
        - type: object
          properties:
            language:
              $ref: "#/components/schemas/SlngDeepgramNova3EsLanguage"
    SlngDeepgramNova3EsLanguage:
      type: string
      description: Supported Spanish language code.
      example: es
      enum:
        - es
        - es-us
        - es-419
        - es-ar
        - es-mx
        - es-es
    ProviderErrorResponse:
      type: object
      description: |
        Provider error response. Contains error information from the upstream provider.
        Common errors include invalid speakers, unsupported languages, or malformed requests.
      properties:
        error:
          type: string
          description: Error type or category (e.g., "TTS service error", "Validation error").
          example: TTS service error
        status:
          type: number
          description: Original HTTP status code from the provider (may differ from gateway response code).
          example: 400
        details:
          type: string
          description: |
            Detailed error message from the provider. For TTS errors, this typically includes
            the specific validation failure (e.g., invalid speaker ID for the selected model/language).
          example: "Rime TTS API error: 400 Bad Request - Invalid argument: Invalid speaker: aurelie"
      required:
        - error
    DeepgramSttResponse:
      type: object
      description: 3rd Party Deepgram API response format.
      required:
        - results
      properties:
        results:
          type: object
          properties:
            channels:
              type: array
              items:
                type: object
                properties:
                  alternatives:
                    type: array
                    items:
                      type: object
                      properties:
                        transcript:
                          type: string
                        confidence:
                          type: number
                  detected_language:
                    type: string
        metadata:
          type: object
          properties:
            request_id:
              type: string
            model:
              type: string
    SlngDeepgramNova3EnRequest:
      allOf:
        - $ref: "#/components/schemas/SttAudioRequestBase"
        - $ref: "#/components/schemas/SlngDeepgramSttOptionsBase"
        - type: object
          properties:
            language:
              $ref: "#/components/schemas/SlngDeepgramNova3EnLanguage"
    SlngDeepgramNova3EnLanguage:
      type: string
      description: Supported English language code.
      example: en
      enum:
        - en
        - en-au
        - en-us
        - en-nz
        - en-gb
        - en-in
    WhisperErrorResponse:
      type: object
      description: Whisper-specific error response.
      properties:
        error:
          type: string
          description: Error message.
      required:
        - error
    WhisperTranscriptionResponse:
      type: object
      description: Whisper STT response format.
      required:
        - text
      properties:
        text:
          type: string
          description: Transcribed text.
        language:
          type: string
          description: Detected language code (may not be present in all variants).
    WhisperTranscriptionRequest:
      type: object
      description: Whisper transcription request. Provide either `audio` (multipart upload) or `url` (publicly accessible HTTPS URL).
      properties:
        audio:
          type: string
          format: binary
          description: "Audio file (multipart) or base64-encoded audio (JSON). Formats: mp3, mp4, mpeg, mpga, m4a, wav, webm. Max 25MB."
        url:
          type: string
          description: Publicly accessible audio URL.
          example: https://docs.slng.ai/audio/hello.wav
        language:
          $ref: "#/components/schemas/WhisperLanguageCode"
    WhisperLanguageCode:
      type: string
      description: ISO-639-1 language code. Auto-detected if not specified.
      example: en
      enum:
        - af
        - am
        - ar
        - as
        - az
        - ba
        - be
        - bg
        - bn
        - bo
        - br
        - bs
        - ca
        - cs
        - cy
        - da
        - de
        - el
        - en
        - es
        - et
        - eu
        - fa
        - fi
        - fo
        - fr
        - gl
        - gu
        - ha
        - haw
        - he
        - hi
        - hr
        - ht
        - hu
        - hy
        - id
        - is
        - it
        - ja
        - jw
        - ka
        - kk
        - km
        - kn
        - ko
        - la
        - lb
        - ln
        - lo
        - lt
        - lv
        - mg
        - mi
        - mk
        - ml
        - mn
        - mr
        - ms
        - mt
        - my
        - ne
        - nl
        - nn
        - no
        - oc
        - pa
        - pl
        - ps
        - pt
        - ro
        - ru
        - sa
        - sd
        - si
        - sk
        - sl
        - sn
        - so
        - sq
        - sr
        - su
        - sv
        - sw
        - ta
        - te
        - tg
        - th
        - tk
        - tl
        - tr
        - tt
        - uk
        - ur
        - uz
        - vi
        - yi
        - yo
        - zh
        - yue
  parameters:
    XWorldPartSlngNovaHi:
      name: X-World-Part-Override
      in: header
      required: false
      description: Target world part override. Auto-selected if not provided.
      schema:
        type: string
        enum:
          - ap
    XRegionSlngNovaHi:
      name: X-Region-Override
      in: header
      required: false
      description: Target region override. Auto-selected if not provided.
      schema:
        type: string
        enum:
          - asia-south1
    XWorldPartSlngNovaTa:
      name: X-World-Part-Override
      in: header
      required: false
      description: Target world part override. Auto-selected if not provided.
      schema:
        type: string
        enum:
          - ap
    XRegionSlngNovaTa:
      name: X-Region-Override
      in: header
      required: false
      description: Target region override. Auto-selected if not provided.
      schema:
        type: string
        enum:
          - ap-south-1
    XRegionSlngNovaEn:
      name: X-Region-Override
      in: header
      required: false
      description: Target region override. Auto-selected if not provided.
      schema:
        type: string
        enum:
          - asia-south1
          - australia-southeast1
          - us-east-1
    XRegionSlngNovaEs:
      name: X-Region-Override
      in: header
      required: false
      description: Target region override. Auto-selected if not provided.
      schema:
        type: string
        enum:
          - us-east-1
    XRegionSlngNovaMulti:
      name: X-Region-Override
      in: header
      required: false
      description: Target region override. Auto-selected if not provided.
      schema:
        type: string
        enum:
          - eu-north-1
    XWorldPartSlngWhisper:
      name: X-World-Part-Override
      in: header
      required: false
      description: Target world part override. Auto-selected if not provided.
      schema:
        type: string
        enum:
          - eu
  responses:
    ProviderInternalServerError:
      description: Internal server error from the provider.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProviderErrorResponse"
          examples:
            processing-error:
              summary: Processing error
              value:
                error: Service error
                details: Internal processing error
    ProviderPayloadTooLarge:
      description: Audio file exceeds size limit.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProviderErrorResponse"
    ProviderBadRequest:
      description: Bad request - invalid parameters provided.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProviderErrorResponse"
          examples:
            validation-error:
              summary: Validation error
              value:
                error: Validation error
                details: "Missing required field: text"
    SlngDeepgramSttSuccess:
      description: Transcription successful.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/DeepgramSttResponse"
          examples:
            basic:
              summary: Basic transcription
              value:
                results:
                  channels:
                    - alternatives:
                        - transcript: hello from sunny barcelona
                          confidence: 0.98
                metadata:
                  request_id: req-123
                  model: nova-3
    ProviderServiceUnavailable:
      description: Service unavailable.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProviderErrorResponse"
    WhisperInternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/WhisperErrorResponse"
          examples:
            processing-error:
              summary: Processing error
              value:
                error: Failed to process audio file
    WhisperPayloadTooLarge:
      description: Audio file exceeds 25MB limit.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/WhisperErrorResponse"
          examples:
            too-large:
              summary: File too large
              value:
                error: Audio file size exceeds maximum limit of 25MB
    ProviderUnauthorized:
      description: Invalid or missing API key.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProviderErrorResponse"
    WhisperBadRequest:
      description: Invalid or missing audio file.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/WhisperErrorResponse"
          examples:
            missing-audio:
              summary: Missing audio
              value:
                error: "Missing required field: audio"
    WhisperTranscriptionSuccess:
      description: Transcription successful.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/WhisperTranscriptionResponse"
          examples:
            english:
              summary: English transcription
              value:
                text: Hello, welcome to SLNG's speech-to-text API.
                language: en
            spanish:
              summary: Spanish transcription
              value:
                text: Hola, bienvenido a la API de texto a voz de SLNG.
                language: es
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        API key issued by SLNG. Pass as `Authorization: Bearer <token>`.