SLNG Rime Arcana v3 API

openapi: 3.2.0
info:
  title: SLNG Gateway API - SLNG TTS Rime Arcana v3 API
  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: []
tags:
- name: Rime Arcana v3
  description: Rime Arcana v3 TTS with multilingual support (English, Hindi).
paths:
  /v1/tts/slng/rime/arcana:3-en:
    post:
      operationId: rime/arcana:3-en
      summary: Arcana v3 (English)
      description: Synthesize English speech using Rime Arcana v3 TTS model.
      tags:
      - Rime Arcana v3
      parameters:
      - $ref: '#/components/parameters/XRegionSlngArcanaV3En'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RimeArcana3TtsRequestEn'
            examples:
              basic:
                summary: Basic English synthesis
                value:
                  text: Hello from Rime Arcana v3 English. Testing text to speech synthesis.
                  speaker: astra
      responses:
        '200':
          $ref: '#/components/responses/TtsSynthesisSuccess'
        '400':
          $ref: '#/components/responses/RimeArcanaBadRequest'
        '401':
          $ref: '#/components/responses/ProviderUnauthorized'
        '500':
          $ref: '#/components/responses/RimeArcanaInternalServerError'
        '503':
          $ref: '#/components/responses/ProviderServiceUnavailable'
  /v1/tts/slng/rime/arcana:3-es:
    post:
      operationId: rime/arcana:3-es
      summary: Arcana v3 (Spanish)
      description: Synthesize Spanish speech using Rime Arcana v3 TTS model.
      tags:
      - Rime Arcana v3
      parameters:
      - $ref: '#/components/parameters/XRegionSlngArcanaV3Es'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RimeArcana3TtsRequestEs'
            examples:
              basic:
                summary: Basic Spanish synthesis
                value:
                  text: Hola desde Rime Arcana v3 Español. Probando la síntesis de texto a voz.
                  speaker: seraphina
      responses:
        '200':
          $ref: '#/components/responses/TtsSynthesisSuccess'
        '400':
          $ref: '#/components/responses/RimeArcanaBadRequest'
        '401':
          $ref: '#/components/responses/ProviderUnauthorized'
        '500':
          $ref: '#/components/responses/RimeArcanaInternalServerError'
        '503':
          $ref: '#/components/responses/ProviderServiceUnavailable'
  /v1/tts/slng/rime/arcana:3-hi:
    post:
      operationId: rime/arcana:3-hi
      summary: Arcana v3 (Hindi)
      description: Synthesize Hindi speech using Rime Arcana v3 TTS model.
      tags:
      - Rime Arcana v3
      parameters:
      - $ref: '#/components/parameters/XRegionSlngArcanaV3Hi'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RimeArcana3TtsRequestHi'
            examples:
              basic:
                summary: Basic Hindi synthesis
                value:
                  text: नमस्ते Rime Arcana v3 हिंदी से। टेक्स्ट टू स्पीच सिंथेसिस का परीक्षण।
                  speaker: astra
      responses:
        '200':
          $ref: '#/components/responses/TtsSynthesisSuccess'
        '400':
          $ref: '#/components/responses/RimeArcanaBadRequest'
        '401':
          $ref: '#/components/responses/ProviderUnauthorized'
        '500':
          $ref: '#/components/responses/RimeArcanaInternalServerError'
        '503':
          $ref: '#/components/responses/ProviderServiceUnavailable'
  /v1/tts/slng/rime/arcana:3-fr:
    post:
      operationId: rime/arcana:3-fr
      summary: Arcana v3 (French)
      description: Synthesize French speech using Rime Arcana v3 TTS model.
      tags:
      - Rime Arcana v3
      parameters:
      - $ref: '#/components/parameters/XRegionSlngArcanaV3Fr'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RimeArcana3TtsRequestFr'
            examples:
              basic:
                summary: Basic French synthesis
                value:
                  text: Bonjour depuis Rime Arcana v3 Français. Test de la synthèse vocale.
                  speaker: livet_aurelie
      responses:
        '200':
          $ref: '#/components/responses/TtsSynthesisSuccess'
        '400':
          $ref: '#/components/responses/RimeArcanaBadRequest'
        '401':
          $ref: '#/components/responses/ProviderUnauthorized'
        '500':
          $ref: '#/components/responses/RimeArcanaInternalServerError'
        '503':
          $ref: '#/components/responses/ProviderServiceUnavailable'
components:
  schemas:
    AudioBinary:
      type: string
      format: binary
      description: Binary audio data.
    RimeArcanaSpeakerFr:
      type: string
      description: Voice speaker ID (French voices).
      default: livet_aurelie
      enum:
      - destin
      - livet_aurelie
      - morel_marianne
      - serrin_joseph
      - solstice
    RimeArcana3TtsRequestFr:
      description: Rime Arcana v3 TTS request for French.
      type: object
      required:
      - speaker
      properties:
        speaker:
          $ref: '#/components/schemas/RimeArcanaSpeakerFr'
        modelId:
          type: string
          default: arcana-3
          description: Rime Arcana v3 model identifier.
        language:
          type: string
          enum:
          - fr
          default: fr
          description: Language code.
      allOf:
      - $ref: '#/components/schemas/RimeArcanaTtsRequestCommon'
    RimeArcana3TtsRequestEs:
      description: Rime Arcana v3 TTS request for Spanish.
      type: object
      required:
      - speaker
      properties:
        speaker:
          $ref: '#/components/schemas/RimeArcana3SpeakerEs'
        modelId:
          type: string
          default: arcana-3
          description: Rime Arcana v3 model identifier.
        language:
          type: string
          enum:
          - es
          default: es
          description: Language code.
      allOf:
      - $ref: '#/components/schemas/RimeArcanaTtsRequestCommon'
    RimeArcana3Speaker:
      type: string
      description: Voice speaker ID for Rime Arcana v3. Multilingual speakers supporting all languages.
      default: astra
      enum:
      - ahmed_mohamed
      - akari
      - albion
      - alfhild
      - alzira
      - amarante
      - anaya
      - andersen_johan
      - anderson_emily
      - anderson_jake
      - anderson_james
      - anderson_kevin
      - andromeda
      - anil
      - arcade
      - arya
      - astra
      - atrium
      - aurelie
      - aurelio
      - aurélie
      - aviva
      - baldur
      - baltasar
      - batin
      - bauer_felix
      - bennett_emily
      - bennett_ryan
      - biondi_paul
      - bond
      - brooks_jordan
      - brown_alex
      - brown_joshua
      - brown_liam
      - brown_madison
      - brown_matthew
      - brown_sophia
      - brown_steven
      - brunetti_tony
      - bruno_katie
      - carter_colin
      - celeste
      - celestino
      - celso
      - chatterjee_rini
      - chen_david
      - chen_mei
      - clark_tyler
      - cohen_emily
      - cohen_jared
      - collins_emily
      - cooper_logan
      - cupola
      - das_sourav
      - davies_james
      - dela cruz_maria
      - dela_cristina
      - destin
      - diallo_amara
      - dubois_emma
      - duncan_colin
      - duval_pierre
      - eliphas
      - estela
      - estelle
      - esther
      - eucalyptus
      - evans_jason
      - fadil
      - fern
      - fernandez_carlos
      - freya
      - goldberg_ryan
      - gomez_daniela
      - gomez_diego
      - gomez_isabel
      - gomez_isabella
      - gomez_javon
      - gonzalez_maya
      - gonzalez_michael
      - gonzalez_ryan
      - grayson_avery
      - hanson_ryan
      - harris_luke
      - harris_lynette
      - harrison_brianna
      - harrison_joey
      - harrison_mary
      - hassan_omar
      - henderson_brittney
      - hernandez_juanita
      - holliday_jewel
      - isadora
      - iyer_arun
      - jensen_mikkel
      - johnny_jackson
      - johnson_amber
      - johnson_angela
      - johnson_asha
      - johnson_avery
      - johnson_brianna
      - johnson_cynthia
      - johnson_elijah
      - johnson_james
      - johnson_jessica
      - johnson_joshua
      - johnson_latisha
      - johnson_lisa
      - johnson_madison
      - johnson_malachi
      - johnson_marcel
      - johnson_mary
      - johnson_matt
      - johnson_matthew
      - johnson_melissa
      - johnson_monique
      - johnson_nia
      - johnson_tasha
      - johnson_tia
      - johnson_walter
      - kelly_aoife
      - kelly_jennifer
      - kelly_john
      - kelly_maureen
      - khan_fatima
      - khan_umar
      - kim_ashley
      - kim_daniel
      - kim_jaehyun
      - kim_sunny
      - kima
      - lark
      - layla
      - lee_sarah
      - levi_david
      - levine_emily
      - levine_joshua
      - levy_hannah
      - li_michael
      - li_wei
      - li_xiao
      - liesel
      - lintel
      - livet_aurelie
      - lorelei
      - lucia
      - luna
      - luz
      - lyra
      - lúcia
      - maddox_emily
      - maguire_jason
      - malik_ahmad
      - mar
      - marinelli_giulia
      - marlu
      - martinez_amber
      - martinez_ana
      - martinez_dylan
      - martinez_jaime
      - martinez_leticia
      - martinez_rosa
      - martinez_ryan
      - masonry
      - mbunda_james
      - mccarthy_james
      - mccarthy_teresa
      - mcdowell_peter
      - mckinley_robert
      - mendoza_alonzo
      - mendoza_jesus
      - mendoza_luz
      - merritt_jimmy
      - miller_cameron
      - miller_dylan
      - miller_judy
      - miller_kelsey
      - miller_lisa
      - miller_logan
      - miyamoto_akari
      - montgomery_elise
      - montgomery_emily
      - morel_marianne
      - morgan_brianna
      - morgan_charles
      - morgan_jeremy
      - morris_colin
      - morris_james
      - morris_leticia
      - morris_melvin
      - morton_daine
      - moss
      - moyo_david
      - murphy_colin
      - murphy_emily
      - murphy_grace
      - murphy_hannah
      - murphy_liam
      - murphy_nolan
      - murphy_sean
      - neal_colin
      - noa
      - nova
      - novak_emily
      - nowak_joanna
      - nowak_michal
      - nozomi
      - o'connor_brian
      - oculus
      - olsson_erik
      - ori
      - orion
      - parapet
      - park_minseo
      - park_somin
      - park_sumin
      - parker_chloe
      - patel_amit
      - patel_asha
      - pham_daniel
      - pilaster
      - pola
      - qadir
      - raiden
      - ramirez_maya
      - ramos_raul
      - reddy_arjun
      - reddy_sunil
      - ren
      - ricci_giulia
      - ricci_lorenzo
      - rodrigues_miguel
      - rodriguez_carla
      - rodriguez_carlos
      - rodriguez_eduardo
      - rodriguez_isabela
      - rodriguez_miguel
      - rosenfeld_steffi
      - rossi_matteo
      - runa
      - sai
      - sakina
      - sakura
      - salik
      - santos_angelica
      - schmidt_joshua
      - schmidt_julia
      - schmidt_sophie
      - schneider_eric
      - schneider_jack
      - seraphina
      - seraphine
      - shai
      - sharma_amit
      - silva_ana
      - singh_anjali
      - sirius
      - smith_heather
      - smith_lisa
      - smith_michael
      - smith_mike
      - sol
      - solstice
      - stucco
      - séraphine
      - taru
      - tauro
      - thalassa
      - thomas_sarah
      - thompson_kevin
      - torres_miguel
      - tran_david
      - tran_jessica
      - tran_tu
      - transom
      - truss
      - tupou_leilani
      - ursa
      - vashti
      - vespera
      - violette
      - walnut
      - wang_mei
      - watson_emily
      - williams_anna
      - williams_brian
      - williams_darnell
      - williams_jennifer
      - williams_jordan
      - williams_nathan
      - williams_ryan
      - williams_terence
      - williams_tiffany
      - wilson_emma
      - wong_kenny
      - wright_cooper
      - wright_jason
      - wright_julianne
      - wright_michael
      - yukiko
      - zahir
      - zhang_mei
    RimeArcana3TtsRequestHi:
      description: Rime Arcana v3 TTS request for Hindi.
      allOf:
      - $ref: '#/components/schemas/RimeArcana3TtsRequestBase'
    RimeArcanaSampleRate:
      type: integer
      description: Output sample rate in Hz. Values above 24000 are upsampled.
      default: 24000
      enum:
      - 8000
      - 16000
      - 22050
      - 24000
      - 44100
      - 48000
      - 96000
    RimeArcanaAudioFormat:
      type: string
      description: Output audio format as MIME type.
      enum:
      - audio/webm;codecs=opus
      - audio/ogg;codecs=opus
      - audio/mp3
      - audio/wav
      - audio/pcm
      - audio/x-mulaw
      default: audio/wav
    RimeArcana3SpeakerEs:
      type: string
      description: Voice speaker ID for Rime Arcana v3 Spanish.
      default: seraphina
      enum:
      - aurelio
      - celestino
      - lark
      - luz
      - mar
      - nova
      - pola
      - seraphina
      - sirius
      - ursa
    RimeArcana3TtsRequestEn:
      description: Rime Arcana v3 TTS request for English.
      allOf:
      - $ref: '#/components/schemas/RimeArcana3TtsRequestBase'
    RimeArcana3TtsRequestBase:
      description: Base schema for Rime Arcana v3 TTS requests.
      allOf:
      - type: object
        required:
        - speaker
        properties:
          speaker:
            $ref: '#/components/schemas/RimeArcana3Speaker'
      - $ref: '#/components/schemas/RimeArcanaTtsRequestCommon'
    RimeArcanaModelId:
      type: string
      description: 'Model: arcana (most realistic, ~150ms), mistv2 (speed & control, ~70ms).'
      enum:
      - arcana
      - arcana-3
      - mistv2
      - mist
      default: arcana
    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
    RimeArcanaTtsRequestCommon:
      type: object
      description: Common Rime Arcana TTS options.
      properties:
        text:
          type: string
          minLength: 1
          description: Text to synthesize.
        modelId:
          $ref: '#/components/schemas/RimeArcanaModelId'
        repetition_penalty:
          type: number
          format: float
          default: 1.5
          description: The repetition penalty. We do not recommend changing this from the default value. Typical range is 1 to 2. Float that penalizes new tokens based on whether they appear in the prompt and the generated text so far. Values > 1 encourage the model to use new tokens, while values < 1 encourage the model to repeat tokens.
        temperature:
          type: number
          format: float
          default: 0.5
          description: The temperature. We do not recommend changing this from the default value. Typical range is 0 to 1. Float that controls the randomness of the sampling. Lower values make the model more deterministic, while higher values make the model more random. Zero means greedy sampling.
        top_p:
          type: number
          format: float
          default: 1
          description: The top p. We do not recommend changing this from the default value. Typical range is 0 to 1. Float that controls the cumulative probability of the top tokens to consider. Must be in (0, 1]. Set to 1 to consider all tokens.
        audioFormat:
          $ref: '#/components/schemas/RimeArcanaAudioFormat'
        sample_rate:
          $ref: '#/components/schemas/RimeArcanaSampleRate'
        speed:
          type: number
          description: Speech rate multiplier (0.25 = half speed, 2.0 = double speed).
          minimum: 0.25
          maximum: 2
          default: 1
      required:
      - text
  parameters:
    XRegionSlngArcanaV3Hi:
      name: X-Region-Override
      in: header
      required: false
      description: Target region override. Auto-selected if not provided.
      schema:
        type: string
        enum:
        - ap-southeast-2
        - eu-north-1
    XRegionSlngArcanaV3Fr:
      name: X-Region-Override
      in: header
      required: false
      description: Target region override. Auto-selected if not provided.
      schema:
        type: string
        enum:
        - eu-north-1
    XRegionSlngArcanaV3Es:
      name: X-Region-Override
      in: header
      required: false
      description: Target region override. Auto-selected if not provided.
      schema:
        type: string
        enum:
        - eu-north-1
    XRegionSlngArcanaV3En:
      name: X-Region-Override
      in: header
      required: false
      description: Target region override. Auto-selected if not provided.
      schema:
        type: string
        enum:
        - ap-southeast-2
        - asia-south1
        - eu-north-1
  responses:
    RimeArcanaBadRequest:
      description: 'Rime Arcana TTS bad request. Common causes include invalid speaker ID for the

        selected language variant, unsupported model, unsupported audio format, or malformed request body.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProviderErrorResponse'
          examples:
            invalid-speaker:
              summary: Invalid speaker ID
              description: 'Speaker ID not available for this language variant. Each Arcana language

                has specific voices - check the endpoint schema for valid speakers.

                '
              value:
                error: TTS service error
                details: 'Rime TTS API error: 400 Bad Request - Invalid argument: Invalid speaker: aurelie'
            invalid-speaker-for-language:
              summary: Speaker not available for language
              description: Using a speaker from a different language variant.
              value:
                error: TTS service error
                details: 'Rime TTS API error: 400 Bad Request - Invalid argument: Invalid speaker: astra'
            missing-text:
              summary: Missing text field
              value:
                error: Validation error
                details: 'Missing required field: text'
            unsupported-model:
              summary: Unsupported model
              description: The specified modelId is not supported by Rime Arcana.
              value:
                error: TTS service error
                details: 'Rime TTS API error: 400 Bad Request - Unsupported model'
    ProviderServiceUnavailable:
      description: Service unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProviderErrorResponse'
    TtsSynthesisSuccess:
      description: Synthesis successful.
      content:
        audio/*:
          schema:
            $ref: '#/components/schemas/AudioBinary'
    RimeArcanaInternalServerError:
      description: 'Rime Arcana TTS internal error. Note: Some validation errors (e.g., invalid speaker)

        may currently return 500 instead of 400. Check the error details for specifics.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProviderErrorResponse'
          examples:
            processing-error:
              summary: Processing error
              value:
                error: TTS service error
                details: Internal processing error
            invalid-speaker-as-500:
              summary: Invalid speaker (returned as 500)
              description: 'Invalid speaker errors may currently return 500 instead of 400.

                The details field will indicate the actual validation error.

                '
              value:
                error: TTS service error
                details: 'Rime TTS API error: 400 Bad Request - Invalid argument: Invalid speaker: aurelie'
    ProviderUnauthorized:
      description: Invalid or missing API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ProviderErrorResponse'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'API key issued by SLNG. Pass as `Authorization: Bearer <token>`.

        '