> For the complete documentation index, see [llms.txt](https://docs.noiz.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.noiz.ai/api-documentation/voices.md).

# Voices

## Get user voices or system voices

> Supports pagination and filtering by voice type.

```json
{"openapi":"3.0.3","info":{"title":"Voice API","version":"1.0.0"},"servers":[{"url":"https://noiz.ai/v1","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"Voice":{"type":"object","properties":{"id":{"type":"integer"},"voice_id":{"type":"string"},"display_name":{"type":"string"},"voice_type":{"type":"string"},"labels":{"type":"string"},"sample":{"type":"string","nullable":true},"meta":{"type":"object","properties":{"text":{"type":"string"}}},"url":{"type":"string"},"create_time":{"type":"integer"}}}},"responses":{"UnauthorizedError":{"description":"API Key missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}},"paths":{"/voices":{"get":{"tags":["Voices"],"summary":"Get user voices or system voices","description":"Supports pagination and filtering by voice type.","parameters":[{"in":"query","name":"voice_type","schema":{"type":"string","enum":["custom","built-in"],"default":"custom"},"description":"Voice type filter. \"custom\" for user-created voices (default), \"built-in\" for system voices."},{"in":"query","name":"keyword","schema":{"type":"string"},"description":"Search keyword (searches voice name, description, labels)"},{"in":"query","name":"skip","schema":{"type":"integer","default":0},"description":"Page number (starts from 0)"},{"in":"query","name":"limit","schema":{"type":"integer","default":10},"description":"Maximum number of items to return per page"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"total_count":{"type":"integer"},"voices":{"type":"array","items":{"$ref":"#/components/schemas/Voice"}}}}}}}}},"400":{"description":"Invalid parameters","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}}
```

## Clone a voice

> Clone a voice by uploading an audio file or providing an audio URL.  Provide either file (upload) or voice\_url (remote URL), at least one is required. Only WAV, MP3, and M4A formats are supported.

```json
{"openapi":"3.0.3","info":{"title":"Voice API","version":"1.0.0"},"servers":[{"url":"https://noiz.ai/v1","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"responses":{"UnauthorizedError":{"description":"API Key missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}},"paths":{"/voices":{"post":{"tags":["Voices"],"summary":"Clone a voice","description":"Clone a voice by uploading an audio file or providing an audio URL.  Provide either file (upload) or voice_url (remote URL), at least one is required. Only WAV, MP3, and M4A formats are supported.","requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"file":{"type":"string","format":"binary","description":"Audio file to upload (WAV, MP3, or M4A). Either file or voice_url must be provided."},"voice_url":{"type":"string","description":"URL to a remote audio file (WAV, MP3, or M4A). Either file or voice_url must be provided."},"display_name":{"type":"string","description":"Display name for the cloned voice"},"denoise":{"type":"boolean","description":"Whether to apply noise reduction to the audio"},"language":{"type":"string","description":"Language of the audio (e.g. \"en\", \"zh\")"}}}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer","description":"Status code (0 = success)"},"message":{"type":"string"},"data":{"type":"object","properties":{"voice_id":{"type":"string"},"voice_display_name":{"type":"string"},"duration":{"type":"integer"},"selected_text":{"type":"string"},"selected_start":{"type":"number","format":"float"},"selected_end":{"type":"number","format":"float"},"text":{"type":"string"},"language":{"type":"string"}}}}}}}},"400":{"description":"Invalid request / processing error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}}
```

## GET /voices/{voice\_id}

> Get voice details

```json
{"openapi":"3.0.3","info":{"title":"Voice API","version":"1.0.0"},"servers":[{"url":"https://noiz.ai/v1","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"schemas":{"Voice":{"type":"object","properties":{"id":{"type":"integer"},"voice_id":{"type":"string"},"display_name":{"type":"string"},"voice_type":{"type":"string"},"labels":{"type":"string"},"sample":{"type":"string","nullable":true},"meta":{"type":"object","properties":{"text":{"type":"string"}}},"url":{"type":"string"},"create_time":{"type":"integer"}}}},"responses":{"UnauthorizedError":{"description":"API Key missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}},"paths":{"/voices/{voice_id}":{"get":{"tags":["Voices"],"summary":"Get voice details","parameters":[{"in":"path","name":"voice_id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Voice"}}}}}},"400":{"description":"Invalid parameters"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Voice not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}}}}}
```

## Delete a voice (soft delete)

> Soft delete a voice by setting delete\_time. The voice won't be physically removed from storage.

```json
{"openapi":"3.0.3","info":{"title":"Voice API","version":"1.0.0"},"servers":[{"url":"https://noiz.ai/v1","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Authorization"}},"responses":{"UnauthorizedError":{"description":"API Key missing or invalid","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}},"paths":{"/voices/{voice_id}":{"delete":{"tags":["Voices"],"summary":"Delete a voice (soft delete)","description":"Soft delete a voice by setting delete_time. The voice won't be physically removed from storage.","parameters":[{"in":"path","name":"voice_id","required":true,"schema":{"type":"string"},"description":"The ID of the voice to delete"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","properties":{"voice_id":{"type":"string","description":"The deleted voice ID"},"display_name":{"type":"string","description":"The display name of the deleted voice"},"delete_time":{"type":"integer","description":"Unix timestamp when the voice was deleted"}}}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"description":"Voice not found","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}}}}}}}}}}}
```