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 plugin's code, instructions, and requested environment variable (HEYGEN_API_KEY) align with its stated purpose of integrating HeyGen's Video Agent into OpenClaw; nothing in the package appears to request unrelated credentials or hidden endpoints.

Purpose & Capability

Name/description, SKILL.md, openclaw.plugin.json, and the TypeScript provider implementation consistently implement a HeyGen video provider. The only required environment variable is HEYGEN_API_KEY and the code makes requests to api.heygen.com and related HeyGen file URLs — all expected for this provider.

Instruction Scope

SKILL.md and README instruct the agent to call OpenClaw's video_generate API with HeyGen-specific providerOptions (avatar_id, voice_id, etc.) and to set HEYGEN_API_KEY. The runtime instructions do not ask the agent to read unrelated files or environment variables, nor do they instruct exfiltration to unexpected endpoints. Note: the plugin supports passing callback_url (webhook) which will cause HeyGen/OpenClaw to call an external URL supplied by the caller — callers should only use trusted webhook endpoints.

Install Mechanism

This is primarily an instruction-only plugin with TypeScript source included and no explicit install spec. That is low risk. One small anomaly: the included package-lock.json contains a large dependency tree (many AWS/@smithy and other packages) not referenced in package.json dependencies. While this doesn't change runtime behavior of the provider code shown, users should confirm the provenance of the lockfile and that your install process will not unexpectedly fetch or install unrelated packages.

Credentials

Only HEYGEN_API_KEY is required and declared as primary credential; the code uses it for X-Api-Key to call HeyGen APIs. No other SECRET/TOKEN/PASSWORD env vars are requested or accessed in the SKILL.md or the visible code.

Persistence & Privilege

The skill does not request 'always: true' and does not attempt to modify other skills or system-wide settings. It registers itself as a video provider in the normal plugin fashion. Autonomous invocation is allowed but this is the platform default and appropriate for a provider plugin.

Assessment

This plugin appears to be what it claims: a HeyGen video provider that needs only your HEYGEN_API_KEY. Before installing: (1) verify the repository origin/commit on the listed homepage (https://github.com/heygen-com/openclaw-plugin-heygen) to ensure the package-lock.json was not tampered with; (2) prefer providing HEYGEN_API_KEY with least privilege and rotate keys if possible; (3) be cautious with callback_url values you pass (they cause HeyGen/OpenClaw to POST to your URL); (4) if you run npm install in this repo, review which packages would be installed — the included package-lock.json contains many large packages not referenced in package.json and you should confirm that matches the upstream repository or remove the lockfile if you trust only the plugin source files. Overall the plugin is coherent and consistent with its purpose.

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.