# HeyGen API: Wallet Pricing, MCP vs CLI, Limits and v3 Setup

> How the HeyGen API bills: a separate prepaid USD wallet from $5, plan credits that skip Zapier and n8n, MCP on plan credits, v3 rate limits and webhooks.

_Source: https://professionalstoolkit.com/articles/heygen-api — The Professional's Toolkit · updated October 2026_

---

The HeyGen API is not part of any HeyGen plan. It runs on its own prepaid wallet in US dollars: you start with $5, pay as you go with no subscription, and purchased API credits expire after 12 months.[1] HeyGen's help center says monthly free API credits ended in February 2026, so budget from the first call. Zapier, Make, n8n, HubSpot and Clay all spend API credits, never plan credits. The Remote MCP server does the opposite and bills your plan. Developers building video into a product should plan against the wallet; people who want an AI assistant to produce the odd video can stay on plan credits. Pick the meter first.


**$5** — Minimum prepaid wallet to start on the HeyGen API; purchased API credits expire after 12 months.



- **10** — Concurrent API workflows on pay-as-you-go (Enterprise: 20)
- **100** — Items per batch call, at 30 batch calls a minute
- **Oct 2026** — v1 and v2 endpoints sunset at the end of the month; build on v3


## Two meters: the API wallet and your plan credits

You buy API credits in dollars, separately from Creator, Pro or Business, and usage is measured by the type and length of what you generate, with rates varying by avatar engine and feature. An optional auto-reload tops the balance up below a threshold you set. A call to GET /v3/users/me tells your code which billing object the account carries (wallet, subscription or usage-based) and the remaining balance. Holders of the old API Pro and Scale plans are on a different clock. Their credits expire after 30 days.

The trap is the integrations. HeyGen's help center says plan credits cannot pay for HubSpot, Clay, Zapier, Make or n8n; those connections need an API key and separately purchased API credits, which any account can buy, Free included.[2] A Business workspace with 1,500 shared credits a month therefore still needs a funded wallet before its CRM workflow sends one personalized video. You find the key under the Developers icon in the web app, then API keys. It is shown once, so store it immediately.

**Remote MCP** works the other way round. You add the endpoint as a connector in Claude, ChatGPT, Cursor or another supported agent, sign in with OAuth, and renders draw on your plan's premium credits with no extra charge and no key. It works on every plan, though HeyGen recommends Creator or above for heavier use. HeyGen's pricing page lists Creator at $29 a month billed monthly, or $24 a month billed yearly ($288 a year), with 600 credits a month. Credits, not the plan price, decide how much video you get, and our [HeyGen pricing guide](/articles/heygen-pricing) converts them per engine.

That conversion lets the two meters be compared. In plan credits, Avatar V costs 48 credits a minute and Avatar IV 16 with a photo look or 31 with a video look. By our arithmetic, Pro's 1,000-credit tier at $49 a month billed monthly works out near $0.049 a credit, so a 48-credit Avatar V minute lands around $2.35; at the blog's API rate the same minute costs $3. Creator at $29 a month billed monthly is slightly cheaper per credit, but HeyGen lists Avatar V on Creator only with limited usage, so Pro is the plan for Avatar V volume. The plan route wins only if you spend the credits before they lapse. Monthly credits roll over just one extra cycle.


> 💡 **Cap spend on every API key:** Workspace admins can set per-key credit limits by calendar month or last 30 days. The cap is soft, so jobs already running can push spend slightly past it.


## The per-second rates HeyGen publishes

Avatar pricing is the awkward part. HeyGen's blog posts (Oct 2026) say the API charges $0.05 per second for Avatar V. At that rate a 60-second presenter clip costs $3 and a ten-minute explainer $30, while a $5 starting balance covers about 100 seconds. The API pricing table itself sits behind sign-in, so check your engine's rate in the dashboard before committing a budget. One quality note: a 4K avatar request through the API is an upscaled 1080p render, not native 4K.

HeyGen Video, the in-house prompt-to-video model with its own sound, lists rates on its product page: from $0.02 per second at 480p and $0.03 per second at 768p, the default. Output at 1080p and 2K bills at three times the 768p rate. Text-to-video and image-to-video clips run 5 to 30 seconds; reference-to-video stops at 15. Billing follows the resolved length, so a request with no duration gets 5 seconds. A ten-second 480p draft costs about twenty cents. The route runs on paid API keys only.

Voice is cheaper and better documented. HeyGen Voice text-to-speech costs $30 per 1M characters, Voice Turbo $15 per 1M characters, and speech-to-speech $0.12 a minute, billed per second. Turbo Free is free until 30 Nov 2026 on shared capacity, so expect 429 responses when that pool fills. Professional voice clones need a purchased slot. Filler-word removal costs $0.30 per source minute, with a one-minute minimum, refunded when nothing gets cut. Translations always bill on source duration.

## MCP, CLI or raw API: the surface decides the bill

| Surface | How it signs in | What pays | Built for |
|---|---|---|---|
| Remote MCP | OAuth, no key | Plan credits | AI assistants making videos on request |
| HeyGen CLI | API key or OAuth login | API wallet when a key is used | Scripts, CI, agents in a terminal |
| HeyGen Skills | MCP, or the CLI if a key is set | Plan credits via MCP; wallet via the CLI | Coding agents |
| v3 REST API | X-Api-Key header or OAuth bearer | API wallet with a key | Video inside your own product |

The quiet switch sits in the Skills row. HeyGen's three open-source skills (avatar, video and translate) call the MCP server by default, but once HEYGEN_API_KEY is set in the environment they use the CLI instead, which bills as separately metered API usage. A developer who exports the key for one script can move an agent's everyday work onto the wallet unnoticed. The CLI ships as a single binary for macOS and Linux. **As of October 2026, Windows is listed as coming soon**, with WSL suggested meanwhile.

The CLI is built for automation. Output is JSON by default, the wait flag blocks with a 20-minute default timeout, and exit code 4 means the resource exists but polling timed out. MCP has narrower edges. HeyGen Video through MCP is limited to 5 to 15 seconds on any plan, Free-tier MCP cannot generate avatar looks, and OAuth video creation defaults avatar videos to 720p and checks resolution against your plan. For video inside a product, HeyGen points to the API, not MCP.


> ⚠ **An exported key moves Skills to the wallet:** Once HEYGEN_API_KEY is set, HeyGen Skills switch from MCP (plan credits) to the CLI, which bills as separate API usage.


## Building on v3 without surprises

Start on version 3. HeyGen is retiring the v1 and v2 endpoints at the end of October 2026, and their responses carry Sunset headers naming the v3 replacement. On v3 every endpoint shares one error format, cursor pagination and authentication by key or OAuth token. You choose the avatar engine per request: Avatar IV is the default, Avatar V is opt-in per look, and an engine the look does not list returns a 400. Key POST endpoints accept an Idempotency-Key, replayed for 24 hours.

Files follow strict size rules. A single upload to POST /v3/assets is capped at 32 MB; the three-step direct upload takes up to 200 MB per video, image or PDF and 1.5 GB per audio file. An asset_id never expires. Output links are the opposite: every video, thumbnail and caption URL is presigned and short-lived. Download files when a job completes instead of storing links.

Custom avatars bring consent into your code. Digital twin footage runs 15 to 600 seconds, about two minutes recommended, and the twin cannot render until the person depicted records consent through a link valid for 24 hours. There is no consent webhook, so poll the avatar group. Uploading pre-recorded consent, or skipping it under an indemnity agreement, is Enterprise only. Photo avatars get no consent check and no record from HeyGen. That responsibility is yours. Deleting an avatar leaves the footage, consent video and cloned voice; each needs its own delete.

Webhooks replace polling, which counts against your rate limits. Registered endpoints receive a POST signed with HMAC-SHA256 of the raw body, and your handler must answer with a 2xx within 10 seconds. Failed deliveries are retried with backoff for up to 24 hours. An event can arrive twice. Deduplicate before you act. For one-off jobs a callback_url works instead, though Cinematic Avatar requests reject it.[3]

## Rate limits, concurrency and the errors that cost money

Pay-as-you-go accounts process 10 workflows at once; Enterprise gets 20 and can add burst capacity of 5 to 50 more, billed at 1.5 times the contract rate. Pay-as-you-go and subscription plans allow 300 reads a minute, 10 writes a second, 30 heavy calls a minute and 500 status polls a minute; Enterprise raises them to 1,000, 30, 120 and 1,500.[4] Batch endpoints allow 30 calls a minute on every plan, each carrying up to 100 items.

Wire up the errors before launch. A 429 carries Retry-After, so respect it. A 402 insufficient_credit states credits held against credits required. A 402 usage_limit_reached means an admin's per-member or per-key credit limit tripped, and buying credits does not clear it. Those limits are soft: running jobs finish, so spend can end slightly above the cap. A key also stops working when its owner loses workspace access. LiveAvatar is a separate product with its own API and credits.


> 💡 **Send an Idempotency-Key on retries:** Key POST endpoints replay the original response for 24 hours when the same key is resent, so a network retry does not create a second render.



## FAQ

**Can a HeyGen API key be restricted to certain actions?**

Yes. Keys can carry permission scopes such as read-only or custom sets, and a call outside the key's scope returns 403 insufficient_api_key_scope.

**Does the HeyGen API include LiveAvatar streaming avatars?**

No. LiveAvatar has its own API, plans and credits, and its credits are unrelated to HeyGen API credits.

**How long does a Video Agent render take through the API?**

HeyGen's docs say processing typically takes 5 to 10 times the final video length, and a video still processing after 24 hours should be reported to support with its video_id.

**Can I test a template without spending credits?**

Yes. Adding test true to a template generate request renders a lower-quality test video with no credit charge.


## The bottom line

The HeyGen API is a capable v3 platform with batch endpoints, webhooks, scoped keys and spend caps, but it bills a wallet that no HeyGen plan touches, and every no-code integration draws from it too. Fund it in dollars, mind the 12-month expiry, and confirm your engine's per-second rate in the dashboard, since the Avatar V figure comes from HeyGen's blog. If you only want an assistant to produce videos, Remote MCP on plan credits is the simpler meter. If the video ships inside your product, build on v3 and budget per second.



## Sources

[1] HeyGen Help: heygen api pricing credits explained — https://help.heygen.com/en/articles/10060327-heygen-api-pricing-credits-explained (2026-10)
[2] HeyGen Help: how to use credits on heygen — https://help.heygen.com/en/articles/15126059-how-to-use-credits-on-heygen (2026-10)
[3] HeyGen developer docs: docs/webhooks — https://developers.heygen.com/docs/webhooks (2026-10)
[4] HeyGen developer docs: docs/usage limits — https://developers.heygen.com/docs/usage-limits (2026-10)
[5] HeyGen pricing page — https://www.heygen.com/pricing
[6] HeyGen Help Center — https://help.heygen.com/en/
[7] HeyGen Terms of Service — https://www.heygen.com/terms
[8] App Store (US), HeyGen listing — https://apps.apple.com/us/app/ai-avatar-generator-heygen/id6711356409