asyncapi: 3.0.0
info:
  title: Gradium Speech Streaming API
  version: '1.0.0'
  description: >-
    AsyncAPI capture of Gradium's real-time speech WebSocket surface (TTS, STT, and
    Speech-to-Speech). Generated by API Evangelist from the documented WebSocket
    lifecycle and message shapes — Gradium does not publish an AsyncAPI document.
    Message payloads and close codes are grounded in the Gradium docs; refine against
    the live protocol before production use.
  x-apievangelist-method: generated
  x-apievangelist-source: >-
    https://docs.gradium.ai/guides/websocket-lifecycle,
    https://docs.gradium.ai/guides/browser-websockets,
    https://docs.gradium.ai/guides/errors
servers:
  production:
    host: api.gradium.ai
    pathname: /api
    protocol: wss
    description: Gradium real-time WebSocket API. Auth via x-api-key (server) or ?token= (browser short-lived token).
channels:
  tts:
    address: /speech/tts
    description: Text-to-Speech streaming — send text, receive audio chunks.
    messages:
      setup: { $ref: '#/components/messages/Setup' }
      text: { $ref: '#/components/messages/TextInput' }
      flush: { $ref: '#/components/messages/Flush' }
      endOfStream: { $ref: '#/components/messages/EndOfStream' }
      ready: { $ref: '#/components/messages/Ready' }
      audio: { $ref: '#/components/messages/AudioOutput' }
      error: { $ref: '#/components/messages/ErrorMessage' }
  asr:
    address: /speech/asr
    description: Speech-to-Text streaming — send audio, receive transcribed text with semantic VAD.
    messages:
      setup: { $ref: '#/components/messages/Setup' }
      audio: { $ref: '#/components/messages/AudioInput' }
      flush: { $ref: '#/components/messages/Flush' }
      endOfStream: { $ref: '#/components/messages/EndOfStream' }
      ready: { $ref: '#/components/messages/Ready' }
      text: { $ref: '#/components/messages/TextOutput' }
      step: { $ref: '#/components/messages/Step' }
      error: { $ref: '#/components/messages/ErrorMessage' }
  s2s:
    address: /speech/s2s
    description: Speech-to-Speech streaming — transcribe, optionally translate, and re-synthesize in real time.
    messages:
      setup: { $ref: '#/components/messages/Setup' }
      audio: { $ref: '#/components/messages/AudioInput' }
      flush: { $ref: '#/components/messages/Flush' }
      endOfStream: { $ref: '#/components/messages/EndOfStream' }
      ready: { $ref: '#/components/messages/Ready' }
      audioOut: { $ref: '#/components/messages/AudioOutput' }
      error: { $ref: '#/components/messages/ErrorMessage' }
operations:
  ttsSend:
    action: send
    channel: { $ref: '#/channels/tts' }
  ttsReceive:
    action: receive
    channel: { $ref: '#/channels/tts' }
  asrSend:
    action: send
    channel: { $ref: '#/channels/asr' }
  asrReceive:
    action: receive
    channel: { $ref: '#/channels/asr' }
  s2sSend:
    action: send
    channel: { $ref: '#/channels/s2s' }
  s2sReceive:
    action: receive
    channel: { $ref: '#/channels/s2s' }
components:
  messages:
    Setup:
      name: setup
      title: Session setup
      payload:
        type: object
        properties:
          type: { type: string, const: setup }
          voice_id: { type: string }
          output_format: { type: string, description: 'e.g. wav, pcm, opus, pcm_16000, ulaw_8000' }
          input_format: { type: string, description: 'STT/S2S input encoding, e.g. pcm_16000' }
    TextInput:
      name: text
      payload:
        type: object
        properties:
          type: { type: string, const: text }
          text: { type: string }
    TextOutput:
      name: text
      payload:
        type: object
        properties:
          type: { type: string, const: text }
          text: { type: string }
    AudioInput:
      name: audio
      payload:
        type: object
        properties:
          type: { type: string, const: audio }
          audio: { type: string, description: base64-encoded audio chunk }
    AudioOutput:
      name: audio
      payload:
        type: object
        properties:
          type: { type: string, const: audio }
          audio: { type: string, description: base64-encoded synthesized audio chunk }
    Ready:
      name: ready
      payload:
        type: object
        properties:
          type: { type: string, const: ready }
    Step:
      name: step
      description: STT semantic-VAD progress event (emitted roughly every 80ms).
      payload:
        type: object
        properties:
          type: { type: string, const: step }
    Flush:
      name: flush
      payload:
        type: object
        properties:
          type: { type: string, const: flush }
    EndOfStream:
      name: end_of_stream
      payload:
        type: object
        properties:
          type: { type: string, const: end_of_stream }
    ErrorMessage:
      name: error
      payload:
        type: object
        properties:
          type: { type: string, const: error }
          message: { type: string }
          code: { type: integer, description: '1008 = policy violation (auth/setup/format); 1011 = internal server error' }