asyncapi: 2.6.0
info:
  title: Text-to-Speech (TTS)
  version: 1.0.0
channels:
  /stream/input:
    description: Generate emotionally expressive speech.
    bindings:
      ws:
        query:
          type: object
          properties:
            access_token:
              type: string
              default: ''
            context_generation_id:
              type: string
            format_type:
              $ref: '#/components/schemas/format_type'
            include_timestamp_types:
              type: array
              items:
                $ref: '#/components/schemas/TimestampType'
            instant_mode:
              type: boolean
              default: true
            no_binary:
              type: boolean
              default: false
            strip_headers:
              type: boolean
              default: false
            version:
              $ref: '#/components/schemas/version'
            api_key:
              type: string
              default: ''
    publish:
      operationId: stream-input-publish
      summary: subscribe
      message:
        name: subscribe
        title: subscribe
        payload:
          $ref: '#/components/schemas/StreamInputSubscribe'
    subscribe:
      operationId: stream-input-subscribe
      summary: publish
      message:
        name: publish
        title: publish
        payload:
          $ref: '#/components/schemas/StreamInputPublish'
servers:
  https://api.hume.ai/:
    url: wss://api.hume.ai/v0/tts
    protocol: wss
    x-default: true
components:
  schemas:
    FormatType:
      type: string
      enum:
        - mp3
        - pcm
        - wav
      title: FormatType
    format_type:
      oneOf:
        - $ref: '#/components/schemas/FormatType'
      description: The format to be used for audio generation.
      title: format_type
    TimestampType:
      type: string
      enum:
        - word
        - phoneme
      title: TimestampType
    OctaveVersion:
      type: string
      enum:
        - '1'
        - '2'
      description: |-
        Selects the Octave model version used to synthesize speech for this request. If you omit this field, Hume
        automatically routes the request to the most appropriate model. Setting a specific version ensures stable and
        repeatable behavior across requests.

        Use `2` to opt into the latest Octave capabilities. When you specify version `2`, you must also provide a
        `voice`. Requests that set `version: 2` without a voice will be rejected.

        For a comparison of Octave versions, see the
        [Octave versions](/docs/text-to-speech-tts/overview#octave-versions) section in the TTS overview.
      title: OctaveVersion
    version:
      oneOf:
        - $ref: '#/components/schemas/OctaveVersion'
      description: The version of the Octave Model to use. 1 for the legacy model, 2 for the new model.
      title: version
    MillisecondInterval:
      type: object
      properties:
        begin:
          type: integer
          description: Start time of the interval in milliseconds.
        end:
          type: integer
          description: End time of the interval in milliseconds.
      required:
        - begin
        - end
      title: MillisecondInterval
    Timestamp-Output:
      type: object
      properties:
        text:
          type: string
          description: The word or phoneme text that the timestamp corresponds to.
        time:
          $ref: '#/components/schemas/MillisecondInterval'
          description: The start and end timestamps for the word or phoneme in milliseconds.
        type:
          $ref: '#/components/schemas/TimestampType'
      required:
        - text
        - time
        - type
      title: Timestamp-Output
    Snippet-Output:
      type: object
      properties:
        audio:
          type: string
          description: The segmented audio output in the requested format, encoded as a base64 string.
        generation_id:
          type: string
          format: uuid4
          description: The generation ID this snippet corresponds to.
        id:
          type: string
          format: uuid4
          description: A unique ID associated with this **Snippet**.
        text:
          type: string
          description: The text for this **Snippet**.
        timestamps:
          type: array
          items:
            $ref: '#/components/schemas/Timestamp-Output'
          description: >-
            A list of word or phoneme level timestamps for the generated audio. Timestamps are only returned for Octave
            2 requests.
        transcribed_text:
          type:
            - string
            - 'null'
          description: The transcribed text of the generated audio. It is only present if `instant_mode` is set to `false`.
        utterance_index:
          type:
            - integer
            - 'null'
          description: The index of the utterance in the request this snippet corresponds to.
      required:
        - audio
        - generation_id
        - id
        - text
        - timestamps
        - transcribed_text
        - utterance_index
      title: Snippet-Output
    TtsOutput:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - audio
              description: 'Discriminator value: audio'
            audio:
              type: string
              description: The generated audio output chunk in the requested format.
            audio_format:
              $ref: '#/components/schemas/FormatType'
              description: The generated audio output format.
            chunk_index:
              type: integer
              description: The index of the audio chunk in the snippet.
            generation_id:
              type: string
              format: uuid4
              description: The generation ID of the parent snippet that this chunk corresponds to.
            is_last_chunk:
              type: boolean
              description: Whether or not this is the last chunk streamed back from the decoder for one input snippet.
            request_id:
              type: string
              description: ID of the initiating request.
            snippet:
              $ref: '#/components/schemas/Snippet-Output'
            snippet_id:
              type: string
              format: uuid4
              description: The ID of the parent snippet that this chunk corresponds to.
            text:
              type: string
              description: The text of the parent snippet that this chunk corresponds to.
            transcribed_text:
              type:
                - string
                - 'null'
              description: >-
                The transcribed text of the generated audio of the parent snippet that this chunk corresponds to. It is
                only present if `instant_mode` is set to `false`.
            utterance_index:
              type:
                - integer
                - 'null'
              description: The index of the utterance in the request that the parent snippet of this chunk corresponds to.
          required:
            - type
            - audio
            - audio_format
            - chunk_index
            - generation_id
            - is_last_chunk
            - request_id
            - snippet_id
            - text
            - transcribed_text
            - utterance_index
          description: SnippetAudioChunk variant
        - type: object
          properties:
            type:
              type: string
              enum:
                - timestamp
              description: 'Discriminator value: timestamp'
            generation_id:
              type: string
              format: uuid4
              description: The generation ID of the parent snippet that this chunk corresponds to.
            request_id:
              type: string
              description: ID of the initiating request.
            snippet_id:
              type: string
              format: uuid4
              description: The ID of the parent snippet that this chunk corresponds to.
            timestamp:
              $ref: '#/components/schemas/Timestamp-Output'
              description: A word or phoneme level timestamp for the generated audio.
          required:
            - type
            - generation_id
            - request_id
            - snippet_id
            - timestamp
          description: OctaveOutputTimestamp variant
      discriminator:
        propertyName: type
      title: TtsOutput
    StreamInputSubscribe:
      oneOf:
        - $ref: '#/components/schemas/TtsOutput'
      title: StreamInputSubscribe
    VoiceProvider:
      type: string
      enum:
        - HUME_AI
        - CUSTOM_VOICE
      title: VoiceProvider
    VoiceId:
      type: object
      properties:
        id:
          type: string
          description: The unique ID associated with the **Voice**.
        provider:
          $ref: '#/components/schemas/VoiceProvider'
          description: >-
            Specifies the source provider associated with the chosen voice.


            - **`HUME_AI`**: Select voices from Hume's [Voice Library](https://app.hume.ai/tts/voice-library),
            containing a variety of preset, shared voices.

            - **`CUSTOM_VOICE`**: Select from voices you've personally generated and saved in your account. 


            If no provider is explicitly set, the default provider is `CUSTOM_VOICE`. When using voices from Hume's
            **Voice Library**, you must explicitly set the provider to `HUME_AI`.


            Preset voices from Hume's **Voice Library** are accessible by all users. In contrast, your custom voices are
            private and accessible only via requests authenticated with your API key.
      required:
        - id
      title: VoiceId
    VoiceName:
      type: object
      properties:
        name:
          type: string
          description: The name of a **Voice**.
        provider:
          $ref: '#/components/schemas/VoiceProvider'
          description: >-
            Specifies the source provider associated with the chosen voice.


            - **`HUME_AI`**: Select voices from Hume's [Voice Library](https://app.hume.ai/tts/voice-library),
            containing a variety of preset, shared voices.

            - **`CUSTOM_VOICE`**: Select from voices you've personally generated and saved in your account. 


            If no provider is explicitly set, the default provider is `CUSTOM_VOICE`. When using voices from Hume's
            **Voice Library**, you must explicitly set the provider to `HUME_AI`.


            Preset voices from Hume's **Voice Library** are accessible by all users. In contrast, your custom voices are
            private and accessible only via requests authenticated with your API key.
      required:
        - name
      title: VoiceName
    VoiceRef:
      oneOf:
        - $ref: '#/components/schemas/VoiceId'
        - $ref: '#/components/schemas/VoiceName'
      title: VoiceRef
    InputMessage:
      type: object
      properties:
        close:
          type: boolean
          default: false
          description: Force the generation of audio and close the stream.
        description:
          type:
            - string
            - 'null'
          description: >-
            Natural language instructions describing how the synthesized speech should sound, including but not limited
            to tone, intonation, pacing, and accent.


            **This field behaves differently depending on whether a voice is specified**:

            - **Voice specified**: the description will serve as acting directions for delivery. Keep directions
            concise—100 characters or fewer—for best results. See our guide on [acting
            instructions](/docs/text-to-speech-tts/acting-instructions).

            - **Voice not specified**: the description will serve as a voice prompt for generating a voice. See our
            [prompting guide](/docs/text-to-speech-tts/prompting) for design tips.
        flush:
          type: boolean
          default: false
          description: Force the generation of audio regardless of how much text has been supplied.
        speed:
          type: number
          format: double
          default: 1
          description: >-
            Speed multiplier for the synthesized speech. Extreme values below 0.75 and above 1.5 may sometimes cause
            instability to the generated output.
        text:
          type: string
          default: ''
          description: The input text to be synthesized into speech.
        trailing_silence:
          type: number
          format: double
          default: 0
          description: Duration of trailing silence (in seconds) to add to this utterance
        voice:
          oneOf:
            - $ref: '#/components/schemas/VoiceRef'
            - type: 'null'
          description: >-
            The `name` or `id` associated with a **Voice** from the **Voice Library** to be used as the speaker for this
            and all subsequent `utterances`, until the `voice` field is updated again.

             See our [voices guide](/docs/text-to-speech-tts/voices) for more details on generating and specifying **Voices**.
      description: Input message type for the TTS stream.
      title: InputMessage
    StreamInputPublish:
      oneOf:
        - $ref: '#/components/schemas/InputMessage'
      title: StreamInputPublish
