Speech to Speech

POST /v3/models/audio/sts takes a recording of someone speaking and returns the same speech in a voice from your workspace. The words and timing stay the same. You get one WAV, as long as the recording. voice_id must be an ACTIVE instant voice in your workspace. Professional voice clones are not supported yet. API keys need the voices:write permission. Each workspace member can send 30 requests per minute.

Request fields

Field	Type	Required	Description
`voice_id`	string	Yes	An `ACTIVE` instant voice owned by the API key’s workspace.
`audio`	object	Yes	The recording to convert: `{ "type": "asset_id", "asset_id" }`, `{ "type": "url", "url" }`, or `{ "type": "base64", "media_type", "data" }`.
`remove_background_noise`	boolean	No	Clean the recording before converting it. Default `false`. This makes the request take longer.

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

curl -X POST "https://api.heygen.com/v3/models/audio/sts" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "voice_id": "7c2a9e4f1b3d4e6a8f0c2d4e6a8b1234",
    "audio": { "type": "url", "url": "https://example.com/recording.mp3" }
  }'

Response

{
  "data": {
    "audio_url": "https://files.heygen.ai/generated/speech-conversion.wav",
    "duration": 12.48
  }
}

The request stays open until the WAV is ready, for up to 150 seconds, so no polling is needed. Set your client timeout to at least 160 seconds. duration is in seconds and matches the recording. Successful responses include an X-Request-Id header; use it to match usage records. The first conversion with a voice can take longer while HeyGen prepares the voice for speech to speech. If that runs long, the request returns 409 voice_not_ready with a Retry-After header. Send the same request again after that delay. You are charged by the length of the output audio, per second. A request that fails, or that you close before the audio is ready, is not charged.

Errors

HTTP status	Error code	Meaning
`400`	`invalid_parameter`	Missing or unknown field, or an invalid value. `param` is `audio` for a recording that is longer than 300 seconds, too large, empty, or can’t be read. `param` is `voice_id` for a professional voice clone.
`401`	`unauthorized`	The API key or OAuth token is missing or invalid.
`402`	`insufficient_credit`	The API credit balance does not cover the recording’s length.
`403`	`insufficient_api_key_scope`	The API key does not have the `voices:write` permission.
`404`	`voice_not_found`	The voice is not in the caller’s workspace.
`409`	`voice_not_ready`	The voice is still being created or prepared. Retry after the seconds in `Retry-After`.
`409`	`voice_training_failed`	The voice is `FAILED`. Don’t retry; use another voice.
`429`	`rate_limit_exceeded`	Retry after the seconds in `Retry-After`.
`500`	`internal_error`	The conversion failed.
`503`	`service_unavailable`	Speech to speech is busy, or the recording’s URL or asset did not download in time. Retry after the seconds in `Retry-After`.
`504`	`gateway_timeout`	The conversion did not finish within 150 seconds. It may still be running, so wait before you retry.

Auth

User Info

Models

Video Generation

Video Composition

On Brand

Realtime Video

Avatar Management

Voice Management

Video Translation

Lipsync

Tools

Asset Management

Batches

Webhook

Limits

Socials

For Agents

Integrations

Request fields

Convert speech

Errors

​Request fields

​Convert speech

​Errors

Request fields

Convert speech

Errors