• Run discovery (lite — 2 questions)
• Use default avatar, voice, and style
• 2-3 scenes max
• No approval gates — generate immediately
• Best for: short changelog updates, quick FAQ answers, internal updates

• Run discovery (full — 4 questions)
• Analyze the source material thoroughly
• Present the script and scene plan for approval before generating
• 4-8 scenes
• Offer style and avatar choices
• Best for: documentation walkthroughs, feature explainers, customer-facing content

• Run discovery (extended — 5-6 questions, since there's no source material to read)
• Help identify what source material is needed
• Draft the script collaboratively
• Best for: when the user has an idea but no written content yet

1. Read the source material first (if provided). Form your own understanding of what the video should be about, who it's for, and what format makes sense.
2. Then ask only what you can't infer. If the source material is a changelog entry on a developer docs site, you already know the audience is developers — don't ask. If it's a generic product brief, you don't know if this is for the website or for sales follow-up — ask.
3. Present your assumptions alongside your questions. Instead of "who is the audience?", say "I'm assuming this is for developers based on the docs page. That right? And a couple more things..."

"I've read through this. Looks like a [changelog/docs/feature] video for [inferred audience]. Two quick things:

1. Where is this going — docs page, LinkedIn, or something else?
2. Should I grab screenshots from the page, or do you have specific ones?"

"Here's what I'm thinking based on the source material:

• Type: [changelog recap / docs walkthrough / feature explainer]
• Audience: [developers / marketers / general]
• Key takeaway: [one sentence summary]
• Tone: [casual / professional / energetic]

A few questions:

1. Where will this video live? (website, LinkedIn, docs, email)
2. Is that takeaway right, or should the focus be different?
3. Do you have screenshots or should I capture them?
4. Anything specific to include or avoid?"

1. "What product or feature is this video about?"
2. "Who's the audience?"
3. "What's the one thing the viewer should take away?"
4. "Where will this video be used?"
5. "Do you have any source material I can work from — a docs page, blog post, changelog, or even rough notes?"
6. "What tone — casual update, polished explainer, or something else?"

AVATAR-CONFIG.md

AVATAR-CONFIG.md

"Before we generate your first video, let's set up your avatar. This is a one-time thing — I'll save your choice for all future videos.

How do you want to appear in your videos?

1. Pick a stock avatar — I'll show you a few options from HeyGen's library
2. Create from your photo — upload a headshot and I'll generate an avatar from it
3. Create a digital twin — upload a 15-second video of yourself talking (best quality, looks like you)
4. Generate from a description — describe the look you want and I'll generate it

Which option?"

1. Fetch available avatars from

   GET https://api.heygen.com/v2/avatars

2. Filter to a curated shortlist of 4-5 high-quality stock avatars. Pick a diverse set — different genders, appearances, and styles. For each, show:
   • Name and short description (e.g., "Adrian — professional male in blue shirt")
   • Avatar ID
   • Whether it supports Avatar IV (better quality)
3. Present the shortlist and let the user pick
4. After selection, proceed to voice selection

1. Ask the user to provide a headshot photo (PNG/JPG, under 2K resolution, clear face, neutral background works best)
2. Upload via

   POST https://api.heygen.com/v3/avatars

   with

   type: "photo"

3. Wait for avatar generation to complete
4. Show the user a preview and confirm it looks good
5. After confirmation, proceed to voice selection

1. Explain the requirements:

   "Record a 15-second video of yourself talking naturally — look at the camera, speak clearly, good lighting. This will create the most realistic avatar. HeyGen requires consent verification for digital twins."

2. Ask the user to provide the video file
3. Upload via

   POST https://api.heygen.com/v3/avatars

   with

   type: "digital_twin"

4. Complete the consent verification flow
5. Wait for processing (this can take several minutes)
6. Show the user a preview and confirm
7. After confirmation, proceed to voice selection

1. Ask the user to describe the look they want (e.g., "friendly woman, early 30s, professional but approachable, dark hair")
2. Submit via

   POST https://api.heygen.com/v3/avatars

   with

   type: "prompt"

   and the description
3. HeyGen returns up to 3 options
4. Present all options and let the user pick their favorite
5. After selection, proceed to voice selection

"Now let's pick a voice. You can:

1. Describe what you want — e.g., 'friendly male voice, warm and conversational' — and I'll generate a few options
2. Browse the catalog — I'll show you voices filtered by language and gender

Which do you prefer?"

1. Ask for a text description of the desired voice
2. Submit via

   POST https://api.heygen.com/v3/voices

   with the description
3. Returns up to 3 options, each with a

   preview_audio

   URL
4. Present the options with preview links so the user can listen
5. User picks their favorite

1. Ask for language and gender preferences
2. Fetch from

   GET https://api.heygen.com/v2/voices

   with filters
3. Present a curated list of 4-5 options with

   preview_audio

   URLs
4. User picks their favorite

• Name: [avatar name or user's name]
• Role: [e.g., "Product narrator", "Company spokesperson"]

• Avatar ID: [heygen avatar id]
• Avatar Type: [stock / photo / digital_twin / prompt]
• Avatar Model: [avatar_iii or avatar_iv]
• Voice ID: [heygen voice id]
• Default Style: [style preset name, default: Clean Dark]

• Tone: [e.g., "conversational", "professional", "energetic"]
• Typical audience: [e.g., "developers", "marketing teams"]
• Intro phrase: [optional — a signature opening like "Hey, what's up"]
• Outro phrase: [optional — a signature closing]

After saving, confirm:

> "All set! I've saved your avatar config. From now on, all videos will use [avatar name] with [voice name]. You can update this anytime by editing `AVATAR-CONFIG.md` or asking me to change it."

Then proceed with the video production flow.

1. Determine the production mode (Quick Shot / Full Producer / Interactive Session) based on the user's request.
2. Check for

   AVATAR-CONFIG.md

   — if found, load avatar and voice preferences.
3. If no config exists, use defaults.

1. Read the source material first (if provided — URL, text, file path).
2. Run discovery based on the detected mode (see Discovery section above).
3. Map discovery answers to production decisions before proceeding.
4. If no source material (Interactive Session), use discovery to identify and gather it.

"This looks like a changelog. Is there a GitHub repo behind these changes? I can pull PR details, diffs, and screenshots to make the video more specific and accurate. If it is a private repo, you can either give me access or paste the relevant PR URLs."

• Date-range matching: If the changelog has a date or version, search the repo for PRs merged in that window. This catches changes the changelog may have missed.
• PR descriptions: Read the body of each relevant PR. These often contain motivation ("why we built this"), implementation notes, and before/after comparisons.
• PR screenshots and GIFs: Extract image URLs from PR bodies. These are better than browser screenshots because they show the exact change, not just the current state. Use these as first-class scene backgrounds.
• Diffs: Read the actual code/config diffs for key PRs. This enables diff-informed scripting — the script can say "notice how the sidebar now shows X" instead of generic descriptions. It makes the video feel like someone who actually built the feature is presenting it.

1. User-provided screenshots — use directly, highest priority
2. Image URLs from the source material (e.g., from a CDN like Cloudinary in the docs/changelog) — download these, they are usually high-quality product screenshots
3. Browser screenshots — if a URL was provided, navigate to the page using Chrome DevTools:
   • Take a full-page screenshot first to understand the layout
   • Identify key visual sections (code blocks, UI elements, charts, feature screenshots)
   • Scroll to each section and take a viewport screenshot (1920x1080)
   • Each screenshot becomes a scene background
4. Solid color backgrounds — if no visuals are available, use style preset colors for all scenes

• Short sentences. Average 10-15 words per sentence.
• Conversational tone. Write how people talk, not how they write.
• No jargon unless the audience is technical and expects it.
• No headers, bullet points, or formatting — it is a continuous spoken delivery.
• Use contractions naturally.
• Direct address — say "you" frequently.
• Rhetorical questions work well as transitions.
• Avoid filler openings like "In this video, I will..." — get to the point.
• If the user has set an intro/outro phrase in

  AVATAR-CONFIG.md

  , use it.

Scene 1 (full avatar): "Here is how to [do X] in [product]. It takes about [N] steps and you will be done in [time]."
Scene 2-N (circle avatar over screenshots): Walk through each step. One step per scene. "First... Then... Now..."
Final scene (full avatar): "That is it. [Recap the outcome]. Check out the docs at [URL] for more."

Scene 1 (full avatar): Hook with impact. "[Product] just shipped [feature]. Here is why it matters."
Scene 2 (circle avatar over product screenshot): What the feature does. Show the UI.
Scene 3 (circle avatar over detail screenshot): The interesting detail or power feature.
Scene 4 (full avatar): Why you should care + CTA.

Scene 1 (full avatar): The problem. "If you have ever tried to [pain point], you know it is painful."
Scene 2 (full avatar or screenshot): The solution intro. "That is exactly what [feature] solves."
Scene 3-4 (circle avatar over screenshots): How it works. Walk through the UI.
Scene 5 (full avatar): Why it matters + CTA.

Scene 1 (full avatar): The question. "One thing people ask a lot is: [question]?"
Scene 2 (circle avatar over relevant screenshot): The answer with visual context.
Scene 3 (full avatar): Summary + where to learn more.

Production Plan — [Video Title]

Summary: [N] scenes, estimated [X] seconds, [avatar model], [style preset]

Scene	Layout	Script	Visual
1	Full avatar	"Hook text here..."	Clean Dark background (#1a1a2e)
2	Circle avatar	"Feature explanation..."	PR screenshot: [description] — [source URL or file]
3	Circle avatar	"Detail walkthrough..."	Browser screenshot: [page section description]
4	Full avatar	"CTA text here..."	Clean Dark background (#1a1a2e)

Visual assets I will use:

• Scene 2: [thumbnail or description of the image, where it came from — PR #123, user-provided, browser screenshot of X page]
• Scene 3: [same detail]

Want me to adjust anything before I generate?

video_id

GET https://api.heygen.com/v1/video_status.get?video_id=<VIDEO_ID>

1. Poll every 10 seconds
2. Log status every 60 seconds to keep the user informed
3. When status is

   completed

   , download the video from

   video_url

4. Save to the working directory

Video complete!
- Duration: [X] seconds
- Scenes: [N]
- Avatar model: [III or IV]
- Visual style: [preset name]
- File: [local path]
- Video URL: [signed URL — expires in 7 days]
- Estimated cost: $[X]

Want me to adjust anything and regenerate?

1. No clickable links in video. Output is flat MP4. Show URLs as text overlays or mention them verbally.
2. No zoom/pan on backgrounds. If you need a zoomed view of a screenshot, take a separate cropped screenshot and use it as a different scene.
3. One text overlay per scene. If you need multiple text elements, bake them into the background image.
4. Max 5,000 characters per scene script. Split long narrations across multiple scenes.
5. Max 50 scenes per video, max 30 minutes total.
6. Generation time is 10-20 minutes for a typical 5-scene video. Avatar IV takes longer than Avatar III.
7. Avatar IDs must match exactly. Always list available avatars first if unsure. Use

   GET https://api.heygen.com/v2/avatars

   .
8. Asset uploads use

   upload.heygen.com

   , not

   api.heygen.com

   . Use raw binary body with Content-Type header.
9. Max 10 concurrent video jobs. Exceeding returns HTTP 429.
10. Signed video URLs expire in 7 days. Always download the video locally.
11. Avatar IV is ~6x more expensive than Avatar III. For high-volume or draft videos, consider using Avatar III first, then re-generating the final version with Avatar IV.
12. Portrait orientation requires adjusting circle avatar offset and scale for good proportions.

curl -s "https://api.heygen.com/v2/avatars" -H "X-Api-Key: <HEYGEN_API_KEY>"

curl -s "https://api.heygen.com/v2/voices" -H "X-Api-Key: <HEYGEN_API_KEY>"

curl -X POST "https://api.heygen.com/v3/voices" \
  -H "X-Api-Key: <HEYGEN_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"description": "friendly male voice, mid-30s, warm and conversational"}'

• Avatar:

  Adrian_public_3_20240312

  (Adrian in Blue Shirt — professional male)
• Voice:

  f38a635bee7a4d1f9b0a654a31d050d2

  (Chill Brian — natural English male)