Skip to main content
POST /v3/models/audio/sts converts a recording into a voice from your workspace. The words and timing stay the same. The response contains a WAV URL and its duration. voice_id must be an ACTIVE instant voice in your workspace. Professional voice clones are not supported yet. Each workspace member can send 30 requests per minute.

Authentication

Use an API key with the voices:write permission, or an OAuth bearer token. Send the API key in X-Api-Key or Authorization: Bearer. Send an OAuth token in Authorization: Bearer. OAuth requires a paid plan and a role that permits API access.

Request fields

The full field list is in the API reference. audio is the recording to convert, as an asset ID, URL or base64. remove_background_noise defaults to false and adds latency when on. seed requests best-effort repeatable generation, and model_id takes only heygen-voice-sts-0, the default. About the recording:
  • It can be up to 300 seconds long.
  • It can be up to 100 MB as an uploaded asset, 32 MB by URL, or 16 MB as inline base64.
  • WAV, MP3, FLAC, OGG, M4A, and AAC work. For inline base64, set media_type, such as audio/wav or audio/mpeg.
  • A URL must be public HTTPS, point at the file itself, and download within 60 seconds.
  • Send clear speech. A recording that can’t be read or converted returns 400 with param set to audio.
Unknown fields and invalid values return 400 invalid_parameter, with param set to that field.

Convert speech

Conversion can take 150 seconds. No polling is needed. Set your client timeout to at least 160 seconds. The response carries audio_url and duration, in seconds, matching the recording. Successful responses include X-Request-Id; use it to find usage records. The first request can take longer while HeyGen prepares the voice. If preparation takes too long, the request returns 409 voice_not_ready. Retry after the delay in Retry-After.

Retries and disconnects

Send the optional Idempotency-Key header to retry a request safely. The key must contain 1–255 characters from A–Z, a–z, 0–9, _, -, :, and .. Use a UUID or another unique value for each new conversion. Keys are scoped to the workspace and this endpoint. A retry with the same key and body returns the completed result without another charge for 24 hours. A different body with the same key returns 409 conflict. A retry while the first request runs returns 409 request_in_progress. Wait for the Retry-After delay. With a key, conversion continues after a client disconnect and can still be charged. Without a key, a disconnect before the charge cancels the request without a charge. After 504 gateway_timeout, wait before retrying with the same key. The conversion can still be running.

Errors

Authentication, scope and rate-limit errors follow the error codes catalog. Specific to this endpoint: