asyncapi: 3.0.0
info:
  title: SLNG Gateway API - Cartesia TTS
  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
    - name: Unmute STT Bridge
      description: SLNG native WebSocket STT protocol bridge.
    - name: Unmute TTS Bridge
      description: SLNG native WebSocket TTS protocol bridge.
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/tts/cartesia/sonic:3:
    address: /v1/tts/cartesia/sonic:3
    title: Cartesia Sonic 3
    summary: Cartesia Sonic 3
    description: Stream low-latency speech synthesis from Cartesia Sonic 3 over WebSocket with a multilingual catalog of voices and context-aware controls.
    tags:
      - name: Cartesia Sonic 3
    servers:
      - $ref: "#/servers/production"
      - $ref: "#/servers/staging"
    messages:
      CartesiaSonicTtsInitRequest:
        $ref: "#/components/messages/CartesiaSonicTtsInitRequest"
      CartesiaSonicTtsTextMessage:
        $ref: "#/components/messages/CartesiaSonicTtsTextMessage"
      TtsFlushMessage:
        $ref: "#/components/messages/TtsFlushMessage"
      TtsCancelMessage:
        $ref: "#/components/messages/TtsCancelMessage"
      TtsCloseMessage:
        $ref: "#/components/messages/TtsCloseMessage"
      KeepaliveMessage:
        $ref: "#/components/messages/KeepaliveMessage"
      CartesiaSonicTtsAudioChunk:
        $ref: "#/components/messages/CartesiaSonicTtsAudioChunk"
      TtsAudioEnd:
        $ref: "#/components/messages/TtsAudioEnd"
      TtsErrorResponse:
        $ref: "#/components/messages/TtsErrorResponse"
    bindings:
      ws:
        method: GET
        headers:
          $ref: "#/components/schemas/WebsocketHeadersCartesia"
operations:
  ttsCartesiaSonic3ReceiveInit:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1tts~1cartesia~1sonic:3"
    summary: Initialize session on Cartesia Sonic 3
    messages:
      - $ref: "#/channels/~1v1~1tts~1cartesia~1sonic:3/messages/CartesiaSonicTtsInitRequest"
    description: Initialize session on Cartesia Sonic 3
    tags: []
  ttsCartesiaSonic3ReceiveText:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1tts~1cartesia~1sonic:3"
    summary: Send text to Cartesia Sonic 3
    messages:
      - $ref: "#/channels/~1v1~1tts~1cartesia~1sonic:3/messages/CartesiaSonicTtsTextMessage"
    description: Send text to Cartesia Sonic 3
    tags: []
  ttsCartesiaSonic3ReceiveFlush:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1tts~1cartesia~1sonic:3"
    summary: Flush buffered output on Cartesia Sonic 3
    messages:
      - $ref: "#/channels/~1v1~1tts~1cartesia~1sonic:3/messages/TtsFlushMessage"
    description: "Manual boundary flush for the active Cartesia synthesis context. This does not finalize the context — to fully complete generation, send the last text message with `continue: false`."
    tags: []
  ttsCartesiaSonic3ReceiveCancel:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1tts~1cartesia~1sonic:3"
    summary: Cancel in-progress generation on Cartesia Sonic 3
    messages:
      - $ref: "#/channels/~1v1~1tts~1cartesia~1sonic:3/messages/TtsCancelMessage"
    description: Cancel an in-progress synthesis context on Cartesia Sonic 3. The gateway forwards a native Cartesia cancel for the supplied `context_id`, or the active session `context_id` when omitted. Cartesia recommends starting a new `context_id` for the next turn after a cancel.
    tags: []
  ttsCartesiaSonic3ReceiveClose:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1tts~1cartesia~1sonic:3"
    summary: Close session on Cartesia Sonic 3
    messages:
      - $ref: "#/channels/~1v1~1tts~1cartesia~1sonic:3/messages/TtsCloseMessage"
    description: Close session on Cartesia Sonic 3
    tags: []
  ttsCartesiaSonic3ReceiveKeepalive:
    action: receive
    channel:
      $ref: "#/channels/~1v1~1tts~1cartesia~1sonic:3"
    summary: Send keepalive on Cartesia Sonic 3
    messages:
      - $ref: "#/channels/~1v1~1tts~1cartesia~1sonic:3/messages/KeepaliveMessage"
    description: Send keepalive on Cartesia Sonic 3
    tags: []
  ttsCartesiaSonic3SendAudioChunk:
    action: send
    channel:
      $ref: "#/channels/~1v1~1tts~1cartesia~1sonic:3"
    summary: Receive audio chunk from Cartesia Sonic 3
    messages:
      - $ref: "#/channels/~1v1~1tts~1cartesia~1sonic:3/messages/CartesiaSonicTtsAudioChunk"
    description: Receive streaming audio chunk from Cartesia Sonic 3.
    tags: []
  ttsCartesiaSonic3SendAudioEnd:
    action: send
    channel:
      $ref: "#/channels/~1v1~1tts~1cartesia~1sonic:3"
    summary: Receive audio end from Cartesia Sonic 3
    messages:
      - $ref: "#/channels/~1v1~1tts~1cartesia~1sonic:3/messages/TtsAudioEnd"
    description: Receive audio end signal from Cartesia Sonic 3.
    tags: []
  ttsCartesiaSonic3SendError:
    action: send
    channel:
      $ref: "#/channels/~1v1~1tts~1cartesia~1sonic:3"
    summary: Receive error from Cartesia Sonic 3
    messages:
      - $ref: "#/channels/~1v1~1tts~1cartesia~1sonic:3/messages/TtsErrorResponse"
    description: Receive error from Cartesia Sonic 3.
    tags: []
components:
  schemas:
    WebsocketHeadersCartesia:
      type: object
      properties:
        X-World-Part-Override:
          type: string
          description: "Target world part override. Auto-selected if not provided. Available world parts: `ap`, `eu`, `na`."
          enum:
            - ap
            - eu
            - na
  messages:
    CartesiaSonicTtsInitRequest:
      name: CartesiaSonicTtsInitRequest
      title: Init Request (Cartesia Sonic 3)
      summary: Initialize a Cartesia Sonic 3 TTS session with provider-specific configuration.
      contentType: application/json
      payload:
        type: object
        description: Initialize a Cartesia Sonic 3 TTS session with voice, language, and audio format options. Fields set here are applied for the session unless overridden per text message.
        required:
          - type
        properties:
          type:
            type: string
            const: init
            default: init
          model_id:
            type: string
            description: Cartesia Sonic model identifier.
            enum:
              - sonic-3
            default: sonic-3
          voice:
            type: string
            description: Cartesia voice identifier.
            default: f786b574-daa5-4673-aa0c-cbe3e8534c02
          language:
            type: string
            description: Optional language override for supported Sonic 3 voices.
          encoding:
            type: string
            description: Output audio encoding format.
            enum:
              - linear16
              - mulaw
              - ulaw
              - alaw
            default: linear16
          sample_rate:
            type: integer
            description: Output audio sample rate in Hz.
            enum:
              - 8000
              - 16000
              - 24000
              - 44100
            default: 24000
          context_id:
            type: string
            description: Optional synthesis context identifier. If omitted, the gateway generates one per WebSocket session.
      examples:
        - name: cartesiaSonicInitBasic
          summary: Initialize a Cartesia Sonic 3 session with defaults
          payload:
            type: init
            model_id: sonic-3
            voice: f786b574-daa5-4673-aa0c-cbe3e8534c02
            encoding: linear16
            sample_rate: 24000
        - name: cartesiaSonicInitTelephony
          summary: Initialize for telephony audio (8kHz mulaw) with Spanish voice
          payload:
            type: init
            model_id: sonic-3
            voice: f786b574-daa5-4673-aa0c-cbe3e8534c02
            language: es
            encoding: ulaw
            sample_rate: 8000
            context_id: demo-context-123
    CartesiaSonicTtsTextMessage:
      name: CartesiaSonicTtsTextMessage
      title: Text Message (Cartesia Sonic 3)
      summary: Send text to synthesize on Cartesia Sonic 3 with optional generation controls.
      contentType: application/json
      payload:
        type: object
        description: Send text to synthesize into audio output using Cartesia Sonic 3. Supports per-utterance generation controls including speed, volume, emotion, and manual flushing.
        required:
          - type
          - text
        properties:
          type:
            type: string
            const: text
          text:
            type: string
            minLength: 1
            description: Text to synthesize.
          voice:
            type: string
            description: Override the Cartesia voice identifier for this utterance.
          generation_config:
            type: object
            description: Optional Sonic 3 generation controls such as speed, volume, and emotion.
            properties:
              speed:
                type: number
                minimum: 0.6
                maximum: 1.5
                description: Sonic 3 speed multiplier guidance.
              volume:
                type: number
                minimum: 0.5
                maximum: 2
                description: Sonic 3 volume multiplier guidance.
              emotion:
                type: string
                description: Sonic 3 emotional guidance.
          speed:
            type: string
            description: Deprecated Cartesia speed override. Prefer `generation_config.speed` for Sonic 3. Ignored when `generation_config` is provided.
            enum:
              - slow
              - normal
              - fast
          continue:
            type: boolean
            description: Whether more text inputs may follow on the same `context_id`. When `true`, Cartesia keeps the context open and waits. When `false` or omitted, this is the final input — Cartesia emits the trailing audio and then `audio_end`.
          max_buffer_delay_ms:
            type: integer
            minimum: 0
            maximum: 5000
            description: Maximum time, in milliseconds, that Cartesia buffers incoming text before starting generation. Use it to group several quick `text` inputs into a single synthesis pass — the longer the delay, the more text Cartesia can combine. Omit or set `0` to generate as soon as the first text input arrives.
          add_timestamps:
            type: boolean
            description: Whether Cartesia should emit timestamp events for this generation.
          flush:
            type: boolean
            description: "Marks a segment boundary within the active context. Not required to receive audio — Cartesia begins generating as soon as text arrives. Sending `flush: true` increments the `flush_id` that Cartesia includes on subsequent `audio_chunk` frames so you can correlate audio back to the text segment that produced it. Does not finalize the context; complete generation by sending the final input with `continue: false`."
          pronunciation_dict_id:
            type: string
            description: Optional pronunciation dictionary applied to this generation only.
          context_id:
            type: string
            description: Optional synthesis context identifier. If omitted, the gateway uses the active session context_id.
      examples:
        - name: cartesiaSonicTextBasic
          summary: Basic streaming synthesis
          payload:
            type: text
            text: Hello, this is Cartesia Sonic 3.
        - name: cartesiaSonicTextWithControls
          summary: Streaming synthesis with generation controls
          payload:
            type: text
            text: Hola desde Barcelona con velocidad ajustada.
            generation_config:
              speed: 1.15
              volume: 1.05
              emotion: curious
            continue: true
            max_buffer_delay_ms: 500
            add_timestamps: true
            context_id: demo-context-123
        - name: cartesiaSonicTextBufferedFirstSegment
          summary: Buffered stream — first segment (continue=true, no flush)
          payload:
            type: text
            text: "Hello from Barcelona, "
            continue: true
            context_id: demo-context-456
        - name: cartesiaSonicTextBufferedMidSegment
          summary: Buffered stream — middle segment (continue=true, flush=true marks a flush_id boundary)
          payload:
            type: text
            text: "where the sun is shining and the tapas are warm. "
            continue: true
            flush: true
            context_id: demo-context-456
        - name: cartesiaSonicTextBufferedFinalSegment
          summary: Buffered stream — final segment (continue=false finalizes the context and triggers audio_end)
          payload:
            type: text
            text: Wish you were here.
            continue: false
            context_id: demo-context-456
    TtsFlushMessage:
      name: TtsFlushMessage
      title: Flush Message
      summary: Standalone segment boundary on the active Cartesia Sonic 3 context.
      contentType: application/json
      payload:
        type: object
        description: "Standalone segment boundary on the active context. Has the same effect as setting `flush: true` on a `text` input: it increments `flush_id` and does not finalize the context. Complete generation by sending the final `text` input with `continue: false`."
        required:
          - type
        properties:
          type:
            type: string
            const: flush
      examples:
        - name: flush
          summary: Flush buffered audio
          payload:
            type: flush
    TtsCancelMessage:
      name: TtsCancelMessage
      title: Cancel Message
      summary: Cancel an in-progress Cartesia Sonic 3 synthesis context.
      contentType: application/json
      payload:
        type: object
        description: "Cancel an in-progress Cartesia synthesis context. The gateway forwards a native `{ context_id, cancel: true }` frame to Cartesia. When `context_id` is omitted, the active session context is cancelled. Cartesia recommends starting a new `context_id` for the next turn after a cancel."
        required:
          - type
        properties:
          type:
            type: string
            const: cancel
          context_id:
            type: string
            description: Optional context identifier to cancel. If omitted, the gateway cancels the active session context_id.
      examples:
        - name: cancel
          summary: Cancel the active synthesis context
          payload:
            type: cancel
        - name: cancelWithContext
          summary: Cancel a specific synthesis context
          payload:
            type: cancel
            context_id: demo-context-123
    TtsCloseMessage:
      name: TtsCloseMessage
      title: Close Message
      summary: Close the session and stop any further audio.
      contentType: application/json
      payload:
        type: object
        description: Close the session and stop any further audio.
        required:
          - type
        properties:
          type:
            type: string
            const: close
      examples:
        - name: close
          summary: Close the session
          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
    CartesiaSonicTtsAudioChunk:
      name: CartesiaSonicTtsAudioChunk
      title: Audio Chunk (Cartesia Sonic 3)
      summary: Streaming audio chunk from Cartesia Sonic 3.
      contentType: application/json
      payload:
        type: object
        description: Streaming audio chunk emitted by Cartesia Sonic 3. The gateway forwards each upstream `chunk` message as an `audio_chunk`, preserving Cartesia's native fields.
        required:
          - type
          - data
        properties:
          type:
            type: string
            const: audio_chunk
          data:
            type: string
            format: byte
            description: Base64-encoded audio chunk matching the requested encoding and sample rate.
          done:
            type: boolean
            description: True when this is the final chunk of the active context.
          status_code:
            type: integer
            description: Upstream HTTP-equivalent status code from Cartesia.
          step_time:
            type: number
            description: Cartesia processing time for this chunk, in milliseconds.
          flush_id:
            type: integer
            description: "Segment identifier within the active context. Starts at `0` and increments by `1` each time a `text` input is sent with `flush: true`, or whenever a standalone flush message is issued. Use it to correlate audio chunks back to the text segment that produced them."
          context_id:
            type: string
            description: Synthesis context identifier this chunk belongs to.
      examples:
        - name: cartesiaSonicAudioChunk
          summary: Receive an audio chunk
          payload:
            type: audio_chunk
            context_id: 9baf38d7-799e-40f2-88d1-daeacbdb3910
            status_code: 206
            done: false
            data: AAF+/dD7n/wj/rD/owGoBEQHBgjTBcoDjAITAk0BtwF0BFUI5wmlB7cEAgO3ArIBUwB0AJwDDQbQBacCEgDA/vD96vxr/H3+hwAqASr/Z/3C/BEAEQAUAA==
            step_time: 67.49622
            flush_id: 0
    TtsAudioEnd:
      name: TtsAudioEnd
      title: Audio End
      summary: Signals the end of audio generation.
      contentType: application/json
      payload:
        type: object
        description: Signals the end of audio generation for the active context. The gateway maps the upstream Cartesia `done` message to `audio_end`, preserving Cartesia's native fields.
        required:
          - type
        properties:
          type:
            type: string
            const: audio_end
          done:
            type: boolean
            description: Always `true` on Cartesia generation-complete frames.
          status_code:
            type: integer
            description: Upstream HTTP-equivalent status code from Cartesia.
          context_id:
            type: string
            description: Synthesis context identifier that finished generation.
      examples:
        - name: audioEnd
          summary: Audio generation complete
          payload:
            type: audio_end
            context_id: 9baf38d7-799e-40f2-88d1-daeacbdb3910
            status_code: 200
            done: true
    TtsErrorResponse:
      name: TtsErrorResponse
      title: Error Response
      summary: Indicates an error occurred during synthesis.
      contentType: application/json
      payload:
        type: object
        description: Indicates an error occurred during synthesis. The gateway surfaces upstream Cartesia error messages with the original status code, provider-specific error code, and supporting metadata.
        required:
          - type
          - message
        properties:
          type:
            type: string
            const: error
          message:
            type: string
            description: Human-readable error description.
          title:
            type: string
            description: Short error title from the upstream provider.
          status_code:
            type: integer
            description: Upstream HTTP-equivalent status code.
          error_code:
            type:
              - string
              - "null"
            description: Provider-specific error code, when available.
          done:
            type: boolean
            description: True when the upstream marked the context as terminated by this error.
          request_id:
            type: string
            description: Cartesia request identifier, useful when contacting support.
          doc_url:
            type: string
            description: Cartesia documentation link for this error class, when provided.
          context_id:
            type: string
            description: Synthesis context identifier associated with the error.
      examples:
        - name: ttsError
          summary: Provider error surfaced through the gateway
          payload:
            type: error
            message: Provider returned an unexpected error
            status_code: 500
            error_code: provider_error
            done: true
            request_id: req-9b1c2f
            doc_url: https://docs.cartesia.ai/errors/provider_error
            context_id: demo-context-123
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: |
        API key issued by SLNG. Pass as `Authorization: Bearer <token>` in the WebSocket upgrade request headers.