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

# Text to Speech Audio Tags

> Direct how HeyGen Voice speaks with audio tags such as [excited], [whispers], or [laughs] in the text of POST /v3/models/audio/tts and /tts/stream.

![](https://mintcdn.com/heygen-1fa696a7/hfMXXwJzjE7vBSYZ/images/theme/research-2.webp?fit=max\&auto=format\&n=hfMXXwJzjE7vBSYZ\&q=85\&s=d6ee10585b27ddaf8137d6ed67791708)

An audio tag is an English word or phrase in square brackets in `text`. It changes how the voice speaks, or adds a sound such as a laugh. Public and instant voices perform audio tags on all three models: `heygen-voice-1`, `heygen-voice-1-turbo`, and `heygen-voice-1-turbo-free`. Both speech endpoints accept them. Professional voices do not perform audio tags.

Each tag is in one of four categories: emotion, delivery, acoustic event, or scenario. The [common tags](#common-tags) table shows what each category does.

```bash theme={null}
curl -X POST "https://api.heygen.com/v3/models/audio/tts" \
  -H "X-Api-Key: $HEYGEN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "heygen-voice-1-turbo-free",
    "voice_id": "83548de556df48ba8c09c42a57c51d85",
    "text": "[sad] I walked past our old house today. [sighs] The garden is gone.",
    "language": "en"
  }'
```

## Add tags automatically

To add tags to a script you already have, give this prompt to an LLM, with your script in place of `<your text>`. It uses only the [common tags](#common-tags).

```text Prompt wrap theme={null}
Enhance the script with HeyGen Voice delivery tags so it is performed with natural, expressive delivery.
Output the full enhanced script straightaway; do not apply any formatting, do not add any comments.

>> Allowed tags. Use ONLY these, spelled exactly as listed, lowercase, inside square brackets.

Span tags set how the text AFTER the tag is spoken, until the next span tag or the end of the chunk:
[happy], [sad], [angry], [excited], [nervous], [frustrated], [surprised], [scared], [sarcastic], [warm], [serious], [calm], [whispers], [softly], [shouts], [deep voice], [trembling voice], [stammers], [sings], [slowly], [quickly], [on the verge of tears], [trying not to laugh], [through gritted teeth], [barely containing excitement], [deadpan, dry humor], [as if sharing a secret], [like a sports commentator], [like reading a bedtime story], [voice dropping to a whisper], [building to a shout]

Moment tags are one sound or beat at that exact spot; delivery then continues in the current span:
[pause], [hesitates], [laughs], [chuckles], [giggles], [sighs], [gasps], [sobs], [sniffles], [coughs], [clears throat], [groans], [scoffs], [hmm]

>> Rules:
1. Only add tags. Never change the script's words, language, structure or punctuation: keep numbers, symbols, capital letters and spelling exactly as written.
2. Add at least 1 tag, even for a very short script. Tag where the delivery changes or a sound fits; do not tag every sentence.
3. Put exactly one tag at any spot. Never put two tags side by side; if a span tag and a moment tag both fit, choose one.
4. Change emotion gradually. Step through in-between tags instead of jumping between distant emotions, for example [excited] -> [warm] -> [serious] -> [sad], one step per sentence. Build volume and pace gradually too, for example [softly] -> [serious] -> [building to a shout] -> [shouts].
5. Synthesis splits the script into chunks of about 233 characters (about 17 seconds), and a span tag does not carry into the next chunk. When a span should continue past about 233 characters, repeat the same span tag at the start of the next sentence.
6. Tags are always English words in square brackets, even when the script is in another language. Never translate a tag.
7. Never write closing tags such as [/happy] or [end whispers]; a span ends where the next span tag starts.
8. Leave any tags and any other text in square brackets already in the script exactly as they are: do not remove, replace, move or rewrite them.
9. The script may contain SSML pause markers like {{BREAK_0}}, {{BREAK_1}}, etc. They are timing markers: preserve them EXACTLY. Do not replace, remove, or convert them into tags.

>> Examples of tags usage:
[warm] Hey everyone, thanks for joining. [excited] Today we have big news to share. [hesitates] Well, almost all of it. [serious] One of our stores is closing next month.
[calm] Breathe in slowly. [pause] And breathe out. [softly] Let your shoulders drop, and let the day go.
[excited] ¡No puedo creerlo, lo logramos! [warm] Gracias a todos por estar aquí. [on the verge of tears] Esto significa muchísimo para mí.
[as if sharing a secret] Want to know the trick? [chuckles] It costs less than $20.

>> Script to enhance:

<your text>

>> Your output (the script exactly as given, with only tags added):
```

## Listen

Every sample below is the exact `text` shown under its player. Unless a section names a different voice, one instant voice with the same settings speaks every sample.

### Same line, different tags

One script, first with no tags and then with a different lead tag. The words stay almost the same, and the tags change the delivery.

> [card] No tags
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/no-tags.mp3" />

> [card] \[calm]
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/calm.mp3" />

> [card] \[excited]
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/excited.mp3" />

> [card] \[nervous]
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/nervous.mp3" />

> [card] \[warm]
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/warm.mp3" />

> [card] \[whispers]
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/whispers.mp3" />

### One category at a time

Emotion, delivery, acoustic event, and scenario tags, each in its own script.

> [card] Emotion: nervous, relieved, excited
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/emotion.mp3" />

> [card] Delivery: whisper, loud, fast
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/delivery-volume.mp3" />

> [card] Delivery: pause and hesitation
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/delivery-pause.mp3" />

> [card] Acoustic events: laugh, sigh, gasp
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/acoustic-laugh-sigh-gasp.mp3" />

> [card] Acoustic events: gasp and laugh
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/acoustic-gasp-laugh.mp3" />

> [card] Scenario: news anchor to sports commentator
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/scenario-anchor-commentator.mp3" />

> [card] Scenario: sharing a secret
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/scenario-secret.mp3" />

### Example scripts

These scripts mix categories, with one tag at each position.

> [card] Telling a story to a friend
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/story.mp3" />

> [card] Customer support
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/customer-support.mp3" />

> [card] Ad read
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/ad-read.mp3" />

> [card] Tutorial
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/tutorial.mp3" />

> [card] Bedtime story
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/bedtime-story.mp3" />

### Accent preservation

A cloned voice keeps its accent when you add tags. The voice below was cloned from a speaker with an Indian English accent. The first player is a neutral reading with `[matter-of-fact]`. The other players are tagged lines spoken by the same voice.

> [card] \[matter-of-fact]
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/accent-indian-matter-of-fact.mp3" />

> [card] \[shy]
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/accent-indian-shy.mp3" />

> [card] \[talking to a small child]
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/accent-indian-small-child.mp3" />

> [card] \[surprised]
>
> <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/accent-indian-surprised.mp3" />

### Emotion intensity

To make an emotion weaker or stronger, put `slightly` or `extremely` in front of the emotion tag, such as `[slightly sad]` or `[extremely angry]`. This works with the emotion tags in the Feelings and Tone lists of [All supported tags](#common-tags). Each group below is one line spoken by one voice, first with no tag and then at three levels of the same emotion. The two tabs are two voices with the same lines.

> [tab] Voice 1
>
> **Sad**
>
> > [card] No tag
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-sad-no-tag.mp3" />
>
> > [card] \[slightly sad]
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-sad-slightly.mp3" />
>
> > [card] \[sad]
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-sad-tag.mp3" />
>
> > [card] \[extremely sad]
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-sad-extremely.mp3" />
>
> **Happy**
>
> > [card] No tag
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-happy-no-tag.mp3" />
>
> > [card] \[slightly happy]
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-happy-slightly.mp3" />
>
> > [card] \[happy]
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-happy-tag.mp3" />
>
> > [card] \[extremely happy]
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-happy-extremely.mp3" />
>
> **Angry**
>
> > [card] No tag
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-angry-no-tag.mp3" />
>
> > [card] \[slightly angry]
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-angry-slightly.mp3" />
>
> > [card] \[angry]
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-angry-tag.mp3" />
>
> > [card] \[extremely angry]
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-angry-extremely.mp3" />

> [tab] Voice 2
>
> **Sad**
>
> > [card] No tag
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-sad-no-tag-voice-2.mp3" />
>
> > [card] \[slightly sad]
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-sad-slightly-voice-2.mp3" />
>
> > [card] \[sad]
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-sad-tag-voice-2.mp3" />
>
> > [card] \[extremely sad]
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-sad-extremely-voice-2.mp3" />
>
> **Happy**
>
> > [card] No tag
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-happy-no-tag-voice-2.mp3" />
>
> > [card] \[slightly happy]
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-happy-slightly-voice-2.mp3" />
>
> > [card] \[happy]
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-happy-tag-voice-2.mp3" />
>
> > [card] \[extremely happy]
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-happy-extremely-voice-2.mp3" />
>
> **Angry**
>
> > [card] No tag
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-angry-no-tag-voice-2.mp3" />
>
> > [card] \[slightly angry]
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-angry-slightly-voice-2.mp3" />
>
> > [card] \[angry]
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-angry-tag-voice-2.mp3" />
>
> > [card] \[extremely angry]
> >
> > <audio controls preload="none" src="https://heygen-1fa696a7.mintlify.site/images/heygen-voice/delivery-steering/intensity-angry-extremely-voice-2.mp3" />

## How tags work

* An emotion, delivery, or scenario tag changes the speech after it. It has an effect for up to approximately 17 seconds of speech, approximately 233 characters of English. To keep the effect for a longer time, write the tag again in a later sentence.
* An acoustic event tag, such as `[laughs]` or `[sighs]`, adds one sound at its position.
* These delivery tags are exceptions. Each one acts one time at its position, as an acoustic event does: `[pause]`, `[hesitates]`, `[after a long pause]`, `[voice cracking]`, `[trailing off]`, and `[catching themselves mid-sentence]`.
* When `text` contains a tag other than `[pause]`, `expressiveness_boost` is not applied. The request is not rejected.

## Writing tags

* Write each tag in lowercase, exactly as it is in the list below, with no closing tag. `[deadpan, dry humor]` is one tag. `[sad, quietly]` is not a tag.
* To make an emotion weaker or stronger, write `slightly` or `extremely` and one space in front of an emotion tag from the Feelings or Tone list in [All supported tags](#common-tags), such as `[slightly sad]` or `[extremely happy]`. Other words, such as `[very sad]`, and other tags, such as `[slightly whispers]`, are not tags.
* Put one tag at a position. Do not put two tags side by side, such as `[angry] [whispers]`.
* Write tags in English, also when `text` is in a different language.
* Bracketed text that is not a tag, such as `[Section 4]`, is usually not spoken. To have those words spoken, remove the square brackets.
* Tags count toward the 10,000-character limit of `text`.
* Markdown is not interpreted. `**word**` does not add emphasis, so remove Markdown from `text` before you send it.

## Common tags

| Category | What it does | Tags |
| - | - | - |
| Emotion | Changes the feeling of the speech, such as anger or sadness. It does not always change how the words are spoken. | `[happy]`, `[sad]`, `[angry]`, `[excited]`, `[nervous]`, `[frustrated]`, `[surprised]`, `[scared]`, `[sarcastic]`, `[warm]`, `[serious]`, `[calm]`, `[on the verge of tears]`, `[barely containing excitement]`, `[deadpan, dry humor]` |
| Delivery | Changes how the words are spoken: volume, pace, pitch, voice quality, articulation, or pauses. | `[whispers]`, `[softly]`, `[shouts]`, `[deep voice]`, `[trembling voice]`, `[stammers]`, `[sings]`, `[slowly]`, `[quickly]`, `[pause]`, `[hesitates]`, `[trying not to laugh]`, `[through gritted teeth]`, `[voice dropping to a whisper]`, `[building to a shout]` |
| Acoustic event | Adds one sound, such as a laugh, a sigh, or a cough, at its position. You can use it in the same text as emotion and delivery tags. | `[laughs]`, `[chuckles]`, `[giggles]`, `[sighs]`, `[gasps]`, `[sobs]`, `[sniffles]`, `[coughs]`, `[clears throat]`, `[groans]`, `[scoffs]`, `[hmm]` |
| Scenario | Gives the speaking style and the emotion that fit a situation, a role, or an audience, such as `[talking to a small child]`. The tag sets the emotion and the delivery together. | `[as if sharing a secret]`, `[like a sports commentator]`, `[like reading a bedtime story]` |

> [accordion] All supported tags
>
> **Emotion**
>
> * Attitude: `[barely containing excitement]`, `[deadpan, dry humor]`, `[defensive, a little hurt]`, `[genuinely impressed]`, `[mock serious]`, `[nostalgic and wistful]`, `[passive aggressive]`, `[quietly furious]`, `[reluctantly admitting]`, `[skeptical, raising an eyebrow]`, `[trying to sound casual]`, `[with a shrug in their voice]`, `[with forced politeness]`
> * Feelings: `[amused]`, `[angry]`, `[annoyed]`, `[anxious]`, `[awestruck]`, `[bored]`, `[confident]`, `[confused]`, `[curious]`, `[determined]`, `[disgusted]`, `[embarrassed]`, `[excited]`, `[exhausted]`, `[frustrated]`, `[grateful]`, `[guilty]`, `[happy]`, `[heartbroken]`, `[hopeful]`, `[jealous]`, `[lonely]`, `[melancholic]`, `[nervous]`, `[panicked]`, `[proud]`, `[relieved]`, `[sad]`, `[scared]`, `[shy]`, `[sleepy]`, `[surprised]`, `[tender]`, `[worried]`
> * Intensity: `slightly` or `extremely` in front of any Feelings or Tone tag, such as `[slightly sad]` or `[extremely angry]`
> * Mid-line change: `[rising panic]`, `[suddenly serious]`
> * Situation: `[in disbelief]`, `[on the verge of tears]`, `[rolling their eyes]`, `[with a knowing smile]`, `[with a lump in their throat]`
> * Tone: `[apologetic]`, `[authoritative]`, `[calm]`, `[cheerful]`, `[cold]`, `[dismissive]`, `[dreamy]`, `[encouraging]`, `[enthusiastic]`, `[firm]`, `[flirtatious]`, `[gentle]`, `[matter-of-fact]`, `[mischievous]`, `[playful]`, `[reassuring]`, `[sarcastic]`, `[serious]`, `[sincere]`, `[smug]`, `[solemn]`, `[stern]`, `[suspicious]`, `[thoughtful]`, `[warm]`
>
> **Delivery**
>
> * Articulation: `[drawls]`, `[enunciating clearly]`, `[mumbles]`, `[mutters]`, `[sings]`, `[slurring]`, `[stammers]`
> * Attitude: `[as an afterthought]`, `[over-the-top dramatic]`
> * Mid-line change: `[barely audible]`, `[building to a shout]`, `[catching themselves mid-sentence]`, `[laughing while speaking]`, `[lowering their voice]`, `[singing it softly]`, `[softer than before]`, `[trailing off]`, `[voice cracking]`, `[voice dropping to a whisper]`, `[whispering urgently]`
> * Pace & pauses: `[hesitates]`, `[pause]`, `[quickly]`, `[rushed]`, `[slowly]`
> * Pitch & voice quality: `[booming]`, `[breathless]`, `[breathy]`, `[deep voice]`, `[high voice]`, `[hoarse]`, `[low voice]`, `[monotone]`, `[nasal]`, `[raspy]`, `[sing-song]`, `[squeaky voice]`, `[trembling voice]`
> * Situation: `[after a long pause]`, `[speaking through a smile]`, `[through gritted teeth]`, `[trying not to laugh]`
> * Volume & force: `[bellows]`, `[calls out]`, `[loudly]`, `[murmurs]`, `[quietly]`, `[screams]`, `[shouts]`, `[shrieks]`, `[softly]`, `[under their breath]`, `[whispers]`, `[yells]`
>
> **Acoustic event**
>
> * Body sounds: `[clears throat awkwardly]`, `[clears throat]`, `[coughs]`, `[gulps]`, `[hiccups]`, `[sneezes]`, `[sniffs]`, `[snores]`, `[snorts]`, `[yawns]`
> * Breath: `[exhales]`, `[gasps]`, `[huffs]`, `[inhales]`, `[long tired sigh]`, `[pants]`, `[sharp intake of breath]`, `[sighs]`, `[wheezes]`
> * Crying: `[muffled sob]`, `[sniffles]`, `[sobs]`, `[whimpers]`
> * Laughter: `[belly laugh]`, `[cackles]`, `[chortles]`, `[chuckles]`, `[giggles]`, `[guffaws]`, `[laughs]`, `[nervous laugh]`, `[short disbelieving laugh]`, `[snickers]`
> * Non-voice events (experimental): `[applause]`, `[claps]`, `[knocks]`, `[snaps fingers]`
> * Vocal reactions: `[exasperated groan]`, `[groans]`, `[grunts]`, `[hmm]`, `[hums]`, `[scoffs]`, `[shushes]`, `[small happy hum]`, `[tsks]`, `[whistles]`
>
> **Scenario**
>
> * Attitude: `[as if sharing a secret]`, `[quoting someone mockingly]`
> * Audience / role: `[addressing a crowd]`, `[comforting a friend]`, `[explaining to a confused customer]`, `[like a drill sergeant]`, `[like a game show host]`, `[like a late-night radio host]`, `[like a museum tour guide]`, `[like a news anchor]`, `[like a sports commentator]`, `[like reading a bedtime story]`, `[talking to a small child]`, `[teasing a close friend]`
> * Situation: `[from across the room]`, `[half asleep]`, `[into a phone, distracted]`, `[leaning in conspiratorially]`, `[walking fast, slightly out of breath]`, `[while catching their breath]`, `[with a mouth full of food]`

## Choosing a voice

For an instant voice, clone from clear speech recorded in a quiet room without echo. See [Instant Voice Clone](https://heygen-1fa696a7.mintlify.site/docs/voices/heygen-voice-instant-clone.md#1-create-the-voice).

The same tag can sound different from voice to voice. Try a tag with a few voices before you choose one.

## Tips

* A request without `seed` uses a random one, so sending the same request again gives a new take. Send the same `seed` to try to repeat a take; repeats are best effort. To steer a different performance, change the wording or punctuation near the tag and send the request again.
* You can mix tags from different categories in one text.
* Choose tags that fit the words.
* Put an acoustic event where the sound happens, such as `[laughs]` after the funny line.
* To change the mood inside a sentence, use a mid-line change tag, such as `[rising panic]`, `[suddenly serious]`, or `[voice dropping to a whisper]`.


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