Human-Sounding Voiceover with Claude Code — MiniMax Voice Cloning + a Script Methodology

Start with that first stretch of the video.

That’s an intro to the third generation of Nano Banana, Google’s image tool, just released. But listen closely to the narrator’s voice — it isn’t me reading into a microphone. It’s my own voice, cloned, generated by Claude Code calling MiniMax’s TTS.

It’s a bit different from the AI voices we’re used to hearing: the timbre carries a lot more sibilance, the rhythm and pauses of the speech feel natural, and there’s a sense of breath between the sentences.

Why MiniMax

Everyone knows MiniMax, and it isn’t just large language models — their TTS voice model is the best one I’ve tested to date.

Step 1: setup and configuration

MiniMax has a China platform and an international one, and I’ve put both addresses in the video.

Once you’re in: top up, generate an API key from the access page, save that key string to a local notepad file, then drag that file into the Claude Code window and you can start making calls.

The best-performing model is speech-2.8-hd. It’ll show you how to call it, but we don’t have to learn any of that ourselves — just find the text to speech (T2A) documentation page on MiniMax’s site and copy the contents, or hand Claude Code the URL directly, and it works out how to call it in code on its own.

What actually matters: how you prepare the script

To make the voice more convincing, MiniMax calls support a lot of custom parameters. This part is the real substance, and it’s what isn’t in the official docs — what I figured out the hard way.

Pauses. Use a marker like <#seconds#> to insert pauses between punctuation, at sentence transitions, and at points of emphasis. MiniMax adds small pauses on its own, but not enough, so I worked out a scheme — an extra 0.2 to 0.3 seconds at the ends of long sentences and wherever emphasis is needed. Careful not to scatter them randomly; the more you add, the faker it sounds.

Speed. From my testing, 1.2x to 1.3x is the most comfortable.

Emotion. Leave it unspecified and it runs in auto mode, matching emotion to the meaning of the text, and auto is usually great. You can also pick happy, sad, disgusted, or surprised, but in testing they all come out a bit overdone and aren’t useful — what is useful is auto, natural, and calm.

Embedded tags. The API supports a lot of parenthetical tags that add “humanness.” What tested well is (breath), plus inhales, a dismissive snort, a lip smack, that family. The ones on the right side of the list — laughs, throat-clearing — pull you right out of it; they sound unnatural, so avoid them. So when I explain the logic to Claude Code, I tell it explicitly which tags it can weave in and which it can’t.

Homographs. You can pin a pronunciation using pinyin plus a tone number. Take a surname like Shan in “Shan laoshi” — the TTS may pick the wrong reading for the character; pinyin plus a tone digit corrects it. For characters it consistently gets wrong, you can also substitute a homophone.

Compound words read as one unit. I used to do a lot of medical-explainer voiceover, and I constantly hit very long terms — semaglutide, omeprazole enteric-coated capsules. Long words like those need to be wrapped in double pound signs so the model reads them as one unbroken unit.

Digits spelled out. Long number strings, phone numbers, and years frequently get read wrong. Just have Claude Code convert the digits into written-out Chinese before sending, and you avoid it. Which of the two Chinese words for “two” to use in a given context, and how to chunk long text for streaming output, are in there too.

I’ve written the whole thing up as a document and put it in the downloads section. Download it, hand it to your Claude Code, and it has learned my whole approach to generating speech.

Demo: one sentence, one finished voiceover

With the key and this methodology in place, all I have to say inside Claude Code is:

Generate me a random 200-character short story, use the MiniMax speech-2.8-hd model with my own voice and our speech-generation methodology, turn it into an audio file, and play it as soon as it’s converted.

It came back fast — a short story about a late-night secondhand bookstore, its owner Old Zhou, and a gray-covered notebook, read in my voice.

How to clone your own voice

Simple: record ten or twenty seconds of your own voice on your phone with no background noise, drag it into the Claude Code window, and tell it to go clone that voice on MiniMax. It clones it right there.

One thing to watch: voices cloned through the API are only kept for 7 days, and get cleaned up if unused within that window. No big deal though — as long as you keep the original audio file, you can re-clone any time.

One easter egg

You may have heard it too: when my Claude Code finishes a task, it plays a clip saying “task complete, awaiting instructions” — also generated with MiniMax, wired in through hooks. That way, with several windows open, one listen tells me something finished and it’s time to go look.

That’s it for today. Questions in the comments.

Source: EP0026_audio.mp3 · ASR model gemini-2.5-pro (chunked parallel) · full text of the roughly 10-minute original recording

[00:00] Come on, friends. Today I’m going to teach you how to use Claude Code to generate smooth, real-sounding human voice audio. Let’s start with a sample.

[00:10] Google’s AI image tool Nano Banana just shipped its third generation. The biggest change this time: Chinese text finally isn’t garbled. The first generation came out last August — the images looked good, but the Chinese was all scribbles. The Pro version fixed the Chinese.

[00:22] You can hear it — this voice is pretty different from the generated AI voices we’re used to hearing. First, the timbre has a lot more labiodental sound in it. Then its speaking rhythm, including the pauses, is very natural. And between every sentence it actually adds a sense of breathing.

[00:44] So how do you generate audio like that? What we’re using is MiniMax. You’ve all heard of MiniMax — it doesn’t just have large language models. Its human-voice TTS model, the model that generates voice, is the best one I’ve tested so far.

[01:03] As for the whole method, here are the steps I’ve laid out. Step one is hooking it up and configuring it. MiniMax actually has a China version and an international version — I’ve put both platform URLs right here. Once you’re in, first we need to get an API key. You have to top up your balance first, and after that you generate the API key from access. Once it’s generated, you can save that API key string into a local notepad file, drag that notepad file into the Claude Code window, and then we can call the model.

[01:46] Within MiniMax’s TTS models, the one with the best results right now is speech-2.8-hd. And this model comes with documentation on how to call it, but in practice we don’t need to learn the call format at all. We just go to MiniMax’s official site, find the text to speech, T2A, docs page, and copy the entire contents of that page — or just hand the page URL to Claude Code — and it can go learn how to call this model in code directly.

[02:25] To get more realistic voice generation, MiniMax supports a lot of custom parameters when you call the model. Normally we’d send it a stretch of continuous natural-language text, right? And within that text, if we add certain tags or special symbols, they actually carry a lot of meaning. For example, what’s shown here is an angle bracket, then a pound sign, with a number in decimal seconds in between — that means: at this point in the text, pause for that long.

[03:05] And you’ll often add pauses between punctuation marks, at transitions from sentence to sentence, or on emphasis, to make it feel natural. Of course, MiniMax’s own generated audio does add some small pauses, but it doesn’t add enough. So I worked out a whole scheme for adding an extra 0.2 or 0.3 seconds of pause at, say, the end of long sentences, or wherever it judges an emphasis pause is needed.

[03:36] Likewise, when generating audio, MiniMax also lets us set what speaking rate to generate at. From my testing so far, 1.2x to 1.3x is a comfortable rate.

[03:53] Then this MiniMax model also supports an emotion component. If we don’t specify anything for emotion, it runs in auto mode — it matches an emotion based on the meaning of the text. Generally speaking, its auto match is already very usable. Of course you can also pick your own, using expressions like happy, sad, disgusted, surprised — but in my testing they all come out a bit exaggerated, none of them are that usable. Only auto mode, plus the natural and calm modes, are pretty usable. You can go test it yourself.

[04:39] Beyond those, you can also add embedded tags in parentheses. You can see a lot of them listed here, because officially there’s support for a huge number of embedded tags for boosting so-called human feel. But after my actual testing, some of them are usable — for example breath, which gives a sense of breathing, and then there’s inhaling, there’s a scornful hmph, or some labiodental, lip-smacking sounds. Those are usable and normal.

[05:08] Relatively speaking, the ones listed on the right — things like laughing, or clearing your throat — those are a bit too much, too far out of character, and you don’t use them often. Even when you do, they come out very unnatural. So those are the tags to avoid. So when I was explaining my usage logic to CC, I had to tell it which tags can be woven into the text and which ones shouldn’t be.

[05:42] That includes using pinyin plus a tone number to replace characters with more than one reading, so it reads the right sound. Take something like “Shan laoshi” — the TTS might read that character with its other reading and give you “Dan laoshi” instead. To make it read as Shan, you can pin the pronunciation with pinyin plus a tone digit. And further on, if certain characters keep coming out wrong, you can also substitute a homophone for that character.

[06:13] Then there’s compound words read as one unit. For example, I used to generate a lot of medical-explainer voiceover scripts, so I constantly ran into very long terms — semaglutide, say, or omeprazole enteric-coated capsules. Long words like those need to be wrapped in double pound signs, so the model recognizes them as one long word to be read straight through.

[06:42] And there are other lessons. Including long digit strings — the model often reads a phone number out as individual digits. All we have to do is have Claude Code convert that long digit string into spelled-out numerals before sending it to the model, and that avoids the problem. Including how years get read, which sometimes goes wrong — converting to spelled-out years guarantees the pronunciation is the one we want. Including the convention for er versus liang, the two ways of saying “two,” and the chunking strategy for long streaming output.

[07:25] And a file like this — none of it comes from the official docs. This is all experience from my daily use. I’ve put this document up on my site too, and once you download it, hand the file to your Claude Code and it can learn my whole set of voice-generation lessons.

[07:43] So with all of that in place, we can go into Claude Code and give it the key. Give it the lessons too. And all I have to say is: generate me a random 200-word short story. Then use the MiniMax speech-2.8-hd model, use my own voice, and use our voice-generation methodology to turn it into an audio file. And once the conversion is done, play it back for me directly.

[08:16] I just say that to CC inside Claude Code and it can generate a piece of audio like this very fast. Then let’s look at the result. (Late at night, one lamp was left on in the old bookshop. The owner, Old Zhou, had a habit of walking one more loop around the shelves before closing, like saying goodnight to old friends. That day, in the very back, he found a gray-covered notebook with no title. He opened it: a stranger’s handwriting inside, recording thirty years of this city’s rain. The last page said, if you’re reading this, please go for me and see whether that old locust tree in the south of the city is still standing. Old Zhou closed the notebook, and early the next morning he really did go to the south side. The locust tree had been cut down long ago; a bus stop sign stood in its place. He stood there a long while. When he got back, he added a line in the blank space of the notebook, and put it back where he’d found it.)

[08:59] So you can already hear it — it did that reading in my own voice. And how do you clone a voice? It’s actually very simple. All you do is record ten or twenty seconds of your own voice on your phone, with no noise, drag it into the Claude Code window and tell it: I want to clone this voice on MiniMax. And it can clone it straight away.

[09:24] But a voice cloned through MiniMax’s API is only kept for seven days — meaning within those seven days, if you don’t use it, it gets cleaned up. That doesn’t really matter though. As long as we still have the original voice file, we can just have it cloned again.

[09:38] And you also heard earlier that when my CC finishes a task, it plays a bit of audio saying “task complete, awaiting instructions.” That’s actually generated with MiniMax too, and then wired in via hooks. That way, when I’m working across multiple windows, I know a task has finished and I need to go look.

[09:56] That’s it for today. If you have questions, see you in the comments as usual. Bye-bye.