Voice instruction prompting

Write performance instructions for text to speech, with examples and a workflow for your own LLM.

Use instructions to direct a passage in natural language: describe the situation, intent, and delivery. Two or three useful decisions are often enough. Voice Design creates a voice; instructions shape its performance.

Quick example

Send the spoken words in text and the performance direction in instructions to POST /v1/text-to-speech/{voice_id}:

{
  "text": "I can’t believe you brought him here!",
  "instructions": "Say it whispering, very quiet and tense, as if you are afraid of being overheard.",
  "voice_settings": {
    "guidance_scale": 2
  }
}

Replace {voice_id} with a voice available to your account. TTS guidance belongs inside voice_settings.

Write instructions in the same language as the input text, consistent with language_code when specified. Instructions are not automatically translated. See expressive controls.

Writing instructions

Start with the spoken words, then combine whichever dimensions help direct the passage:

• Situation: Give a circumstance that affects delivery, such as hiding from someone nearby or comforting a worried friend.
• Intent: Describe what the speaker wants: to reassure, persuade, warn, or conceal. Reassurance and a hidden threat can both sound calm, but carry different intent.
• Emotion and intensity: Name the emotion and its boundary: “restrained panic,” “mild impatience,” or “urgent but not panicked.”
• Rhythm and emphasis: Specify pace, pauses, breath, or emphasis: “Emphasize ‘right now’ without shouting.” This guides performance, not exact timing.
• Physical and vocal state: Connect a state to its sound: “breathless from running” or “holding back tears, with a cracked voice.”

You do not need all five. For a consistent voice identity, describe age, accent, and core texture primarily through voice selection or Voice Design.

Same text, different performances

Each example uses the same text:

I can’t believe you brought him here!

Change instructions to guide a different interpretation.

Whispered and afraid of being overheard

Say it whispering, very quiet and tense, as if you are afraid of being overheard.

Excited surprise

Say it excitedly, with bright surprise and rising energy, as if his arrival is wonderful and completely unexpected.

Sarcastic disbelief

Say it sarcastically, with dry disbelief and a dismissive tone, as if this was obviously a terrible idea.

Nervous humor

Say the line with a nervous laugh after the first phrase, as if trying to hide panic behind humor.

Restrained grief

Say it while holding back tears, with a cracked voice and emotional pauses, as if bringing him here deeply hurt you.

Guidance

voice_settings.guidance_scale controls how closely the output follows your instructions and the reference voice. Higher values strengthen guidance; lower values relax it. For expressive passages, try 1–3 as a starting range. For continuous narration, start at 1 and audition 1–2. The accepted range is 1–10; these starting points are not defaults or guarantees of quality.

Combining instructions with audio tags

Instructions describe performance, including local changes; Audio tags mark vocal events at positions in text, not exact timestamps—see the reference for supported tags, languages, and models.

Write instructions with your own LLM

Your existing LLM in Codex, Claude Code, Cursor, or another agent harness can write the instructions. Drafting does not require a BreezeBlue API call. Give the model the spoken text, speech language, scene, listener, and intended effect. Use this prompt in your harness:

Write a concise TTS performance instruction for the passage below.
Keep the spoken text unchanged. Write the instruction in the same language
as the passage. Choose two or three useful directions: situation, intent,
emotional intensity, pace, emphasis, or physical vocal state.
Avoid contradictory directions, identity changes, and exact timing promises.
Return only a JSON object with "text" and "instructions".

Speech language: English
Scene: A friend has brought an unwelcome guest to a private gathering.
Listener: The friend, standing close by.
Intended effect: Conceal anger because the guest might overhear.
Text: I can't believe you brought him here!

Review the result before sending it to TTS. Keep instructions within 1,000 characters. Reject invented dialogue, unsupported audio tags, or directions that contradict the selected voice. For multiple passages, preserve the voice identity and adapt the delivery to each passage instead of repeating the same emotional direction everywhere.

Pass the reviewed instruction to the CLI; replace YOUR_VOICE_ID with an available saved voice ID:

breeze tts --text "I can't believe you brought him here!" \
  --voice YOUR_VOICE_ID \
  --instructions "Speak quietly with restrained anger, as if the unwelcome guest might overhear. Emphasize 'him' without raising your voice." \
  --language en --guidance-scale 2 \
  -o performance.mp3 --agent

Generation consumes credits. Listen for the intended emphasis, emotion, intelligibility, and voice continuity. Change one direction at a time if the result misses the brief. A successful API response verifies generation, not the quality of the performance.

Next steps

Text to speech

Generate speech with HTTP, SDKs, or asynchronous jobs.

Convert text to speech

Generate audio when you do not need word timestamps.

Voice Design prompting

Describe a reusable voice identity and write a representative preview script.

CLI scripting and agents

Let your existing agent write instructions and run the Breeze CLI.