Agent 4: Text to Video with Avatars

I wanted my AI agents to create and publish educational videos without me touching a single button. Here's how I connected HeyGen, Claude, and YouTube into one automated pipeline using two custom MCP servers — and what I learned along the way.

01 — Getting started with HeyGen

HeyGen is an AI video generation platform that lets you create studio-quality videos using a digital avatar — in this case, a personalised avatar of me, Jon Axel Sunnehall. Instead of recording myself over and over for every piece of content, I can pass text into HeyGen via API and it renders a video of my avatar delivering it.

The first step is straightforward: navigate to Developers → Overview and create an API key. You can see here the key named InAgentic-Text2Video — a production key created on 13 June 2026. You'll also need to top up API credits; HeyGen charges per render based on video duration. I started with $5 of API credits, enough to test the full pipeline several times.

Note: HeyGen offers both plan credits and separate API credits. Make sure you top up the API credits specifically — plan credits don't carry over to programmatic API calls.

02 — A destination for every video

Every video the agent creates needs somewhere to live. I chose YouTube as the distribution channel — it's where the audience already is, and the YouTube Data API makes programmatic uploads straightforward.

In Google Cloud Console, search the Marketplace for YouTube Data API v3 and enable it on your project. Then generate OAuth 2.0 credentials. The key detail here: uploading to a channel requires OAuth with user consent, not just a service account key. You'll go through the OAuth flow once to obtain a refresh token, which your MCP server stores and reuses for all future uploads — so you never have to authorise again.

03 — Building the MCPs with Claude Code

Here's where it gets interesting. I used Claude Code inside VS Code to write both MCP servers. You can see Claude mid-task: it's just decided to add a buildHeyGenServer function with create_video, get_video_status, and list_avatars tools, wiring them up to a /heygen endpoint. 214 lines added in a single edit.

I built two servers: text2video for triggering HeyGen renders, and inagentic-youtube for uploading finished videos. Both are deployed at mcp.inagentic.ai.

HeyGen does offer a pre-built MCP, but I chose to build my own for a deliberate reason: vendor independence. By owning the MCP layer, I can swap HeyGen out for another generative video tool — Runway, Synthesia, Sora — without changing anything in the agent. The interface stays stable; only the implementation changes.

Once deployed, the MCP shows up in Claude's connector settings at https://mcp.inagentic.ai/text2video. You can see the three tools exposed to agents: create_video, get_video_status, and list_avatars — all set to Always allow. Any Claude agent or project can now call these tools directly.

// Tools registered on the /heygen endpoint
const tools = [
  "create_video",              // Render a new video from template + slide data
  "get_video_status",          // Poll render progress by video ID
  "list_avatars",              // Discover available avatars
  "list_templates",            // Discover available templates
  "create_video_from_template" // Render using a saved template
]

04 — The 7-image template

Inside HeyGen I built a reusable template called "CRM Options" — visible in the Templates panel on the right. The structure is what matters: a fixed layout with 7 image placeholder slots across scenes, with my avatar appearing as a circular overlay and delivering a voice-over script on each slide.

The concept is simple and repeatable. Each image illustrates a step or concept; the avatar talks the viewer through it. Think of it as a screencasted tutorial format, but generated entirely from code. When the agent calls create_video_from_template, it passes the 7 images and the voice-over text for each scene — HeyGen handles all the rendering, transitions, and audio sync.

Why a fixed template? It means the agent never has to make layout or design decisions. It just fills the slots. This keeps the agent prompt simple and the output visually consistent — every video looks branded and intentional, even though no human touched it.

05 — Writing the content agent

With the MCPs in place, I wrote a Claude agent whose sole job is to produce video content. You can see it here working through the script for this very tutorial — writing out image references and voice-over copy for each of the 7 slides, one scene at a time.

Given a topic, the agent: determines the 7 images needed (screenshots, diagrams, or illustrations for each step); writes the avatar voice-over for each slide — concise, instructional, matching the tutorial tone; then calls create_video_from_template with the images and scripts packed into the template's slot format.

The agent prompt is deliberately short. It doesn't need to know anything about rendering or uploading — that's the MCP's responsibility. The agent is purely a content strategist: topic in, structured slide data out.

06 — Waiting for the render: exponential backoff

HeyGen renders aren't instant. After calling create_video, the API returns a video ID and a status of processing. The agent then enters a polling loop: wait, check status via get_video_status, then either proceed or wait longer.

Rather than hammering the API every few seconds, I implemented an exponential backoff strategy. The first check happens after 3 minutes. If the video still isn't ready, the next wait doubles to 6 minutes, then 12, and so on. This is gentle on the API, avoids rate limits, and works cleanly inside a long-running agent session.

• Attempt 1 — wait 3 minutes, then check
• Attempt 2 — wait 6 minutes, then check (×2)
• Attempt 3 — wait 12 minutes, then check (×2)
• Attempt 4 — wait 24 minutes, then check (×2)

Once get_video_status returns completed, the agent grabs the video URL and immediately passes it to the inagentic-youtube MCP tool to upload directly to the channel — title, description, and tags all included.

07 — Video live, or kick off the next one

The finished video appears on the YouTube channel automatically — no browser tabs, no manual uploads. At this point the agent has two natural exit paths: watch the video directly via the returned YouTube URL, or loop back and generate content for the next topic.

Because the whole pipeline runs through MCP tools, an orchestrator agent sitting above it can chain multiple video topics together in a single session — a full content calendar executed while you sleep.

What this unlocks: The same pipeline works for any topic. Change the agent prompt from "how to use MCP servers" to "getting started with Claude Code" and you get a completely different video — same template, same avatar, same distribution channel, zero manual work.

What I'd tell myself before starting

Own your abstraction layer. Building custom MCPs instead of using HeyGen's pre-built one was the right call. The agents talk to a stable interface I control — not a vendor's roadmap. If HeyGen changes their API or pricing, I update one file in one MCP server and nothing else breaks.

Polling beats webhooks for agentic workflows. Webhooks require a publicly reachable endpoint and state management across requests. Polling from inside the agent is simpler, fully observable in the conversation thread, and far easier to debug when something goes wrong mid-render.

Templates are leverage. The 7-image template was the force multiplier. Once it existed, every future video was just a data-filling exercise. The agent never needs to think about layout, branding, or transitions — those decisions were made once, in the template, and they compound across every video produced.

The avatar is a trust signal. Using my own likeness rather than a generic avatar matters — viewers associate the face with InAgentic, which builds brand recognition across every video the agent produces, even ones I never watched before they went live.

How I generated a specific prompt in Claude:
update prompt to create video for "Agent 4: Text to Video with Avatars", read and view images on https://inagentic.ai/news/agent-4-text-to-video-with-avatars/