openapi: 3.1.0 info: title: Voices version: 1.0.0 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' servers: - url: https://api.hume.ai components: schemas: 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 VoiceProvider: type: string enum: - HUME_AI - CUSTOM_VOICE title: VoiceProvider 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. - **`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 - name - provider title: OctaveVoiceDesignSaveResponse ValidationErrorLocItems: oneOf: - type: string - type: integer title: ValidationErrorLocItems ValidationError: type: object properties: loc: type: array items: $ref: '#/components/schemas/ValidationErrorLocItems' msg: type: string type: type: string required: - loc - msg - type title: ValidationError 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 voices_delete_Response_200: type: object properties: {} description: Empty response body title: voices_delete_Response_200 securitySchemes: bearerAuth: type: apiKey in: header name: X-Hume-Api-Key