Create or Retrain an Audio Voice

Creates a model-backed audio voice from one or more recordings, or retrains an existing professional voice when voice_id is supplied. Retraining requires only voice_id and source audio and retains the existing voice’s ID, name, language, and mode. The voice is PENDING and unavailable for inference while either operation runs. Poll GET /v3/models/audio/voices/{voice_id} until its status becomes ACTIVE or FAILED. Idempotency-Key is optional; omitting it means repeated creation requests create separate voices. New voices require an unoccupied professional-voice slot. Each purchased slot provides five pooled trainings per monthly billing period, including initial training; failed trainings do not consume the allowance.

POST /v3/models/audio/voices

Create or Retrain an Audio Voice

cURL

curl --request POST \
  --url https://api.heygen.com/v3/models/audio/voices \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "audio": [
    {
      "type": "url",
      "url": "<string>"
    }
  ],
  "mode": "professional",
  "voice_id": "<string>",
  "name": "<string>",
  "language": "<string>"
}
'

202

Example

{
  "data": {
    "voice_id": "<string>"
  }
}

Authorizations

ApiKeyAuthBearerAuth

x-api-key · string · header · required

HeyGen API key. Obtain from your HeyGen dashboard.

Headers

Idempotency-Key · string

Optional client-supplied key for safely retrying mutations. Subsequent calls within 24 hours that share this key replay the original response — even if the request body differs slightly (a warning is logged). A retry that arrives while the original is still in flight gets a 409 request_in_progress. Keys must be 1–255 characters from [A-Za-z0-9_:.-]; a UUID is a safe default. Scope is per-endpoint and per-resource: the same key on a different route or path parameter is independent.

Required string length: 1 - 255

Pattern: ^[A-Za-z0-9_\-:.]{1,255}$

Body

application/json

Create or retrain one model-backed audio voice.

audio · (AssetUrl · object | AssetId · object | AssetBase64 · object)[] · 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.

Required array length: 1 - 10 elements

Asset input via publicly accessible HTTPS URL.

AssetUrl

AssetId

AssetBase64

Show child attributes

mode · enum<string> | null

Voice operation mode for a new voice. Ignored when voice_id is supplied; the existing mode is retained. Currently only professional is supported.

Available options: professional

voice_id · string | null

Existing professional voice to retrain. Omit to create a new voice.

Required string length: 1 - 64

Pattern: ^\S+$

name · string | null

Display name for a new voice. Ignored when voice_id is supplied; the existing name is retained.

Required string length: 1 - 256

language · string | null

Primary language code, such as en, for a new voice. Ignored when voice_id is supplied; the existing language is retained.

Required string length: 1 - 32

Response

202

application/json

Accepted — submission acknowledged; poll for completion.

data · CreateModelAudioVoiceResponse · object

Identifier returned after voice creation or retraining is accepted.

Show child attributes