> ## Documentation Index > Fetch the complete documentation index at: https://heygen-1fa696a7.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Update an Audio Voice > Renames a voice that your workspace owns, instant or professional. Today `name` is the only field you can change. The name follows the same rules as when the voice was created: spaces at the start and end are removed, and an instant voice name can have 1 to 64 characters, a professional voice name 1 to 256. Returns the updated voice, in the same shape as GET /v3/models/audio/voices/{voice_id}. The HeyGen app also shows the new name. It may cut a name longer than 64 characters. A professional voice can be renamed in any status. An instant voice cannot be renamed while its status is `PENDING`, which lasts a few seconds after it is created: this returns 409 `voice_not_ready`, so wait a few seconds and try again. A public voice, a deleted voice, or a voice from another workspace returns 404 `voice_not_found`. A workspace member who cannot edit the voice in the HeyGen app is refused as DELETE refuses them: 403 `resource_access_denied`, or 404 `resource_not_found` when the member has no access to the voice at all. ## OpenAPI ````yaml /openapi/external-api.json patch /v3/models/audio/voices/{voice_id} openapi: 3.1.0 info: title: HeyGen External API version: 1.0.0 description: >- HeyGen's external API for programmatic AI video creation. See https://docs.heygen.com for full documentation. contact: name: HeyGen Product Infra url: https://heygen.com servers: - url: https://api.heygen.com description: Production security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Video Agent description: Create videos from text prompts using AI - name: Videos description: Create, list, retrieve, and delete videos - name: Templates description: Generate videos from reusable templates by replacing their variables - name: Voices description: Text-to-speech and voice management - name: Audio description: Search the background-music and sound-effects catalog - name: Video Translate description: Translate videos into other languages - name: AI Clipping description: Turn long-form videos into ready-to-share short clips with captions - name: Batches description: Create and track batches of videos. - name: Video Translation Batches description: Create and track batches of video translations. - name: Lipsync Batches description: Create and track batches of lipsyncs. - name: Asset Batches description: Create and track batches of direct-to-S3 asset uploads. - name: User description: Account information and billing - name: API Keys description: Inspect the API key authenticating the current request - name: Avatars description: List and manage avatars and looks - name: Assets description: Upload files for use in video creation - name: Folders description: >- Create folders to organize videos and translations in the workspace, and look up any folder, Assets library folders included, by id - name: Webhooks description: Manage webhook endpoints and events - name: Lipsync description: Dub or replace audio on existing videos - name: Brand description: >- Brand-related resources — brand kits (colors, fonts, logos) and brand glossaries (custom term translations) - name: HyperFrames description: Render HyperFrames composition zips into video — separate from /v3/videos - name: Models description: '' - name: Filler Word Removal description: '' paths: /v3/models/audio/voices/{voice_id}: patch: tags: - Models summary: Update an Audio Voice description: >- Renames a voice that your workspace owns, instant or professional. Today `name` is the only field you can change. The name follows the same rules as when the voice was created: spaces at the start and end are removed, and an instant voice name can have 1 to 64 characters, a professional voice name 1 to 256. Returns the updated voice, in the same shape as GET /v3/models/audio/voices/{voice_id}. The HeyGen app also shows the new name. It may cut a name longer than 64 characters. A professional voice can be renamed in any status. An instant voice cannot be renamed while its status is `PENDING`, which lasts a few seconds after it is created: this returns 409 `voice_not_ready`, so wait a few seconds and try again. A public voice, a deleted voice, or a voice from another workspace returns 404 `voice_not_found`. A workspace member who cannot edit the voice in the HeyGen app is refused as DELETE refuses them: 403 `resource_access_denied`, or 404 `resource_not_found` when the member has no access to the voice at all. operationId: updateModelAudioVoice parameters: - name: voice_id in: path required: true schema: type: string description: Unique voice identifier requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateModelAudioVoiceRequest' responses: '200': description: Successful response content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ModelAudioVoiceResponse' '400': description: Invalid request parameters content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' examples: missing_name: summary: The body has no name value: error: code: invalid_parameter message: Field required param: name doc_url: null instant_name_too_long: summary: The name is too long for an instant voice value: error: code: invalid_parameter message: An instant voice name can have at most 64 characters. param: name doc_url: null '401': description: Authentication failed content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: unauthorized message: Invalid or expired API key. Verify your x-api-key header. param: null doc_url: null '403': description: >- Forbidden — `error.code` is one of: `insufficient_api_key_scope`, `resource_access_denied`. content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' examples: insufficient_api_key_scope: summary: Missing scope value: error: code: insufficient_api_key_scope message: The API key requires voices:write. param: null doc_url: null resource_access_denied: summary: The member cannot edit this voice value: error: code: resource_access_denied message: Forbidden param: null doc_url: null '404': description: Resource not found content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: voice_not_found: summary: No such voice in the workspace value: error: code: voice_not_found message: Voice not found. param: null doc_url: null resource_not_found: summary: The member has no access to the voice in the HeyGen app value: error: code: resource_not_found message: Resource not found param: null doc_url: null '409': description: Conflict content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: voice_not_ready message: >- The instant voice is still being created. Try again in a few seconds. param: null doc_url: null headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer '429': description: Rate limit exceeded content: application/json: schema: type: object properties: error: $ref: '#/components/schemas/StandardAPIError' example: error: code: rate_limit_exceeded message: >- Too many requests. Retry after the duration specified in the Retry-After header. param: null doc_url: null headers: Retry-After: description: Seconds to wait before retrying schema: type: integer security: - ApiKeyAuth: [] - BearerAuth: [] components: schemas: UpdateModelAudioVoiceRequest: additionalProperties: false description: The fields to change on one audio voice. Only `name` can change today. properties: name: description: >- New display name of the voice. Spaces at the start and end are removed. The limits are the same as when the voice was created: 1 to 64 characters for an instant voice, 1 to 256 for a professional voice. examples: - Support Narrator maxLength: 256 minLength: 1 title: Name type: string required: - name title: UpdateModelAudioVoiceRequest type: object ModelAudioVoiceResponse: additionalProperties: false description: Customer-visible state of one model-backed audio voice. properties: voice_id: description: Stable identifier for this voice. title: Voice Id type: string mode: description: >- `professional` for a professional voice clone, `instant` for an instant voice clone. enum: - professional - instant title: Mode type: string name: description: Display name of the voice. title: Name type: string language: anyOf: - type: string - type: 'null' default: null description: >- Primary language code of the voice. An instant clone created without one has none until its recording passes every check and the detected language is recorded, so a clone refused before that never gets one. A professional voice created without one has none until it is ACTIVE. title: Language status: $ref: '#/components/schemas/VideoTTSVoiceStatus' description: 'Current lifecycle state: `PENDING`, `ACTIVE`, or `FAILED`.' created_at: description: Unix timestamp in seconds when the voice was created. title: Created At type: integer failure_reason: anyOf: - $ref: '#/components/schemas/VideoTTSVoiceFailureReason' - type: 'null' default: null description: Stable failure code. Present only when `status` is `FAILED`. preview_audio_url: anyOf: - type: string - type: 'null' default: null description: >- URL to a WAV clip of this voice reading a short fixed preview script: in its language when a script exists for it, otherwise in English. Present only when `status` is `ACTIVE` and a clip exists. The URL can expire; read the voice again rather than storing it. title: Preview Audio Url required: - voice_id - mode - name - status - created_at title: ModelAudioVoiceResponse type: object StandardAPIError: type: object properties: code: type: string description: Machine-readable error code example: invalid_parameter message: type: string description: Human-readable error message example: Video not found param: type: - string - 'null' description: Which request field caused the error doc_url: type: - string - 'null' description: Link to error documentation errors: type: array description: >- Per-item error details for batch/multi-node failures (e.g. graph compilation errors by node). items: $ref: '#/components/schemas/StandardAPIErrorDetail' request_id: type: string description: >- Request identifier, also returned in the X-HeyGen-Request-Id response header. Include it when contacting support. example: 8c4f0b9e1d2a4f6b9e3c7a1d5f2b8e40 required: - code - message VideoTTSVoiceStatus: description: Values persisted in ``video_tts_voices.status``. enum: - PENDING - ACTIVE - FAILED title: VideoTTSVoiceStatus type: string VideoTTSVoiceFailureReason: description: Stable failure codes persisted for terminal training failures. enum: - INVALID_AUDIO - INSUFFICIENT_AUDIO - PREPROCESSING_FAILED - TRAINING_FAILED - DESIGN_FAILED - ARTIFACT_VALIDATION_FAILED - INTERNAL_ERROR title: VideoTTSVoiceFailureReason type: string StandardAPIErrorDetail: type: object properties: code: type: string description: Machine-readable error code example: unknown_node_type message: type: string description: Human-readable error message example: Unknown node type node_id: type: string description: Graph node id this error pertains to, if applicable port: type: string description: Port name on the node this error pertains to, if applicable path: type: string description: Field path within the item this error pertains to, if applicable required: - code - message securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: HeyGen API key. Obtain from your HeyGen dashboard. BearerAuth: type: http scheme: bearer description: OAuth2 bearer token. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.