---
title: "Create or Retrain an Audio Voice"
method: POST
path: "/v3/models/audio/voices"
tags: ["Models"]
---

# Create or Retrain an Audio Voice

`POST /v3/models/audio/voices`

## Request

- Base URL: `https://api.heygen.com`
- URL: `https://api.heygen.com/v3/models/audio/voices`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Creates an instant voice with `mode: instant` from one recording, or a professional voice with `mode: professional`. Free-plan workspaces can make 20 instant-clone calls per rolling day by default. All members share the workspace limit. Text-based voice design has a separate daily limit. Workspace limits can differ. Instant voices do not support retraining. Use POST /v3/models/audio/tts/stream for streaming speech; model defaults to heygen-voice-1. Instant voices ignore seed, speed and pitch controls. Mode is required for both creation and retraining. Retrains a professional voice when `voice_id` is set. The voice is `PENDING` while training; poll GET /v3/models/audio/voices/{voice_id} until it is `ACTIVE` or `FAILED`. A new voice in professional mode needs a free professional-voice slot; each purchased slot provides five pooled trainings per monthly billing period, including the first, and failed trainings do not count. Send an Idempotency-Key to make retries safe.

## Headers

- `Idempotency-Key` string

## Request body

- union
  - CreateModelAudioVoiceRequest: Create or retrain one model-backed audio voice.
    - `mode` 'professional', required: Supported audio-voice creation implementations.
    - `voice_id` string, nullable: Existing professional voice to retrain. Omit to create a new voice.
    - `name` string, nullable: Display name for a new voice. Ignored when `voice_id` is supplied; the existing name is retained.
    - `language` string, nullable: Primary language code, such as `en`, for a new voice. Optional. When omitted, the language of each recording is detected during training. `language` is null until the voice is ACTIVE. Ignored when `voice_id` is supplied; the existing language is retained.
    - `audio` union[], required: Source recordings of the same speaker. Each item may be a public HTTPS URL, a HeyGen asset ID, or base64-encoded audio. The recordings must contain at least 20 minutes of audio and no more than 1.5 GB (1,500,000,000 bytes) in total.
      - union
        - AssetUrl: Asset input via publicly accessible HTTPS URL.
          - `type` 'url', required: Input type discriminator
          - `url` string, required: Publicly accessible HTTPS URL for the asset
        - AssetId: Asset input via HeyGen asset ID from the asset upload endpoint.
          - `type` 'asset_id', required: Input type discriminator
          - `asset_id` string, required: HeyGen asset ID from the asset upload endpoint
        - AssetBase64: Asset input via base64-encoded content.
          - `type` 'base64', required: Input type discriminator
          - `media_type` string, required: MIME type of the encoded content (e.g. "image/png")
          - `data` string, required: Base64-encoded file content
  - CreateInstantAudioVoiceRequest: Create one instant voice from a single recording.
    - `mode` 'instant', required
    - `name` string, required: Display name for the instant voice.
    - `language` string, nullable: Language code for the voice design. Omit to detect it from the recording.
    - `audio` union[], required: One source recording, supplied as an audio asset ID, public HTTPS URL, or base64 audio.
      - union
        - AssetUrl: Asset input via publicly accessible HTTPS URL.
          - `type` 'url', required: Input type discriminator
          - `url` string, required: Publicly accessible HTTPS URL for the asset
        - AssetId: Asset input via HeyGen asset ID from the asset upload endpoint.
          - `type` 'asset_id', required: Input type discriminator
          - `asset_id` string, required: HeyGen asset ID from the asset upload endpoint
        - AssetBase64: Asset input via base64-encoded content.
          - `type` 'base64', required: Input type discriminator
          - `media_type` string, required: MIME type of the encoded content (e.g. "image/png")
          - `data` string, required: Base64-encoded file content
    - `remove_background_noise` boolean: Remove background noise from the source recording before cloning.
    - `gender` 'male' | 'female', nullable: Speaker gender for default-image selection. Omit to classify the recording.
    - `age` 'young' | 'old', nullable: Speaker age group for default-image selection. Omit to classify the recording.
    - `similarity` 'medium' | 'high' | 'mel' | 'extra_high' | 'max': How closely the designed voice follows the source recording.
    - `image` union: An image of the speaker in their setting, as a JPEG, PNG or WebP image asset ID, public HTTPS URL, or base64 image. The voice is conditioned on it, including the ambience its background suggests: a quiet room keeps the voice clean, a busy street adds matching background sound. Omit it to use a default image chosen from the speaker's gender and age. Cannot be combined with `gender` or `age`.
      - AssetUrl: Asset input via publicly accessible HTTPS URL.
        - `type` 'url', required: Input type discriminator
        - `url` string, required: Publicly accessible HTTPS URL for the asset
      - AssetId: Asset input via HeyGen asset ID from the asset upload endpoint.
        - `type` 'asset_id', required: Input type discriminator
        - `asset_id` string, required: HeyGen asset ID from the asset upload endpoint
      - AssetBase64: Asset input via base64-encoded content.
        - `type` 'base64', required: Input type discriminator
        - `media_type` string, required: MIME type of the encoded content (e.g. "image/png")
        - `data` string, required: Base64-encoded file content

## Response `202`

Accepted — submission acknowledged; poll for completion.

- object
  - `data` CreateModelAudioVoiceResponse: Identifier returned after voice creation or retraining is accepted.
    - `voice_id` string, required: Stable identifier to use when retrieving the voice and its training status.

## Other responses

- `400`: Invalid request parameters
- `401`: Authentication failed
- `404`: Resource not found
- `409`: Conflict — either the request conflicts with existing state, or a prior request with this `Idempotency-Key` is still in progress (`request_in_progress`).
- `429`: Rate limit exceeded
- `503`: Temporarily unavailable — the request did not complete and is safe to retry.

## Changes

- **2026-11-03** `7dfa5e59b4f5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/heygen/apis/heygen-external-api/changes/v3/models/audio/voices/post.md)

---

[API](https://skmtc.dev/heygen/apis/heygen-external-api.md) - [All operations](https://skmtc.dev/heygen/apis/heygen-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/heygen/apis/heygen-external-api/revisions/7dfa5e59b4f5?raw)