asyncapi: 3.0.0
info:
  title: Test websocket schema
  version: 1.0.0
  description: This is a test websocket API.
channels:
  channelOne:
    title: Vogent Websocket
    description: >-
      Real-time text-to-speech streaming over websockets. Send text incrementally and receive audio chunks as they are generated.
      To authenticate, you must include an `Authorization` header, with the value `Bearer {API_TOKEN}`. You can also include an
      `apiKey` query param with the value being your API key. Websockets can run multiple TTS streams concurrently. If you're using
      the `contextId` feature, make sure all generations for the context are on the same websocket.
    address: /
    messages:
      WebsocketInput:
        $ref: '#/components/messages/WebsocketInput'
      FinishedMessage:
        $ref: '#/components/messages/FinishedMessage'
      ErrorMessage:
        $ref: '#/components/messages/ErrorMessage'
      ChunkMessage:
        $ref: '#/components/messages/ChunkMessage'
      TimestampMessage:
        $ref: '#/components/messages/TimestampMessage'
servers:
  vogent:
    host: api.vogent.ai/api/tts/websocket
    protocol: wss
operations:
  sendWebsocketInput:
    action: receive
    channel:
      $ref: '#/channels/channelOne'
    messages:
      - $ref: '#/channels/channelOne/messages/WebsocketInput'
  receiveWebsocketOutput:
    action: send
    channel:
      $ref: '#/channels/channelOne'
    messages:
      - $ref: '#/channels/channelOne/messages/FinishedMessage'
      - $ref: '#/channels/channelOne/messages/ErrorMessage'
      - $ref: '#/channels/channelOne/messages/ChunkMessage'
      - $ref: '#/channels/channelOne/messages/TimestampMessage'
components:
  messages:
    WebsocketInput:
      title: Websocket Input
      description: Input message for text-to-speech generation
      payload:
        type: object
        properties:
          generationId:
            type: string
            description: Unique identifier for the generation request.
          contextId:
            type: string
            description: >
              A context that can represent a single conversation, helps preserve voice consistency across multiple lines.
              Leave blank if you don't need this behavior. Ignored after the first time this generationId is seen.
              You may not have different voices across the same context (all generations with the same contextId, must also have the same voiceId).
          voiceOptionValues:
            items:
              type: string
            description: >
              **Ignore the type above, this is an array.** An array of {"optionId": string, "value": string} objects (a ModelOptionValue object)
          voiceId:
            type: string
            description: ID of the voice to use for generation. Required the first time this generationId is sent.
          text:
            type: string
            description: Text content to convert to speech.
          finalText:
            type: boolean
            description: Whether this is the final text chunk.
          cancel:
            type: boolean
            description: Whether to cancel the generation with generationId.
          sampleRate:
            type: integer
            description: Sample rate for the generated audio. Required the first time this generationId is sent.
          addWordTimestamps:
            type: boolean
            description: Add timestamps on the audio for each word in the input.
        required:
          - generationId
    FinishedMessage:
      title: Finished Message
      description: Message sent when text-to-speech generation is complete
      payload:
        type: object
        properties:
          type:
            type: string
            enum: ["finished"]
            description: Message type, always "finished"
          generationId:
            type: string
            description: Unique identifier for the generation request
        required:
          - type
          - generationId
    ErrorMessage:
      title: Error Message
      description: Message sent when text-to-speech generation encounters an error
      payload:
        type: object
        properties:
          type:
            type: string
            enum: ["error"]
            description: Message type, always "error"
          generationId:
            type: string
            description: Unique identifier for the generation request
          error:
            type: string
            description: Error message describing what went wrong
        required:
          - type
          - generationId
          - error
    ChunkMessage:
      title: Chunk Message
      description: Message sent with audio data chunks during text-to-speech generation
      payload:
        type: object
        properties:
          type:
            type: string
            enum: ["chunk"]
            description: Message type, always "chunk"
          generationId:
            type: string
            description: Unique identifier for the generation request
          audio:
            type: string
            description: Base64-encoded audio data chunk
        required:
          - type
          - generationId
          - audio
    TimestampMessage:
      title: Timestamp Message
      description: Message sent with timestamps during text-to-speech generation, only when add word timestamps is true
      payload:
        type: object
        properties:
          alignment:
            type: object
            properties:
              words:
                type: array
                items:
                  type: string
                description: An array of strings representing the words in this alignment chunk
              startTimes:
                type: array
                items:
                  type: integer
                description: The start time of each word (the array will be the same length as words). Relative to the start of the generation, in milliseconds.
              durationMs:
                type: array
                items:
                  type: integer
                description: The duration of each word (the array will be the same length as words)
          type:
            type: string
            enum: ["alignment"]
            description: Message type, always "alignment"
          generationId:
            type: string
            description: Unique identifier for the generation request
        required:
          - type
          - alignment
          - generationId