Hume Voices API
REST API for managing custom voices used by Hume's TTS and EVI products. Supports voice creation, listing, and deletion. Bearer token auth.
OpenAPI Specification
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