{"openapi":"3.1.0","info":{"title":"Voices","version":"1.0.0"},"paths":{"/v0/tts/voices":{"post":{"operationId":"voices_create","summary":"Create voice","description":"Saves a new custom voice to your account using the specified TTS generation ID.\n\nOnce 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":["voices"],"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"}}}},"security":[{"bearerAuth":[]}]},"get":{"operationId":"voices_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":["voices"],"parameters":[{"name":"provider","in":"query","description":"Specify the voice provider to filter voices returned by the endpoint:\n\n- **`HUME_AI`**: Lists preset, shared voices from Hume's [Voice Library](https://app.hume.ai/tts/voice-library).\n- **`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.\n\nThis 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.\n\nFor 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.\n\nFor example, `GENDER:Male` returns only voices with the `GENDER` tag set to `Male`. Tag types are case-insensitive; tag values are case-sensitive.\n\nMultiple values are ANDed together; for example, `[GENDER:Male, LANGUAGE:Japanese]` returns only voices matching both criteria.","required":false,"schema":{"type":"array","items":{"type":"string"}}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/return_paged_octave_public_voices"}}}}},"security":[{"bearerAuth":[]}]},"delete":{"operationId":"voices_delete","summary":"Delete voice","description":"Deletes a previously generated custom voice.","tags":["voices"],"parameters":[{"name":"name","in":"query","description":"Name of the voice to delete","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/voices_delete_Response_200"}}}}},"security":[{"bearerAuth":[]}]}}},"tags":[{"name":"voices"}],"servers":[{"url":"https://api.hume.ai","description":"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.\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"},"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.\n\nVoices 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.\n\nThis 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.\n\nThis 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"}}}}