> ## 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.

# Speech to Speech

> Speak a recording again in one of your instant voices with POST /v3/models/audio/sts: same words, same timing, a different voice.

`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](/docs/voices/heygen-voice-instant-clone) 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](/docs/upload-assets), 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

```bash theme={null}
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" }
  }'
```

```json Response theme={null}
{
  "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. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.