> ## 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.
# 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.
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"
}'
```
## Listen
Every sample below is the exact `text` shown under its player, spoken by one instant voice with the same settings.
### 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
>
>
> [card] \[calm]
>
>
> [card] \[excited]
>
>
> [card] \[nervous]
>
>
> [card] \[warm]
>
>
> [card] \[whispers]
>
>
### One category at a time
Emotion, delivery, acoustic event, and scenario tags, each in its own script.
> [card] Emotion: nervous, relieved, excited
>
>
> [card] Delivery: whisper, loud, fast
>
>
> [card] Delivery: pause and hesitation
>
>
> [card] Acoustic events: laugh, sigh, gasp
>
>
> [card] Acoustic events: gasp and laugh
>
>
> [card] Scenario: news anchor to sports commentator
>
>
> [card] Scenario: sharing a secret
>
>
### Example scripts
These scripts mix categories, with one tag at each position.
> [card] Telling a story to a friend
>
>
> [card] Customer support
>
>
> [card] Ad read
>
>
> [card] Tutorial
>
>
> [card] Bedtime story
>
>
## 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.
* 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 5,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]`
> * 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.
## Long-form scripts
In a long script, write a tag again about every 17 seconds of speech to keep its effect, as this story does.
```text Story of a long week wrap theme={null}
[excited] Okay, you will not believe the week I just had! [laughs] It started with the best news ever. [barely containing excitement] We finally got the keys to the new studio, and I literally [gasps] screamed in the parking lot. [happy] I called my mom right away, and she was just as thrilled. [chuckles] She made me promise to send her photos of every single room. [warm] That evening we carried in the first boxes, and everything felt perfect. [calm] [sighs] We sat on the floor with takeout and just took it all in. [softly] It was quiet, and the city lights were glowing through the big windows. [hesitates] But then, um, I noticed a little puddle forming under the sink. [nervous] At first I told myself it was nothing. [stammers] I mean, it's, it's probably just a drip, right? [scared] And then the pipe made this awful rattling sound. [gasps] Water started spraying everywhere! [frustrated] [groans] I spent the next two hours on my knees with a bucket and a towel. [through gritted teeth] The landlord, of course, did not answer his phone. [angry] I called him eleven times! [scoffs] Eleven! [sarcastic] Oh sure, I bet he was very, very busy. [deadpan, dry humor] Meanwhile, my brand new floor was slowly becoming a swimming pool. [serious] By midnight, I was soaked and completely exhausted. [sad] And honestly, I was a little heartbroken. [sniffles] [on the verge of tears] All I wanted was one perfect night in our new place. [sighs] [softly] So I sat by the window and just let myself feel it. [calm] Then my neighbor knocked on the door with a wrench and a flashlight. [surprised] [gasps] She had fixed the exact same pipe last year! [happy] [laughs] Ten minutes later the leak was gone, and we were sharing cookies on my wet floor. [trying not to laugh] She even said the puddle gave the room some character. [warm] [chuckles] So yeah, rough start, but I think we are going to love it here.
```
## Tips
* The same voice, `text`, and settings give the same speech each time. `seed` is ignored for instant voices, so sending the same request again does not give a new take. To hear 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. Do not put two tags side by side.
* 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]`.
## Add tags automatically
To add tags to a script you already have, give this prompt to an LLM, with your script in place of ``. 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 output (the script exactly as given, with only tags added):
```
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.