HeyGen Video Agent

Official HeyGen plugin for OpenClaw — adds HeyGen as a first-class provider for the built-in video_generate tool. Identity-first avatar videos: pick an avata...

Security Scan

The skill's code, docs, and runtime instructions consistently implement a HeyGen video provider and only request the single HeyGen API key they need to operate.

Purpose & Capability

Name/description, SKILL.md, openclaw.plugin.json, and the provider code all line up: this is an OpenClaw video provider for HeyGen and it only declares HEYGEN_API_KEY as the required credential. Nothing in the metadata or manifest requests unrelated cloud credentials or host-level access.

Instruction Scope

Runtime instructions (SKILL.md and INSTALL_FOR_AGENTS.md) tell the agent to install the plugin, ask the user for a HeyGen API key, set it via env or OpenClaw onboarding, and optionally run a small smoke test that creates a real HeyGen render (costs credits). The instructions reference only OpenClaw config files (~/.openclaw/openclaw.json) and HeyGen endpoints — no unexplained file reads, secret collection, or off-platform exfiltration are present.

Install Mechanism

No automatic download/install spec is embedded (instruction-only install). Included source files are standard plugin code and unit tests. There are no install steps that pull arbitrary archives or call back to personal servers. package-lock contains many transitive entries (e.g., AWS-related packages) but package.json devDeps are minimal; this is not evidence of an install-time remote fetch from unknown hosts.

Credentials

Only HEYGEN_API_KEY is declared and used as the primary credential. The SKILL.md and code use that key to authenticate to api.heygen.com. No other SECRET/TOKEN/PASSWORD env vars are requested.

Persistence & Privilege

always:false (normal). The plugin is marked enabledByDefault in openclaw.plugin.json and the docs show commands that save defaults to the OpenClaw config and can make HeyGen the instance-wide default video provider — this is expected for a provider plugin but you should be aware these config changes affect all agents on the OpenClaw instance.

Assessment

This plugin appears to be what it says: an OpenClaw provider that calls api.heygen.com and requires your HeyGen API key. Before installing: (1) confirm you trust the GitHub repo/homepage listed (https://github.com/heygen-com/openclaw-plugin-heygen), (2) only provide a HeyGen API key (the plugin does not request other secrets), (3) be aware the smoke test will create a real HeyGen render and may consume credits, (4) if you don’t want the plugin to be the default for all agents, skip the 'make HeyGen the default' config step, and (5) consider creating a dedicated HeyGen API key (or checking billing/permissions) so any misuse is limited. If you want higher assurance, review the plugin's repository externally (especially video-generation-provider.ts) or install from the official GitHub release.

HeyGen Video Agent — OpenClaw Plugin

Adds HeyGen as a first-class provider for OpenClaw's built-in video_generate tool. Same interface every other video provider in OpenClaw uses (Google Veo, Runway, Kling, Wan, MiniMax, Dashscope) — now with identity-preserving avatar/presenter video.

Install

openclaw plugin install heygen

Set HEYGEN_API_KEY in your environment (get one at https://app.heygen.com/settings/api).

Quick start

const result = await video_generate({
  model: "heygen/video_agent_v3",
  prompt: "Hi team, here's the product update for this week.",
  providerOptions: {
    avatar_id: "<your-avatar-id>",
    voice_id: "<your-voice-id>",
    orientation: "landscape", // or "portrait"
  },
});
// result.url → downloadable .mp4

Avatar / voice ids: list from the HeyGen dashboard or the heygen-skills companion skill (which composes opinionated avatar/voice picking on top of this plugin).

When HeyGen vs other video providers

• Avatar-presenter / talking-head video → HeyGen.
• Cinematic / scene generation → Veo, Runway, Kling.
• Translation / dubbing → use HeyGen's translate APIs (separate skill).
• Real-time interactive avatar → HeyGen Streaming Avatar (separate surface, not this plugin).

Provider options

Field	Type	Notes
avatar_id	string	HeyGen avatar id; falls back to models.providers.heygen.defaultAvatarId.
voice_id	string	HeyGen voice id; falls back to models.providers.heygen.defaultVoiceId.
style_id	string	Optional style template.
orientation	"landscape" | "portrait"	Maps from aspect ratio. 1:1 rejected.
mode	"generate" | "chat"	Default generate. chat keeps full poll budget for interactive flows.
callback_url	string	Async webhook completion.
callback_id	string	Caller-supplied correlation id for the webhook.
incognito_mode	boolean	Skip retention on HeyGen side where supported.

Errors surfaced cleanly

• 401 → HeyGen API key missing or invalid
• 402 / quota → HeyGen credit limit reached
• Generate-mode + 8 consecutive thinking polls → fast-fail with a hint pointing at avatar_id / voice_id.
• failed status surfaces HeyGen's failure_message rather than a generic error.

Polling

Three-tier backoff: 5s × 6 → 15s × 12 → 30s until MAX_POLL_ATTEMPTS. Long renders (20–45 min) stay under typical HeyGen per-key rate limits.

Source + tests

• Repo: https://github.com/heygen-com/openclaw-plugin-heygen
• 19 unit tests, live smoke verified end-to-end against api.heygen.com.
• Extracted from openclaw/openclaw#69578 (closed in favor of external/ClawHub publication per VISION.md).

License

MIT. See LICENSE.