Here's the goal: you type one sentence into Claude Code, and a minute or two later there's a video of your AI avatar saying it, in your voice, sitting in your folder. (Your AI avatar is a talking video of you, made by HeyGen from your own photo and voice.)
This is the one connection most “Claude + HeyGen” videos skip past: Claude Code driving HeyGen's command-line tool, with a dry run before every render so nothing spends credits by surprise. It's the avatar step of my full content engine, pulled out on its own.
The easy way: let Claude set it up with you
Do the two HeyGen steps in the browser first (the avatar and the voice, under “Set up HeyGen” below). Then paste one prompt into Claude Code and it walks you through the rest: installing HeyGen's command-line tool, logging in, finding your ids, a dry run, and your first real clip, waiting for your yes before anything spends a credit.
mkdir -p ~/avatar-studio/out
cd ~/avatar-studio
claudeHi Claude. Please be my patient setup helper. I don't code: one step at a time, tell me exactly what to type, and wait for me.
Goal: you render videos of my HeyGen avatar from one sentence, using HeyGen's command-line tool (the heygen CLI), in this folder. Follow this guide; its manual-way sections are the source of truth for every command:
https://receiptsgroup.com/guides/claude-code-heygen
I've already made my avatar from my own photo and cloned my voice in HeyGen.
Steps:
1. Install the heygen CLI and help me log in with: heygen auth login --oauth (I do the browser part).
2. Find my avatar's look id and my voice id (heygen avatar looks list, heygen voice list). Save them in CLAUDE.md under "My HeyGen ids". They're ids, not secrets, but never print anything from ~/.heygen.
3. Write CLAUDE.md from the guide's box, with my ids filled in.
4. Dry run: build the request for the line "This is my first video made from one prompt." and show it to me. Don't send it.
5. Only after I say yes: render it with heygen video create --wait, then download it to out/first.mp4.
Rules: Avatar IV every time. 9:16, 1080p unless I say otherwise. Never render without showing me the request and getting my yes. Never use anyone's face or voice but mine. Never print or ask for keys or tokens.How the pieces connect
This is the manual way: every step and every command. Claude follows it too.
- 1Your sentenceYou, typing into Claude Code→ the line to say
- 2The requestClaude Code builds it from CLAUDE.md's rules→ a JSON request you read first (the dry run)
- 3The renderheygen video create --wait (Avatar IV, your look, your voice)→ a video id, credits spent
- 4The downloadheygen video download→ out/<name>.mp4
- 5Your editAnything, or HyperFrames (my content engine guide)→ the finished video
Words you'll see
- CLI: a command-line tool. HeyGen's is called
heygen. - Look id / voice id: the names HeyGen's tool uses for your avatar and your cloned voice. Not secrets.
- Avatar IV: HeyGen's engine that animates a photo avatar. We name it in every request so a default changing on HeyGen's side can't swap it.
- Dry run: build and show the request, send nothing, spend nothing.
Set up HeyGen (in the browser)
Pick a plan
Creator is where voice cloning and 1080p show up ($29 a month at list price, checked 2026-10-04; check HeyGen's pricing page before you buy).
Make your avatar
Open the Avatars tab, choose New Avatar, then Upload Photo. Use a photo of you: eyes, mouth and lips clearly visible, your face filling a good part of the frame. Name it and submit. It has to be validated before you can use it.
What you'll seeHeyGen's Avatars tab: New Avatar, then Upload Photo. Clone your voice
Open Voices, click + New Voice, then Create New Voice, and pick Instant Voice Cloning. Record or upload a clean sample of you talking in a quiet room. HeyGen's tip: mic 6 to 8 inches from your mouth, not rubbing on your shirt.
PermissionsYou're giving HeyGen your face and voice to model. Their docs cover what they store and how to delete it.
Connect Claude Code to HeyGen
Install Claude Code
Skip this if
claude --versionalready prints a version. You need Claude Pro, Max, Team or Enterprise.curl -fsSL https://claude.ai/install.sh | bash # open a NEW terminal window, then: claude --versionInstall HeyGen's command-line tool and log in
Two ways to log in, and they bill differently. OAuth (
heygen auth login --oauth) is a browser sign-in, and renders use your plan's credits. An API key bills a separate pay-as-you-go balance. Pick one; the tool keeps one login at a time.curl -fsSL https://static.heygen.ai/cli/install.sh | bash heygen auth login --oauth heygen auth statusPermissionsOAuth opens a HeyGen sign-in in your browser and asks you to approve the tool on your account. The login is saved in~/.heygen/credentials: never share that file or show it on screen.Find your two ids
Both commands print JSON. Find your avatar by the name you gave it and copy its look id; find your cloned voice and copy its id.
heygen avatar looks list heygen voice listWrite CLAUDE.md: the rules Claude follows every time
This is what makes it safe to hand Claude the keys to your credits: it reads this file at the start of every session.
# My avatar studio This folder turns a sentence into a video of my HeyGen avatar, using the heygen CLI. ## My HeyGen ids (not secrets) - Look id: <your look id> - Voice id: <your voice id> ## Every render 1. Build the request first and show it to me (the dry run). Wait for my yes. 2. Always: "type": "avatar", my look id and voice id, "engine": {"type": "avatar_iv"}, "aspect_ratio": "9:16", "resolution": "1080p", unless I ask for something else. 3. Render with: heygen video create -d '<the JSON>' --wait 4. Download with: heygen video download <video id> --output-path out/<short-name>.mp4 --force 5. Tell me the file and its length when it's done. ## Never - Never render without my yes. Every render spends credits. - Never use anyone's face or voice but mine. - Never print, copy or open anything in ~/.heygen, .env, or any key or token.
First test: the dry run (free)
Start claude in ~/avatar-studio and paste this. It should show you the request and stop.
Dry run only. Build the HeyGen request for this line and show it to me, then stop:
"This is my first video made from one prompt."Good: JSON with your look id, your voice id, "engine": {"type": "avatar_iv"}, 9:16 and 1080p, and no render. Bad: it renders anyway, or the ids are missing. Then CLAUDE.md isn't being read: check you started claude inside ~/avatar-studio.
Want to see every field HeyGen accepts? heygen video create --request-schema prints the full list.
Your first real clip (this spends credits)
Yes, render that request, wait for it, and download it to out/first.mp4. Then tell me the file and how long it is.Under the hood Claude runs two commands. Here they are, so you can run them yourself or check what it did:
heygen video create -d '{"type":"avatar","avatar_id":"<your look id>","voice_id":"<your voice id>","script":"This is my first video made from one prompt.","engine":{"type":"avatar_iv"},"aspect_ratio":"9:16","resolution":"1080p"}' --wait
# copy the video id from the answer, then:
heygen video download <video id> --output-path out/first.mp4 --forceWatch it with sound. If the voice sounds off, the fix is usually a cleaner voice sample, not a different prompt.
Real use: prompts for real jobs
Here's a rough thought: <your thought>. Write it as 60-100 words I'd say to camera: casual, one idea, the point in the first sentence, no numbers I didn't give you. Show me the script and the dry-run request. Wait for my yes before rendering.Dry run two requests for the same line: one 9:16 for Reels and TikTok, one 16:9 for YouTube. Show both. After my yes, render both into out/ with -vertical and -wide in the names.Dry run a request for this line with "output_format": "webm" so HeyGen removes the background (no background field; HeyGen rejects one with webm). After my yes, render and download to out/<name>.webm.Read lines.txt (one line per video). Show me a table: each line, its word count, and about how many seconds it is. Then dry run the first one only. After my yes on that, render the rest one at a time and stop on the first error.What it costs
| Tool | Plan | Monthly, list price |
|---|---|---|
| Claude Code | Claude Pro | $20 |
| HeyGen | Creator (600 credits) | $29 |
| Total | Monthly billing | $49 |
What HeyGen's credits buy: HeyGen lists an Avatar IV photo look at 16 credits per minute of video, so 600 credits is about 37 minutes of avatar video a month if every credit goes to that. A 30-second clip is about 8. Retakes cost the same as takes, which is why the dry run exists.
When it breaks
heygen: command not found
~/.local/bin: add that folder to your PATH.heygen auth status says you're not logged in
heygen auth login --oauth again. OAuth logins expire; it's normal to redo this now and then.Claude renders without a dry run
CLAUDE.md. Start claude from inside ~/avatar-studio, and keep the “Never render without my yes” line.The render fails with an avatar error
heygen avatar looks list again and copy the id exactly.It renders on a different engine
"engine": {"type": "avatar_iv"}. Naming it every time means HeyGen's default can't change it under you.Out of credits
Next: turn the clip into a finished video
A talking clip is half a video. My content engine guide takes this same clip through captions and graphics with HyperFrames and schedules it to five apps through Upload-Post, with a stop for your yes before anything posts.
That's the connection
One sentence in, your avatar out, and a dry run between you and every credit. That's the whole trick most of these videos skip.
Next: the full engine: captions, graphics and scheduling, with your yes before anything posts.
Checked on Oct 6, 2026 against
Every claim about a third-party tool in this guide (plans, prices, menu paths, commands, limits) was checked against these official pages on Oct 6, 2026. These screens change often: if something looks different, trust the page over this guide.
- Claude Code: Advanced setupInstall command and which plans include Claude Code.
- Claude Code: Memory (CLAUDE.md)CLAUDE.md is read at the start of every session.
- HeyGen Developers: CLIInstall,
heygen auth login(OAuth or API key),video createwith-dand--wait,video download. - HeyGen CLI on GitHubThe CLI's readme: logins, commands,
--request-schema. - HeyGen Developers: Avatar IVThe Avatar IV engine and its request field.
- HeyGen Developers: Avatar consentConsent for photo avatars is the user's responsibility.
- HeyGen Help: Photo avatarsUpload Photo, photo requirements, validation.
- HeyGen Help: VoicesInstant Voice Cloning and the recording tips.
- HeyGen: PricingCreator at $29 a month with 600 credits (checked 2026-10-04).
- HeyGen Help: How to use creditsAvatar IV photo looks at 16 credits per minute.
- Claude: Plans and pricingPro at $20 a month billed monthly (checked 2026-10-04).
