Writing a voice prompt that lands: a playbook

Voice prompting on Hakim Mulhim v3 takes a free-form description and renders a voice. The model is forgiving · you can write a single adjective and it will synthesise something. But the gap between "the model produced audio" and "the audio is the voice you wanted" is wide, and prompts that close that gap follow a small set of repeatable patterns.

This playbook documents those patterns: the three-axis prompt structure, the twelve example prompts we hand to new teams, the anti-patterns that fight the model, the iteration loop that gets you from "meh" to "this is the one" in five minutes, and the language-specific notes for English and Arabic.

If you haven't read it yet, Voice prompting explained is the 101 post that introduces the capability. This one is for the team that's already running the design endpoint and wants to write prompts that land more consistently.

The three-axis structure, revisited

Every voice prompt that lands consistently covers three axes:

Axis	What it controls	Typical signal words
Identity	Who is speaking	"broadcaster", "grandmother", "teenager", "narrator"
Texture	How the voice sounds at rest	"raspy", "smooth", "low-pitched", "bright"
Scenario	Why they're speaking, with what energy	"calm bedtime story", "passionate bulletin", "intimate podcast intro"

The playground's voice-prompt drawer surfaces these as three labelled fields: Identity, Texture, Scenario. The composed description sent to the API is the three fields joined by ", " plus the optional free-form override appended on the end. You can replicate the same composition on direct API calls; the drawer is just a UI affordance, not a wire-format choice.

The reason three axes work: each one constrains a different part of the model's decision space. Identity narrows the broad-strokes timbre; texture shapes the millisecond-scale signal; scenario sets the prosody envelope over the whole utterance. Drop any one and the model fills the gap with whatever it deems plausible · which is fine, but you stop being able to predict what you'll get.

Twelve example prompts, annotated

Below are prompts we've validated produce consistent, reusable voices. Each is annotated with which axes carry the weight and why the result is what it is.

Voicebots and conversational agents

The brief: warm, low-friction, professional. The voice should feel like a helpful colleague rather than a corporate IVR.

Prompt 1 · friendly support agent

A friendly support agent in their late 20s, warm bright timbre, natural conversational cadence, helpful and unhurried.

Why it works: Identity (support agent + late 20s) anchors the register; Texture (warm bright + natural cadence) prevents the model from drifting into "news anchor" territory; Scenario (helpful and unhurried) keeps the prosody patient when the user needs a second to read an OTP.

Prompt 2 · calm IVR assistant

A calm female IVR assistant in her mid-30s, smooth mid-pitch timbre, measured pacing, professional and reassuring.

Why it works: "Mid-pitch" is the key descriptor for phone audio · brighter voices sound thinner over a 8 kHz cellular bridge. "Measured pacing" tells the model to leave space between options so callers can hear "for billing, press one" without rushing.

Prompt 3 · voice agent for a developer tool

A confident female engineer in her early 30s, crisp low-pitched timbre, direct cadence, walking through a technical problem out loud.

Why it works: Identity does double duty here · "engineer" plus "walking through a technical problem" tells the model to use the prosody pattern of someone reasoning, not someone reading. Useful for AI agents that explain their thinking.

Narration and long-form

The brief: a voice that holds up over twenty minutes. Texture matters disproportionately here; a voice that sounds great on a twenty-second preview can wear out at minute ten.

Prompt 4 · audiobook narrator (literary fiction)

A male audiobook narrator in his late 50s, deep magnetic low-pitched timbre with a slight rasp, slow deliberate cadence, intimate literary reading of contemporary fiction.

Why it works: "Slight rasp" is the crucial Texture cue · it prevents the model from over-polishing the timbre into something that reads as synthetic at minute six. "Slow deliberate cadence" gives Faseeh/Mulhim's prosody engine room to breathe.

Prompt 5 · documentary narrator

A measured documentary narrator in their mid-40s, neutral mid-pitch timbre, occasional dramatic pauses, conveying gravitas without melodrama.

Why it works: "Without melodrama" is doing real work · documentaries have a register problem where the model can drift toward news anchor or theatrical. The explicit negative constraint pulls it back.

Prompt 6 · bedtime story for kids

A warm grandmother in her late 60s, raspy gentle timbre, slow magnetic delivery, hushed bedtime register, drawing the child into a familiar story.

Why it works: Three explicit pacing cues ("gentle timbre", "slow magnetic delivery", "hushed register") tell the model to dial down energy across the board · the result reads as sleep-cue audio, not performance.

Brand voices and marketing

The brief: voice as identity. The voice should feel like a person you'd recognise in a year of audio content. Three Texture descriptors are the minimum here; brand voices are mostly Texture.

Prompt 7 · a tech-startup brand voice

A confident male founder in his early 40s, smooth low-pitched timbre, deliberate pacing, slight conversational warmth, addressing a room of developers as peers.

Why it works: "Addressing developers as peers" is a Scenario cue that tells the model to avoid the salesperson register. "Slight conversational warmth" prevents it from over-correcting into monotone authority.

Prompt 8 · a luxury brand voice

A poised female narrator in her mid-30s, refined low-pitched timbre, unhurried elegant cadence, evoking quiet confidence and craftsmanship.

Why it works: "Quiet confidence" + "craftsmanship" set a register the model has solid priors on (it's read enough Hermès copy in training). "Unhurried elegant cadence" prevents drift into news anchor pacing.

Prompt 9 · a wellness brand voice

A warm female practitioner in her early 40s, soft low-pitched timbre, slow soothing cadence, grounded mindful register, narrating a moment of stillness.

Why it works: "Narrating a moment of stillness" is a Scenario cue with specific prosodic implications · long sentences, soft consonants. Pair with [breath] non-verbal tags on the speech endpoint and you have a production-ready meditation voice.

Specialised registers

The brief: voices for specific situations where the standard registers don't fit.

Prompt 10 · sports commentator (live event)

An energetic male sports commentator in his late 30s, bright high-energy timbre, building cadence with crescendos, calling a live championship moment.

Why it works: "Building cadence with crescendos" is the Texture/Scenario hybrid that lets the model render the rising-and-falling prosody live sports needs.

Prompt 11 · classical Arabic poetry recitation

A male reciter in his early 50s, deep resonant low-pitched timbre, classical Arabic poetic cadence with extended vowels and natural caesurae, reciting from the canon with reverence.

Why it works: "Classical Arabic poetic cadence" gives the model a specific prosodic prior. "Extended vowels and natural caesurae" maps onto specific phonological behaviours the model can produce; without those cues you get prose-reading prosody, which fights the meter.

Prompt 12 · auctioneer

An animated male auctioneer in his late 40s, sharp bright timbre, rapid-fire cadence with rhythmic emphasis, calling bids at a charity auction.

Why it works: "Rapid-fire cadence with rhythmic emphasis" is exactly the right pair of cues for the auctioneer register. The model has enough auction footage in its prosody priors to produce this convincingly when the cues are explicit.

Anti-patterns

Prompts that fight the model rather than collaborate with it. We've caught all five in production prompts that didn't land.

Anti-pattern A · under-constrained one-axis prompts

A grandmother.

The model produces a grandmother voice · just not necessarily the one you wanted. Without texture and scenario, the result is unpredictable. Fix: add texture (timbre + pitch) and scenario (register + pacing).

Anti-pattern B · piling on adjectives

A warm, raspy, gentle, soft, breathy, kind, gentle, soothing, calm,
magnetic, low-pitched, smooth, polished elderly woman.

Past about ten adjectives the model starts ignoring the tail. Trim to the three or four that matter most. Counter-intuitively, removing adjectives often makes the result more consistent.

Anti-pattern C · referencing real people

A voice that sounds like Morgan Freeman.

The moderation pipeline flags this for manual review · the design endpoint returns the prompt-as-submitted into pending_manual_review, and even when approved the result is influenced by the description's general texture rather than a specific person. For "that specific person's voice" use voice cloning with consent.

Anti-pattern D · stage directions inside the prompt

A male broadcaster (he speaks fast at the start, then slows down, then
speeds up).

The prompt designs the voice; non-verbal tags + script content control prosody on a per-utterance basis. Move pacing variation into the script itself with [breath] tags and natural punctuation rather than baking it into the voice prompt.

Anti-pattern E · contradictory cues

A loud whisper of a soft shouting voice.

The model tries to obey both halves and produces an averaged register that satisfies neither. Pick one direction and lean into it.

The iteration recipe

The loop that gets you from a first-draft prompt to a saved keeper in five minutes:

Write the first prompt fast. Three axes, single paragraph, don't overthink it. Open the playground voice-design drawer with the example already loaded and adapt; you'll get to a working first draft faster than from a blank page.
Generate three samples. Same prompt, three back-to-back calls. Listen to each. Voice prompting is non-deterministic by design; the third generate is often the one that lands.
Pick the strongest sample, tweak one axis. If the texture is right but the scenario reads as too formal, swap "professional and reassuring" for "warm and conversational" and regenerate three more.
Save when the result is unambiguous. Don't oversave. A voice library with eight strong voices beats one with thirty drafts.

The five-minute heuristic: if you've spent more than five minutes on a single voice without landing it, the prompt is the problem. Step away, read the Mulhim section of the models guide for tier-specific behaviour, and come back with a fresh paragraph rather than tweaking the same one.

Language-specific notes

English prompts read most consistently when they specify a regional accent ("an American broadcaster", "a Scottish narrator", "an Australian podcast host") rather than leaving the accent ambiguous. The model has broad priors on every major English variety; specifying which one prevents drift.

Arabic prompts work best in formal MSA (الفصحى) descriptive prose regardless of the dialect you want the voice to produce. The dialect of the voice is controlled by adding "speaking in Khaleeji" or "speaking in Egyptian" as a Scenario cue; the prompt itself doesn't need to be in that dialect. We've found that prompts written in MSA produce more consistent results than prompts written in colloquial Arabic, even when the target voice is colloquial.

Bilingual content is supported on every saved voice. A voice you design with an English prompt reads Arabic text natively in the same voice; a voice you design with an Arabic prompt reads English text the same way. The dialect of the voice persists across languages, so a Khaleeji-targeted voice reads English words with the prosody patterns of a Khaleeji speaker switching to English, not a generic English-speaker's voice. This is the right behaviour for bilingual content.

Brand-consistent prompting

For teams designing a family of related voices (a podcast host + a guest intro voice + an alert chime voice, all from the same brand), keep a shared "prompt template" with the brand's Texture vocabulary pinned:

{identity, age range, role within the brand},
{2-3 brand texture descriptors that stay constant across voices},
{scenario specific to this voice's use case}.

For example, a "calm-and-deliberate" brand might pin Texture to "smooth low-pitched timbre, deliberate pacing" across every voice, and vary only the identity and scenario per voice. The result is a family of voices that feel like they belong together · the same brand personality refracted through different roles.

This is also where saving voices to the library matters most: the voice.id is the canonical handle. Even if the prompt evolves over time, the saved voice stays exactly the same render. A new prompt iteration produces a new voice; the original brand voice doesn't drift.

Saving + reusing voices across tiers

Once a designed voice is saved, it works on every tier of the Hakim TTS family · not just Mulhim. Practical pattern: design the voice on Mulhim (only tier that supports the design endpoint), then use the resulting voice.id on Saree' for runtime voicebot synthesis when latency matters, and on Faseeh for premium narration with non-verbal tags. Three tiers, one voice, the cost trade-offs you'd expect from each.

import { HakimClient } from '@hakim/node';
const hakim = new HakimClient({ apiKey: process.env.HAKIM_API_KEY });

const voiceId = 'voi_01HX...'; // the saved designed voice

// Runtime voicebot · Saree' for the latency budget.
await hakim.audio.speech.stream({
  model: 'hakim-fast-v1',
  input: 'Hi, thanks for calling. How can I help today?',
  voice: voiceId,
  response_format: 'pcm',
  stream: true,
});

// Long-form narration · Faseeh for prosody quality + tag support.
await hakim.audio.speech.create({
  model: 'hakim-v2',
  input: 'Welcome back, listeners. [breath] Today we are talking about something special.',
  voice: voiceId,
  response_format: 'mp3',
});

The same designed voice carries both registers. What changes is the tier's posture, not the voice's identity.

Common questions

Can I lock down a prompt so it always produces the same voice? No. Save the voice instead. The prompt is a description; the voice.id is the canonical reference. Once saved, the voice renders identically every time.

How many tries before I should give up on a prompt? If three generates didn't produce something usable, rewrite the prompt rather than running a fourth. Most prompts that aren't landing have a fixable issue in the wording (ambiguity, contradiction, missing axis).

Can I edit a saved voice's prompt later? The prompt is metadata on the saved voice for audit purposes, but re-running it doesn't regenerate the voice; the saved sample is the canonical render. To "edit" a saved voice, design a new one with the revised prompt and replace the reference in your application.

Does prompt length affect cost? No. Voice design is billed per design call, not per character of the prompt. Long prompts and short prompts cost the same.

How does this work in non-English non-Arabic prompts? The prompt itself is treated as descriptive text; we've tested prompts in French, Spanish, and German with strong results. The voice the prompt produces can read any of the supported speech languages regardless of the language the prompt was written in.