HeyGen Video 1: Power-User Guide to 30-Second Reference Clips and MCP

Last updated: November 19, 2026

HeyGen Video 1 is HeyGen’s prompt-to-video model, called as heygen-video-1. In November 2026, HeyGen raised reference-to-video clips to 30 seconds with turbo or quality enhancement and let its MCP video tools create 5 to 30 second clips on all plans. Reference videos still share a 15-second input budget.

Contents

What changed in November 2026

HeyGen’s API changelog lists a November 2026 entry titled “HeyGen Video reference to video up to 30 seconds.” It completes a change that began in October, when text-to-video and image-to-video clips moved to 30 seconds while reference-to-video and MCP requests stayed at 15 seconds.

The November update has two parts:

  • API: POST /v3/models/videos now accepts whole-second durations from 5 to 30 for reference_to_video with turbo or quality enhancement, at 480p, 768p, 1080p or 2K. The model ID and endpoint are unchanged.
  • MCP: the text_to_video, image_to_video and reference_to_video tools accept 5 to 30 seconds on all plans, with auto duration capped at 15 seconds.

HeyGen Video 1 at a glance

The HeyGen Video documentation describes one model, heygen-video-1, built on MiniMax H3 and post-trained by HeyGen. Each clip includes its own audio track with dialogue, ambience and sound effects, so there is no separate speech or lip-sync step.

Item Details
Model ID heygen-video-1
Create and retrieve POST /v3/models/videos, then GET /v3/models/videos/{video_id}
Modes text_to_video, image_to_video, reference_to_video (default)
Duration 5–30 seconds with turbo or quality; 5–15 seconds with ultraquality or disabled; default 5
Resolution 480p, 768p (default), 1080p, 2K
Prompt length Up to 32,000 characters
Output MP4 (H.264), 24 fps, AAC 32 kHz stereo audio
Auth and scopes x-api-key header; videos:write, videos:read, assets:write

HeyGen says the model works best on short, contained shots with one subject, one place and one action. It is less reliable on long on-screen text, soft organic motion such as hair or paper, and close hand work.

Create a 30-second reference-to-video clip

The route runs on paid API keys, and insufficient credits return a 400 error. An explicit duration above the limit is rejected rather than shortened.

  1. Create an API key on the HeyGen API keys page with the videos:write, videos:read and assets:write scopes.
  2. Upload reference files you do not host yourself with POST /v3/assets and keep the returned asset_id. The URL fetcher does not follow redirects.
  3. Send POST /v3/models/videos with "model": "heygen-video-1", "mode": "reference_to_video", at least one reference image or video, and an explicit "duration": 30.
  4. Set prompt_enhancement to turbo or quality. If you leave it out, quality is used. Ultraquality and disabled stay limited to 15 seconds.
  5. For 1080p or 2K, set aspect_ratio to 16:9 or 9:16, since reference to video otherwise defaults to adaptive.
  6. Add an Idempotency-Key header so a retry within 24 hours does not start a second job.
  7. Poll GET /v3/models/videos/{video_id} until the status is completed, failed or cancelled, or pass a callback_url. A 30-second clip is still one job and one final video.

A minimal request body looks like this:

{
  "model": "heygen-video-1",
  "mode": "reference_to_video",
  "prompt": "<Picture 1> sits on a wooden desk while a presenter explains it to camera.",
  "reference_images": [{ "type": "asset_id", "asset_id": "ASSET_ID" }],
  "duration": 30,
  "prompt_enhancement": "quality",
  "resolution": "1080p",
  "aspect_ratio": "16:9"
}

How reference inputs work

In reference to video, list order becomes the label you use in the prompt. The first reference image is <Picture 1>, the first reference video is <Video 1>, and images, videos and audio are numbered separately.

Input Maximum
reference_images 9
reference_videos 3
reference_audio 3 (optional)
Total references 15
Reference video footage 15 seconds shared across all videos

The 15-second video budget did not change with the 30-second output. When reference videos run longer than 15 seconds combined, each keeps up to its first five seconds and the rest of the budget is shared. For example, two 10-second videos use 7.5 seconds each.

Use 30-second clips through MCP

HeyGen’s MCP overview explains how to connect Claude, Cursor, Gemini CLI and other MCP clients through the remote server at https://mcp.heygen.com/mcp/v1/ with OAuth sign-in and no API key. ChatGPT and Codex users install the HeyGen plugin instead. MCP usage draws on your existing HeyGen plan credits.

The page notes that auto duration selects 8 to 15 seconds through MCP, so ask for a specific length, for example “make a 30-second clip,” when you want a 16 to 30 second result.

How it compares with the launch version

HeyGen added the HeyGen Video API to its public reference in September 2026. The changelog shows how much the model has grown since then:

Feature September 2026 launch November 2026
Clip length 5–15 seconds 5–30 seconds in all modes (turbo or quality)
Resolution 480p, 768p 480p, 768p, 1080p, 2K
Prompt length Up to 5,000 characters Up to 32,000 characters
Total references 12 15
Auto duration Not available 8–30 seconds, or 8–15 for reference to video and MCP

HeyGen Video is separate from the avatar engines behind POST /v3/videos, which animate an avatar you already own from a script. To place your own avatar looks in a HeyGen Video shot, HeyGen offers Cinematic Avatar with the HeyGen Video model, which the changelog lists at 5 to 15 seconds and 720p.

For other video tools, see our answers on whether ChatGPT can generate videos, whether Claude can generate videos and the Gemini video generation limit.

Billing and plan notes

HeyGen’s developer docs point to the API dashboard at platform.heygen.com for current self-serve prices and do not list a per-second price for HeyGen Video. The documentation does state these billing rules:

  • 1080p and 2K bill at 3 times the 768p rate, for output seconds and reference-video seconds alike.
  • With auto duration, billing uses the length the job picked, reported as duration.
  • Reference footage is billed by input_video_duration, which is 0 when there are no video references.

Limitations and tips

  • Auto stays short: reference to video and MCP cap auto duration at 15 seconds. Always set an explicit duration for longer clips.
  • Write long prompts: HeyGen says prompts of a few hundred to a few thousand characters produce materially better output.
  • Avoid invented branding: add a line such as “no logos, brand names, printed words or badges anywhere in frame.”

For HeyGen’s analysis model, see our HeyGen Decision 1 guide. For music-driven clips, see our Suno Visuals guide.

Frequently asked questions

What is HeyGen Video 1?

HeyGen Video 1 (model ID heygen-video-1) is HeyGen’s general-purpose video generation model, built on MiniMax H3 and post-trained by HeyGen. It creates a full scene with its own audio from a prompt, a first-frame image or reference media through POST /v3/models/videos.

How long can HeyGen Video clips be?

With turbo or quality prompt enhancement, all three modes accept whole-second durations from 5 to 30 seconds. Clips using ultraquality or disabled enhancement stay at 5 to 15 seconds. Omitting duration selects 5 seconds.

Why does duration auto stop at 15 seconds for reference to video?

HeyGen caps auto duration at 15 seconds for reference to video and for MCP requests. Auto picks 8 to 15 seconds from quoted dialogue, so set an explicit duration such as 25 or 30 when you want a longer clip.

Can I make 30-second HeyGen Video clips through MCP?

Yes. HeyGen’s MCP text_to_video, image_to_video and reference_to_video tools accept 5 to 30 seconds on all plans with turbo or quality enhancement. Ask for an explicit length, because auto duration is capped at 15 seconds.

How much does HeyGen Video cost?

HeyGen does not publish a per-second price in its developer docs; self-serve prices appear after you sign in to platform.heygen.com. The docs state that 1080p and 2K bill at 3 times the 768p rate and that billing uses the resolved duration.

Sources

Image: HeyGen logo by HeyGen, public domain (trademarked), via Wikimedia Commons. HeyGen is a trademark of HeyGen; FreeAnswers is not affiliated with HeyGen.

Related answers

Leave a Comment