openapi: 3.0.3
info:
  title: SLNG Gateway API - ElevenLabs TTS
  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/tts/elevenlabs/eleven:3:
    post:
      operationId: elevenlabs/eleven:3
      summary: ElevenLabs v3
      description: Synthesize speech using ElevenLabs Eleven v3 with premium voice quality.
      tags:
        - Eleven v3
      parameters:
        - $ref: "#/components/parameters/XWorldPartElevenLabsEleven3"
      requestBody:
        $ref: "#/components/requestBodies/ElevenLabsTtsRequestBody"
      responses:
        "200":
          $ref: "#/components/responses/ElevenLabsTtsSynthesisSuccess"
        "400":
          $ref: "#/components/responses/ProviderBadRequest"
        "401":
          $ref: "#/components/responses/ProviderUnauthorized"
        "500":
          $ref: "#/components/responses/ProviderInternalServerError"
        "503":
          $ref: "#/components/responses/ProviderServiceUnavailable"
  /v1/tts/elevenlabs/eleven-flash:2:
    post:
      operationId: elevenlabs/eleven-flash:2
      summary: ElevenLabs Flash v2
      description: Synthesize speech using ElevenLabs Flash v2 with ultra-low latency.
      tags:
        - Eleven Flash v2
      parameters:
        - $ref: "#/components/parameters/XWorldPartElevenLabsElevenFlash2"
      requestBody:
        $ref: "#/components/requestBodies/ElevenLabsTtsRequestBody"
      responses:
        "200":
          $ref: "#/components/responses/ElevenLabsTtsSynthesisSuccess"
        "400":
          $ref: "#/components/responses/ProviderBadRequest"
        "401":
          $ref: "#/components/responses/ProviderUnauthorized"
        "500":
          $ref: "#/components/responses/ProviderInternalServerError"
        "503":
          $ref: "#/components/responses/ProviderServiceUnavailable"
  /v1/tts/elevenlabs/eleven-flash:2.5:
    post:
      operationId: elevenlabs/eleven-flash:2.5
      summary: ElevenLabs Flash v2.5
      description: Synthesize speech using ElevenLabs Flash v2.5 with multilingual support.
      tags:
        - Eleven Flash v2.5
      parameters:
        - $ref: "#/components/parameters/XWorldPartElevenLabsFlash25"
      requestBody:
        $ref: "#/components/requestBodies/ElevenLabsTtsRequestBody"
      responses:
        "200":
          $ref: "#/components/responses/ElevenLabsTtsSynthesisSuccess"
        "400":
          $ref: "#/components/responses/ProviderBadRequest"
        "401":
          $ref: "#/components/responses/ProviderUnauthorized"
        "500":
          $ref: "#/components/responses/ProviderInternalServerError"
        "503":
          $ref: "#/components/responses/ProviderServiceUnavailable"
  /v1/tts/elevenlabs/eleven-multilingual:2:
    post:
      operationId: elevenlabs/eleven-multilingual:2
      summary: ElevenLabs Multilingual v2
      description: Synthesize speech using ElevenLabs Multilingual v2 with broad language support.
      tags:
        - Multilingual v2
      parameters:
        - $ref: "#/components/parameters/XWorldPartElevenLabsElevenMultilingual2"
      requestBody:
        $ref: "#/components/requestBodies/ElevenLabsTtsRequestBody"
      responses:
        "200":
          $ref: "#/components/responses/ElevenLabsTtsSynthesisSuccess"
        "400":
          $ref: "#/components/responses/ProviderBadRequest"
        "401":
          $ref: "#/components/responses/ProviderUnauthorized"
        "500":
          $ref: "#/components/responses/ProviderInternalServerError"
        "503":
          $ref: "#/components/responses/ProviderServiceUnavailable"
tags:
  - name: Eleven v3
    description: ElevenLabs Eleven v3 with premium voice quality.
  - name: Eleven Flash v2
    description: ElevenLabs Flash v2 with ultra-low latency.
  - name: Eleven Flash v2.5
    description: ElevenLabs Flash v2.5 with multilingual support.
  - name: Multilingual v2
    description: ElevenLabs Multilingual v2 with broad language support.
components:
  responses:
    ProviderServiceUnavailable:
      description: Service unavailable.
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ProviderErrorResponse"
    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
    ProviderUnauthorized:
      description: Invalid or missing API key.
      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"
    ElevenLabsTtsSynthesisSuccess:
      description: Synthesis successful. Returns binary audio in the codec specified by output_format.
      content:
        application/octet-stream:
          schema:
            $ref: "#/components/schemas/AudioBinary"
  schemas:
    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
    AudioBinary:
      type: string
      format: binary
      description: Binary audio data.
    ElevenLabsTtsRequest:
      allOf:
        - $ref: "#/components/schemas/TtsVoiceRequestBase"
        - type: object
          properties:
            language_code:
              allOf:
                - $ref: "#/components/schemas/ElevenLabsLanguage"
              description: Language code (ISO 639-1) used to enforce a language for the model and text normalization.
            voice_settings:
              $ref: "#/components/schemas/ElevenLabsVoiceSettings"
            seed:
              type: integer
              minimum: 0
              maximum: 4294967295
              description: If specified, our system will make a best effort to sample deterministically.
            previous_text:
              type: string
              description: The text that came before the text of the current request.
            next_text:
              type: string
              description: The text that comes after the text of the current request.
            previous_request_ids:
              type: array
              description: A list of request_id of the samples that were generated before this generation.
              items:
                type: string
              maxItems: 3
            next_request_ids:
              type: array
              description: A list of request_id of the samples that come after this generation.
              items:
                type: string
              maxItems: 3
            apply_text_normalization:
              type: string
              description: "This parameter controls text normalization with three modes: 'auto', 'on', and 'off'."
              enum:
                - auto
                - on
                - off
              default: auto
            apply_language_text_normalization:
              type: boolean
              description: This parameter controls language text normalization.
              default: false
            enable_logging:
              type: boolean
              description: Enable request logging. Set false for zero retention mode (enterprise only).
              default: true
      required:
        - text
    ElevenLabsVoiceSettings:
      type: object
      description: Voice settings overriding stored settings for the given voice.
      properties:
        stability:
          type: number
          minimum: 0
          maximum: 1
          description: Determines how stable the voice is and the randomness between each generation.
          default: 0.5
        similarity_boost:
          type: number
          minimum: 0
          maximum: 1
          description: Determines how closely the AI should adhere to the original voice.
          default: 0.75
        style:
          type: number
          minimum: 0
          maximum: 1
          description: Determines the style exaggeration of the voice.
          default: 0
        use_speaker_boost:
          type: boolean
          description: This setting boosts the similarity to the original speaker.
          default: true
        speed:
          type: number
          minimum: 0.7
          maximum: 1.2
          description: Adjusts the speed of the voice. A value of 1.0 is the default speed.
          default: 1
    ElevenLabsLanguage:
      type: string
      description: ISO 639-1 language code. Supported by multilingual models.
      enum:
        - ar
        - cs
        - de
        - en
        - es
        - fil
        - fr
        - hi
        - it
        - ja
        - nl
        - pl
        - pt
        - ro
        - sk
        - sv
        - tr
        - zh
      default: en
    TtsVoiceRequestBase:
      type: object
      properties:
        text:
          $ref: "#/components/schemas/TextToSynthesize"
        voice:
          type: string
          description: ElevenLabs voice ID (premade or custom from your library).
          default: pNInz6obpgDQGcFmaJgB
    TextToSynthesize:
      type: string
      minLength: 1
      description: The text that will get converted into speech.
  requestBodies:
    ElevenLabsTtsRequestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ElevenLabsTtsRequest"
          examples:
            basic:
              summary: Basic synthesis
              value:
                voice: pNInz6obpgDQGcFmaJgB
                text: Hello, this is a test of text to speech synthesis.
            with-voice-settings:
              summary: With custom voice settings
              value:
                voice: pNInz6obpgDQGcFmaJgB
                text: Hello, this is a test of text to speech synthesis.
                voice_settings:
                  stability: 0.7
                  similarity_boost: 0.8
                  style: 0.2
                  speed: 1.1
            continuity:
              summary: Request stitching for continuity
              value:
                voice: pNInz6obpgDQGcFmaJgB
                text: This is the second part of my speech.
                previous_text: This is the first part of my speech.
                next_text: And this is the third part.
  parameters:
    XWorldPartElevenLabsEleven3:
      name: X-World-Part-Override
      in: header
      required: false
      description: Target world part override. Auto-selected if not provided.
      schema:
        type: string
        enum:
          - eu
    XWorldPartElevenLabsElevenFlash2:
      name: X-World-Part-Override
      in: header
      required: false
      description: Target world part override. Auto-selected if not provided.
      schema:
        type: string
        enum:
          - eu
    XWorldPartElevenLabsElevenMultilingual2:
      name: X-World-Part-Override
      in: header
      required: false
      description: Target world part override. Auto-selected if not provided.
      schema:
        type: string
        enum:
          - eu
    XWorldPartElevenLabsFlash25:
      name: X-World-Part-Override
      in: header
      required: false
      description: Target world part override. Auto-selected if not provided.
      schema:
        type: string
        enum:
          - eu
          - ap
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        API key issued by SLNG. Pass as `Authorization: Bearer <token>`.