> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hooked.so/llms.txt
> Use this file to discover all available pages before exploring further.
# Delete a Voice
> Delete one of your team's own voices for good
## Overview
Deletes one of your team's own voices: one you cloned (in the dashboard or with [Clone a Voice](/api-reference/voice/clone)) or designed in the dashboard. Library voices cannot be deleted.
**This cannot be undone.** The voice is removed from your library and from the ElevenLabs account it lives in. Videos and voiceovers already made keep their audio, but the voice can no longer be used as `voiceId`.
What happens:
* The voice leaves [List Voices](/api-reference/voice/list), and a `voiceId` naming it answers `400` from then on.
* It frees one of your plan's custom voices, so you can clone another.
* It is refused with `409` while a project of your team is still being generated with it. Wait for that project to finish or fail, then retry.
Use the voice's `id` from [List Voices](/api-reference/voice/list) (`type=custom`), not its ElevenLabs `voiceId`.
```bash cURL theme={null}
curl -X DELETE "https://api.hooked.so/v1/voice/cm4xa1b2c0001ab12cd34ef56" \
-H "x-api-key: your_api_key_here"
```
```javascript JavaScript theme={null}
const response = await fetch("https://api.hooked.so/v1/voice/cm4xa1b2c0001ab12cd34ef56", {
method: "DELETE",
headers: { "x-api-key": process.env.HOOKED_API_KEY },
});
console.log(response.status, await response.json());
```
```python Python theme={null}
import os
import requests
response = requests.delete(
"https://api.hooked.so/v1/voice/cm4xa1b2c0001ab12cd34ef56",
headers={"x-api-key": os.environ["HOOKED_API_KEY"]},
)
print(response.status_code, response.json())
```
```json 200 theme={null}
{
"success": true,
"message": "Voice deleted",
"data": {
"voiceId": "cm4xa1b2c0001ab12cd34ef56",
"deleted": true
}
}
```
```json 409 theme={null}
{
"success": false,
"message": "Voice is used by project \"Launch video\" (cm4x9p0q10001ab12cd34ef56), which is still processing"
}
```
## Errors
| Status | Message | Cause |
| - | - | - |
| 401 | `code: "not_authenticated"` | Missing or invalid `x-api-key`. |
| 403 | `code: "entitlement_required"` | Your team does not have the Hooked app product. |
| 404 | `Voice not found` | Not one of your team's voices: a library voice, another team's voice or an unknown id. |
| 409 | `Voice is used by project ...` | A project is still being generated with this voice. Nothing was deleted. |
## OpenAPI
````yaml DELETE /v1/voice/{voiceId}
openapi: 3.0.0
info:
title: Hooked API
version: 1.0.0
description: AI Video Generation API
servers:
- url: https://api.hooked.so
security:
- ApiKeyAuth: []
tags:
- name: Videos
description: Create projects, follow them and render videos
- name: Account Analysis
description: Analyze TikTok and YouTube accounts
- name: Channels
description: Connected social accounts you publish to
- name: Publish
description: Schedule videos to your connected accounts
- name: Images
description: 'Image editing: background removal and expansion'
- name: Media
description: 'Your media library: list, import from a URL, upload a file'
- name: Avatars
description: Your team's own avatars (Actors) and their Hook + Demo reactions
paths:
/v1/voice/{voiceId}:
delete:
tags: []
summary: Delete a Voice
description: >-
Deletes one of your team's own voices (cloned or designed) for good.
**This cannot be undone.** The voice is removed from your library and
from the ElevenLabs account it lives in, and frees a custom voice of
your plan. Projects already made keep their audio. Refused with 409
while a project of your team is still being generated with it. Library
voices and other teams' voices answer 404. Free.
operationId: deleteVoice
parameters:
- name: voiceId
in: path
required: true
schema:
type: string
description: The voice's `id`, from List Voices (`type=custom`) or Clone a Voice.
responses:
'200':
description: Voice deleted
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
message:
type: string
data:
type: object
required:
- voiceId
- deleted
properties:
voiceId:
type: string
description: The voice that was deleted
deleted:
type: boolean
enum:
- true
example:
success: true
message: Voice deleted
data:
voiceId: cm4xa1b2c0001ab12cd34ef56
deleted: true
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/EntitlementRequired'
'404':
description: >-
Not one of your team's voices (a library voice, another team's or a
malformed id answers the same)
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound404'
example:
success: false
message: Voice not found
'409':
description: >-
A project is still being generated with this voice. Nothing was
deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/Conflict409'
example:
success: false
message: >-
Voice is used by project "Launch video"
(cm4x9p0q10001ab12cd34ef56), which is still processing
'429':
$ref: '#/components/responses/RateLimited429'
'500':
description: Internal server error (anything charged is given back)
content:
application/json:
schema:
$ref: '#/components/schemas/Error500'
example:
success: false
message: Internal server error
security:
- ApiKeyAuth: []
components:
responses:
Unauthorized:
description: Missing or invalid API key
content:
application/json:
schema:
$ref: '#/components/schemas/Error401'
EntitlementRequired:
description: The team does not have the product this endpoint needs
content:
application/json:
schema:
$ref: '#/components/schemas/EntitlementRequired403'
RateLimited429:
description: >-
Your team is over a rate limit: 30 POST requests per minute, 120 other
requests per minute, or 3 downloads of your URLs running at once.
Nothing ran and nothing was charged: wait `Retry-After` seconds and send
the request again. See [Rate
limits](/guides/error-handling#rate-limits-429).
headers:
Retry-After:
description: Seconds to wait before sending again.
schema:
type: integer
X-RateLimit-Limit:
description: The limit of the bucket you hit (not sent for the download cap).
schema:
type: integer
X-RateLimit-Remaining:
description: 'Requests left in this window: 0 (not sent for the download cap).'
schema:
type: integer
X-RateLimit-Reset:
description: >-
When the window ends, in Unix seconds (not sent for the download
cap).
schema:
type: integer
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
errorCode:
type: string
enum:
- RATE_LIMITED
message:
type: string
retryAfterSeconds:
type: integer
required:
- success
- errorCode
- message
- retryAfterSeconds
example:
success: false
errorCode: RATE_LIMITED
message: >-
Rate limit exceeded: 30 POST requests per minute per team. Retry
after 12 s.
retryAfterSeconds: 12
schemas:
NotFound404:
type: object
description: >-
Not found. Another team's resource answers the same way as a missing
one.
properties:
success:
type: boolean
enum:
- false
message:
type: string
required:
- success
- message
example:
success: false
message: Project not found
Conflict409:
type: object
description: >-
The resource cannot be deleted right now. `message` says why; nothing
was deleted.
properties:
success:
type: boolean
enum:
- false
message:
type: string
data:
type: object
properties:
scheduleIds:
type: array
items:
type: string
description: >-
The pending scheduled posts in the way. Cancel each with DELETE
/v1/schedule/{scheduleId}, then retry.
required:
- success
- message
Error500:
type: object
properties:
success:
type: boolean
enum:
- false
message:
type: string
error:
type: string
description: Present on some endpoints
example:
success: false
message: Internal server error
Error401:
type: object
description: Missing or invalid `x-api-key`.
properties:
code:
type: string
enum:
- not_authenticated
message:
type: string
example: Not authenticated
errorCode:
type: string
enum:
- NOT_AUTHENTICATED
details:
type: object
additionalProperties:
type: string
example:
code: not_authenticated
message: Not authenticated
errorCode: NOT_AUTHENTICATED
details:
x-api-key: Header not provided or API Key invalid
EntitlementRequired403:
type: object
description: >-
Valid key, but the team does not have the product this endpoint belongs
to.
properties:
code:
type: string
enum:
- entitlement_required
error:
type: string
enum:
- entitlement_required
message:
type: string
product:
type: string
example: app
required:
- code
- error
- message
- product
example:
code: entitlement_required
error: entitlement_required
message: This endpoint requires the "app" product.
product: app
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: x-api-key
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.