Hume AI subpackage_voices API

openapi: 3.1.0
info:
  title: Speech-to-speech (EVI) subpackage_voices API
  version: 1.0.0
servers:
- url: https://api.hume.ai
tags:
- name: subpackage_voices
paths:
  /v0/tts/voices:
    post:
      operationId: create
      summary: Create voice
      description: 'Saves a new custom voice to your account using the specified TTS generation ID.


        Once saved, this voice can be reused in subsequent TTS requests, ensuring consistent speech style and prosody. For more details on voice creation, see the [Voices Guide](/docs/text-to-speech-tts/voices).'
      tags:
      - subpackage_voices
      parameters:
      - name: X-Hume-Api-Key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OctaveVoiceDesignSaveResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OctaveVoiceDesignSaveArgs'
    get:
      operationId: list
      summary: List voices
      description: Lists voices you have saved in your account, or voices from the [Voice Library](https://app.hume.ai/tts/voice-library).
      tags:
      - subpackage_voices
      parameters:
      - name: provider
        in: query
        description: 'Specify the voice provider to filter voices returned by the endpoint:


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

          - **`CUSTOM_VOICE`**: Lists custom voices created and saved to your account.'
        required: true
        schema:
          $ref: '#/components/schemas/VoiceProvider'
      - name: page_number
        in: query
        description: 'Specifies the page number to retrieve, enabling pagination.


          This parameter uses zero-based indexing. For example, setting `page_number` to 0 retrieves the first page of results (items 0-9 if `page_size` is 10), setting `page_number` to 1 retrieves the second page (items 10-19), and so on. Defaults to 0, which retrieves the first page.'
        required: false
        schema:
          type: integer
          default: 0
      - name: page_size
        in: query
        description: 'Specifies the maximum number of results to include per page, enabling pagination. The value must be between 1 and 100, inclusive.


          For example, if `page_size` is set to 10, each page will include up to 10 items. Defaults to 10.'
        required: false
        schema:
          type: integer
      - name: ascending_order
        in: query
        required: false
        schema:
          type: boolean
      - name: filter_tag
        in: query
        description: 'Filter voices by tag using `TAG:TAG_VALUE` syntax.


          For example, `GENDER:Male` returns only voices with the `GENDER` tag set to `Male`. Tag types are case-insensitive; tag values are case-sensitive.


          Multiple values are ANDed together; for example, `[GENDER:Male, LANGUAGE:Japanese]` returns only voices matching both criteria.'
        required: false
        schema:
          type: array
          items:
            type: string
      - name: X-Hume-Api-Key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/return_paged_octave_public_voices'
    delete:
      operationId: delete
      summary: Delete voice
      description: Deletes a previously generated custom voice.
      tags:
      - subpackage_voices
      parameters:
      - name: name
        in: query
        description: Name of the voice to delete
        required: true
        schema:
          type: string
      - name: X-Hume-Api-Key
        in: header
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/voices_delete_Response_200'
components:
  schemas:
    ValidationErrorLocItems:
      oneOf:
      - type: string
      - type: integer
      title: ValidationErrorLocItems
    VoiceProvider:
      type: string
      enum:
      - HUME_AI
      - CUSTOM_VOICE
      title: VoiceProvider
    ValidationError:
      type: object
      properties:
        loc:
          type: array
          items:
            $ref: '#/components/schemas/ValidationErrorLocItems'
        msg:
          type: string
        type:
          type: string
      required:
      - loc
      - msg
      - type
      title: ValidationError
    OctaveVoiceDesignSaveArgs:
      type: object
      properties:
        generation_id:
          type: string
          description: A unique ID associated with this TTS generation that can be used as context for generating consistent speech style and prosody across multiple requests.
        name:
          type: string
          description: The name of a **Voice**.
      required:
      - generation_id
      - name
      title: OctaveVoiceDesignSaveArgs
    OctaveVoiceDesignSaveResponse:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          format: uuid4
          description: The unique ID associated with the **Voice**.
        name:
          type: string
          description: The name of a **Voice**.
        provider:
          $ref: '#/components/schemas/VoiceProvider'
          description: "Specifies the source provider associated with the chosen voice.\n\n- **`HUME_AI`**: Select voices from Hume's [Voice Library](https://app.hume.ai/tts/voice-library), containing a variety of preset, shared voices.\n- **`CUSTOM_VOICE`**: Select from voices you've personally generated and saved in your account. \n\nIf 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`.\n\nPreset 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
      - name
      - provider
      title: OctaveVoiceDesignSaveResponse
    voices_delete_Response_200:
      type: object
      properties: {}
      description: Empty response body
      title: voices_delete_Response_200
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
      title: HTTPValidationError
    return_voice_octave_public:
      type: object
      properties:
        compatible_octave_models:
          type: array
          items:
            type: string
        id:
          type: string
          description: ID of the voice in the `Voice Library`.
        name:
          type: string
          description: Name of the voice in the `Voice Library`.
        provider:
          $ref: '#/components/schemas/VoiceProvider'
          description: 'The provider associated with the created voice.


            Voices created through this endpoint will always have the provider set to `CUSTOM_VOICE`, indicating a custom voice stored in your account.'
      required:
      - id
      - name
      - provider
      description: An Octave voice available for text-to-speech
      title: return_voice_octave_public
    return_paged_octave_public_voices:
      type: object
      properties:
        page_number:
          type: integer
          description: 'The page number of the returned list.


            This value corresponds to the `page_number` parameter specified in the request. Pagination uses zero-based indexing.'
        page_size:
          type: integer
          description: 'The maximum number of items returned per page.


            This value corresponds to the `page_size` parameter specified in the request.'
        total_pages:
          type: integer
          description: The total number of pages in the collection.
        voices_page:
          type: array
          items:
            $ref: '#/components/schemas/return_voice_octave_public'
          description: List of voices returned for the specified `page_number` and `page_size`.
      required:
      - page_number
      - page_size
      - total_pages
      - voices_page
      description: A paginated list Octave voices available for text-to-speech
      title: return_paged_octave_public_voices
  securitySchemes:
    bearerAuth:
      type: apiKey
      in: header
      name: X-Hume-Api-Key