Steering

Steering lets you direct how a voice speaks with natural-language instructions. Control articulation, pitch, speed, volume, and other aspects of delivery to make speech sound more natural and expressive.

Think of it as giving direction to a voice actor. Wrap your instructions in square brackets and place them before the text they apply to. No markup languages or numeric parameters required.

How instructions work

This is the same convention as a stage direction in a screenplay. Once (shouting) appears, every line after it is shouted until a new direction says otherwise. A [tag] behaves the same way: it takes effect at the point you write it and stays in force for the rest of the text.

To end a styled passage, write [reset]. To switch to a different style, just write the new tag.

What does not change the instruction

An instruction stays in force until you change it. None of the following ends it:

• The end of a sentence or a paragraph break. Instructions are not scoped to a sentence.
• Very long input text. Long input is internally split for synthesis, and every part inherits the instruction in force.
• A <break/> pause. See Pause Controls — a pause is a pause, and never alters delivery.
• A non-verbal tag. [laugh] inserts a sound; it does not clear a style.

Only another [tag] or [reset] changes the instruction.

Ending an instruction with [reset]

[reset] removes the active instruction for the rest of the text.

[say slowly with a trembling voice] I don't think we're alone in here. [reset] Anyway, the report is on your desk.

A few details worth knowing:

• [reset] is never spoken. Like every instruction tag, it is removed from the text before synthesis.
• It is case-insensitive. [Reset] and [RESET] work the same as [reset].
• It removes the instruction, not the voice. A voice whose own character is angry or breathy stays that way after a reset. [reset] returns the voice to itself, not to a flat, emotionless read — which is exactly why it is not called [neutral].
• It is not final. A later tag takes over and persists in turn: [reset] One. [whisper] Two. Three. speaks the first sentence normally and whispers the other two.
• In a run of adjacent tags, the last instruction wins. [whisper] [reset] Hi. clears the instruction; [reset] [whisper] Hi. whispers. Non-verbal tags in the run are unaffected: [reset] [laugh] Hi. clears the instruction and keeps the laugh.

Free-form turn instructions

Describe the full character of a delivery in natural language, like a director coaching an actor before a take. A single instruction can capture emotion, energy, pacing, and intent all at once. The more fully you describe the delivery — layering mood, physical manner, and intent — the more precisely the voice will perform.

[speak as if barely holding back rage forcing every word through gritted teeth] I have told you. Repeatedly. And you STILL didn't listen.

[overwhelmed with excitement and barely able to contain yourself] We just hit a million users. I still can't believe it — we actually did it!

[slow and hushed with every word weighted by grief] I got the call this morning. He's gone.

Metadata-based instructions

Single-property instructions that target one aspect of delivery at a time. The examples below are starting points — feel free to experiment with your own natural language phrasing.

• Articulation: How words are shaped and delivered — add force, crispness, or deliberate rhythm.

  Examples: [say with force] [articulate clearly] [say with deliberate pauses]

  [articulate clearly] Each step must be followed in order. Do not skip ahead.

• Intonation: Controls how pitch moves through a phrase — whether it lands decisively or stays open-ended.

  Examples: [say with a falling pitch] [say with a rising pitch]

  [say with a falling pitch] That's my final answer. I'm not changing my mind.

• Volume: The overall amplitude of the voice, from barely audible to a full, room-filling projection.

  Examples: [very loud] [very quiet]

  [very quiet] Don't make a sound. There's someone right outside the door.

• Pitch: The baseline register of the voice — lower for gravity and weight, higher for energy and presence.

  Examples: [say in a low tone] [say in a high pitch]

  [say in a high pitch] We just got the green light, the product launches tomorrow!

• Range: How much pitch varies across the utterance — flat for monotony, expressive for warmth or playfulness.

  Examples: [say playfully] [say with no pitch variation]

  [say playfully] So anyway, I was telling her about the trip, and she just laughed the whole time.

• Speed: The speed of delivery — faster for urgency and tension, slower for weight and clarity.

  Examples: [very fast] [very slow]

  [very fast] Run, they're right behind us, don't stop, keep moving!

• Vocal style: Changes how the voice itself sounds — shifting from normal speech into a different mode like whispering or singing.

  Examples: [sing joyfully] [whisper in a hushed style] [give a nasal quality]

  [sing joyfully] The sun is rising and the world feels new, everything I dreamed is finally coming true.

Reasoning

Reasoning writes the steering instruction for you. Turn it on, and a language model reads your text before synthesis and writes a short instruction for how it should be delivered, such as [say it with quiet relief]. When the text needs no direction, it writes none and the voice reads the text as written.

Turn it on

Set synthesisContext.reasoning to REASONING_ON. For long-form audio, such as an audiobook chapter or a narrated lesson, send it on a Synthesize speech (async) job:

curl -s 'https://api.inworld.ai/tts/v1/voice:synthesizeAsync' \
  --header "Authorization: Basic $INWORLD_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
    "text": "The house was quiet when Mara got home. She set her keys on the table and smiled at the flowers her sister had left. Then she saw that the back door was open.",
    "voiceId": "Dennis",
    "modelId": "inworld-tts-2",
    "audioConfig": { "audioEncoding": "MP3" },
    "synthesisContext": {
      "reasoning": "REASONING_ON",
      "reasoningContext": "Narrator of a psychological thriller audiobook."
    }
  }'

The response names the job's operation. Poll it and download the audio as in Synthesize speech (async).

On a Synthesize speech or Synthesize speech (streaming) request, set the same field:

{
  "text": "We made it. I honestly didn't think we would.",
  "voiceId": "Dennis",
  "modelId": "inworld-tts-2",
  "synthesisContext": {
    "reasoning": "REASONING_ON"
  }
}

This response carries the instruction Reasoning applied in reasoningInstruction. On Synthesize speech (streaming), it is on the first message only. It is absent when Reasoning wrote no instruction.

Reasoning on async jobs

• It reads your context. Reasoning reads your reasoningContext and previousRequests along with the text.
• Your first inline tag ends it. From the first [tag] in the text, [reset] included, your tags direct the rest of the job and Reasoning writes no more instructions.

When Reasoning runs

• Your inline tags still win. A [tag] in the text takes over from where it appears, and the generated instruction does not come back after it. See How instructions work.
• It never blocks synthesis. If Reasoning cannot write an instruction in time, the request is synthesized without one.
• On Synthesize speech and Synthesize speech (streaming), it adds a short step before synthesis starts, so the first audio arrives slightly later than without it.

Give it context

The text alone can't say what scene it belongs to. Describe the scene or the character in synthesisContext.reasoningContext, next to reasoning, and Reasoning reads it when it writes the instruction:

{
  "text": "Don't open that door.",
  "voiceId": "Dennis",
  "modelId": "inworld-tts-2",
  "synthesisContext": {
    "reasoning": "REASONING_ON",
    "reasoningContext": "Protagonist in a psychological thriller, alone in the house at night.",
    "previousRequests": [
      { "text": "Did you hear that?" }
    ]
  }
}

• reasoningContext is up to 600 characters. Longer context is rejected with INVALID_ARGUMENT.
• It is never spoken and is not billed. It is read only when Reasoning runs.
• Put earlier lines of the conversation in previousRequests, not here. See Give the model conversation context.

Keep a delivery you like

Each request is directed on its own, so the same text can be directed differently on another request. To keep a delivery, put the returned reasoningInstruction in brackets at the start of the text and leave synthesisContext.reasoning unset.

Non-verbals

Insert organic, human sounds at any point in the text to add realism.

[clear throat] If I could have everyone's attention, please.

I told him what happened, and he just [laugh] couldn't believe it!

Non-verbal tags and instruction tags share the same [bracket] syntax but behave in opposite ways:

Only the list below determines whether a bracketed tag is a non-verbal or an instruction. A tag that names a recognized sound is a non-verbal. Anything else in brackets is treated as an instruction.

Recognized sounds

The most reliable non-verbals — and the ones to reach for first — are [laugh] [breathe] [clear throat] [sigh] [cough] [yawn].

The full set of recognized sounds is below. Matching ignores case, spacing, and punctuation, and accepts common inflections, so [Clear Throat], [clear_throat], [clears throat], and [throat clearing] all resolve to the same sound.

Emphasis

Capitalize letters within your input text to draw attention to specific words or syllables. Fully capitalizing a word stresses the entire word, while capitalizing individual letters within a word emphasizes a specific syllable.

I told you NOT to open that door.

Are you seriously asking if I want pizza? AbsoLUTEly I do.

Common gotchas

Best practices

Write instructions in English. Steering instructions must be in English regardless of the language of the input text. For best results, avoid capital letters and punctuation in your instructions. For example, [say quietly in a low tone with deliberate pauses] Bonjour, je suis ravi de vous rencontrer.

Use free-form descriptive instructions for maximum control. The more you describe how you want the voice to perform, the better the output. A bare tag like [sad] gives the model one dimension to work with. A fuller instruction like [say sadly with deliberate pauses in a low voice and hushed style] combines mood, rhythm, pitch, and mode — producing a more nuanced and convincing performance.

Avoid conflicting instructions. Combining opposing directions, for example [whisper in a hushed style] and [very loud] in the same tag, produces unpredictable results. Use one clear instruction per tag.

Match the instruction to the text. The content being spoken should be consistent with the delivery style. A mismatch like [say sadly] applied to This is the happiest day of my life, I just landed my dream job and fell in love! sends contradictory signals and may degrade output quality.

Change the instruction only where the delivery should change. Because a tag persists, one tag at the start is enough for a passage that keeps a single delivery. Add a tag mid-text when the performance shifts, and [reset] when it should return to normal. Re-tagging every sentence gives the model less continuity to work with and can make delivery uneven.

Use pause controls for longer pauses. Use pause controls if you want to add longer pauses for added emphasis.