Connect Claude Code to HeyGen's command-line tool, so one sentence becomes a video of your AI avatar in your folder. With a dry run first.
Swipe or tap Next · checked on 2026-10-06
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.
Make the folder and start Claude in it
mkdir -p ~/avatar-studio/out
cd ~/avatar-studio
claudeThe setup prompt (copy all of it) · lines 1-4 of 15. Copy all copies the whole prompt; read it in full on the page.
Hi 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-heygenThis is the manual way: every step and every command. Claude follows it too.
heygen.The avatar is your own photo and your own voice, with your consent. HeyGen's own docs say it runs no consent check on photo avatars, and that getting the person's agreement is your job. So the rule is simple: nobody else's face or voice, ever.
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).
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.
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.
Skip this if claude --version already prints a version. You need Claude Pro, Max, Team or Enterprise.
Install (macOS, Linux, WSL)
curl -fsSL https://claude.ai/install.sh | bash
# open a NEW terminal window, then:
claude --versionTwo 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.
Install, log in, check
curl -fsSL https://static.heygen.ai/cli/install.sh | bash
heygen auth login --oauth
heygen auth status~/.heygen/credentials: never share that file or show it on screen.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.
List your looks and voices
heygen avatar looks list
heygen voice listThis is what makes it safe to hand Claude the keys to your credits: it reads this file at the start of every session.
CLAUDE.md · Part 1 of 2 · Copy copies all 20 lines
# 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.CLAUDE.md · Part 2 of 2 · Copy copies all 20 lines
## 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.Start claude in ~/avatar-studio and paste this. It should show you the request and stop.
Prompt: dry run
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.
Prompt: render it
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:
What Claude runs (fill in your ids)
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.
1. A script from a rough thought
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.2. The same line, two shapes
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.3. A cut-out of me for an edit
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.4. A batch from a list
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.Checked 2026-10-04 on each tool's pricing page. Prices change: check before you buy.
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.
heygen: command not foundOpen a new terminal window after installing. Still missing? The installer put it in ~/.local/bin: add that folder to your PATH.
heygen auth status says you're not logged inRun heygen auth login --oauth again. OAuth logins expire; it's normal to redo this now and then.
It isn't reading CLAUDE.md. Start claude from inside ~/avatar-studio, and keep the “Never render without my yes” line.
Your photo avatar may still be validating, or the look id is wrong. Run heygen avatar looks list again and copy the id exactly.
Make sure the request has "engine": {"type": "avatar_iv"}. Naming it every time means HeyGen's default can't change it under you.
The render is refused. Wait for your plan's reset, or buy more; dry runs stay free either way.
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.
What each page backs up is listed at the end of the full guide.
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.
Want help setting this up? Receipts Group builds these systems.
Open the full guide as a page (every file in full, plus the table of contents).