openapi: 3.0.3
info:
  title: SLNG Gateway API - Gradium TTS
  version: 0.1.0
  description: Real-time multilingual text-to-speech with streaming WebSocket and one-shot HTTP synthesis
  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/tts/gradium/tts:default:
    post:
      operationId: gradium/tts:default
      summary: Gradium TTS default
      description: Real-time multilingual text-to-speech with streaming WebSocket and one-shot HTTP synthesis
      tags:
        - Gradium TTS
      parameters:
        - $ref: "#/components/parameters/XRegionOverride"
      requestBody:
        $ref: "#/components/requestBodies/GradiumTtsDefaultRequestBody"
      responses:
        "200":
          description: Success
        "400":
          $ref: "#/components/responses/ProviderBadRequest"
        "401":
          $ref: "#/components/responses/ProviderUnauthorized"
        "500":
          $ref: "#/components/responses/ProviderInternalServerError"
        "503":
          $ref: "#/components/responses/ProviderServiceUnavailable"
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
  parameters:
    XRegionOverride:
      name: x-region
      in: header
      required: false
      description: Override the default region for this request.
      schema:
        type: string
  requestBodies:
    GradiumTtsDefaultRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/GradiumTtsDefaultRequest"
          examples:
            example1:
              summary: Basic synthesis
              value:
                text: Hello, this is a test of Gradium text to speech.
                voice_id: YTpq7expH9539ERJ
                output_format: wav
  schemas:
    GradiumTtsDefaultRequest:
      type: object
      properties:
        text:
          type: string
          minLength: 1
          description: Text to synthesize.
        voice_id:
          type: string
          description: Voice ID from the Gradium voice library or a custom voice ID.
        output_format:
          type: string
          description: Output audio format.
          enum:
            - wav
            - pcm
            - pcm_8000
            - pcm_16000
            - pcm_24000
            - opus
            - ulaw_8000
            - alaw_8000
          default: wav
        encoding:
          type: string
          description: SLNG normalized output audio encoding (WebSocket streaming).
          default: wav
          enum:
            - wav
            - linear16
            - pcm
            - opus
            - mulaw
            - alaw
        language:
          type: string
          description: Language hint for synthesis.
          default: en
          enum:
            - en
            - fr
            - de
            - es
            - pt
        temperature:
          type: number
          description: Sampling temperature (stability). Lower is more stable.
          minimum: 0
          maximum: 1.4
        only_audio:
          type: boolean
          description: HTTP only. When true, returns raw audio bytes instead of a JSON message stream.
          default: true
      required:
        - text
  responses:
    ProviderBadRequest:
      description: Bad request — invalid parameters.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    ProviderUnauthorized:
      description: Unauthorized — invalid or missing API key.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    ProviderInternalServerError:
      description: Internal server error.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string
    ProviderServiceUnavailable:
      description: Service temporarily unavailable.
      content:
        application/json:
          schema:
            type: object
            properties:
              error:
                type: string