HeyGen API v1 and v2 retire November 1: what to move

HeyGen's v1 and v2 API endpoints stay operational through October 31, 2026 and are retired from November 1, 2026, per HeyGen's Endpoint Version Comparison. If your code, your no-code automations or an internal agent still calls a v1 or v2 path, this is a mapping job rather than a rewrite: HeyGen's docs name a v3 replacement for each legacy call, and every legacy response already points at the one it should become.

The reason it matters now is the second half of the timeline. HeyGen's docs recommend v3 for all new development, and v3 is where the newer work lives. The Quick Start names v3 as the current developer entry point, and the changelog carries the formal deprecation. The old endpoints do not break this week, so the useful part is the deadline and the exact list of calls to move.

What the v1 and v2 retirement actually covers

The comparison page sets out two phases. Until October 31, 2026, both legacy versions "remain fully operational," and v3 is live and recommended for all new development. From November 1, 2026, v1 and v2 "will be retired," and all traffic should be routed to v3 by that date. The Quick Start repeats the shorter version in a single line: v1 and v2 are supported until October 31, 2026.

The dates on HeyGen's own pages do not all agree, and a developer planning a cutover should know where they split. The timeline says November 1. The same page then says legacy responses carry a Sunset header of Sat, 31 Oct 2026 00:00:00 GMT, and the JSON warning text says the endpoint "will be removed on 2026-10-31." HeyGen's own migration checklist tells teams to test migrated endpoints in staging before October 31, 2026. Three of those four markers point at October 31, so the safe reading is to be on v3 before the earlier date.

The changelog entry behind the timeline ran in April 2026, headed "v1 and v2 endpoints sunset on October 31, 2026." It added one qualifier worth checking against your stack: the Studio API for multi-scene work and the Template API "will continue to be supported on v2 until a v3 equivalent is available." The current comparison page now lists both as having v3 equivalents, so that stopgap appears to be closed, but the page is the live source and it is the one to re-read before you plan.

How to find the v1 and v2 calls your code still makes

You do not have to read the codebase first. HeyGen designed the deprecation so that running the integration tells you what to change. Every v1 and v2 response carries Deprecation: true and the Sunset header above, and the JSON body gains a warning object:

{
  "warning": {
    "message": "This v2 endpoint is Legacy and will be removed on 2026-10-31. Developers: migrate to POST /v3/videos. Documentation: https://developers.heygen.com/reference/create-video",
    "v3_endpoint": "POST /v3/videos",
    "docs_url": "https://developers.heygen.com/reference/create-video",
    "sunset_date": "2026-10-31"
  }
}

The v3_endpoint field is "the exact operation to move to," per HeyGen. Log it across a day of real traffic and you have your migration list, written by the API rather than by memory. The third-party write-up at LinkLoot adds a manual cross-check for calls that may never fire in a normal day: search code, no-code automations, webhooks and internal docs for /v1/, /v2/, video_status.get, video_translate, and old upload calls.

What replaces each v1 and v2 endpoint

HeyGen publishes the mapping, and the common swaps look like this. The comparison page lists more, covering templates, avatars, assets, folders, brand glossary and account info.

Translation captions are an easy miss: GET /v2/video_translate/caption has no direct successor, and the caption files now come from the srt_caption_url and vtt_caption_url fields on the translation's own detail response. If your pipeline fetched captions from a separate call, that call changes shape, not just its prefix.

What v3 adds that v1 and v2 never had

The comparison page keeps a separate table of v3-only surfaces, and this is the part of the migration that changes what you can build rather than where you point. Batch video creation, at POST /v3/videos/batches, submits up to 100 videos in one request. Managed webhooks at /v3/webhooks/endpoints replace the old callback_url parameter with event types, signed payloads, secret rotation and an event log. Avatar creation is one endpoint for footage, photo and prompt at POST /v3/avatars, with a required consent flow before a digital twin renders. HyperFrames renders HTML, CSS and JavaScript projects to video at POST /v3/hyperframes/renders. Voice design, lipsync, background removal, audio search and look packs round out the set.

The Video Agent, which turns one prompt into a scripted video, lives at POST /v3/video-agents on v3, and the Quick Start uses it for a first call. Video Translation covers "175+ languages with voice cloning and lip-sync," per the Quick Start's build list. Batch creation, avatar creation, HyperFrames, voice design, lipsync, background removal, audio search and look packs have no v1 or v2 equivalent, while the Video Agent and translation calls also exist on v1 and v2.

What changes besides the path

A renamed route is rarely the whole change, and HeyGen lists several platform shifts that touch client code:

• Pagination is cursor-based across every v3 list endpoint, not offset-based or absent.
• Creation endpoints take assets through one url / asset_id / base64 union.
• The video request body is a discriminated union on type (avatar, image, cinematic_avatar or studio) instead of a flat object.
• voice_id now falls back to the avatar's default voice when omitted, where v1 and v2 always required it.

The Make integration app, which is separate from HeyGen, shows what those shifts cost in practice. Its own migration notes say version 2 of the app uses v3 of the API, that connections from version 1 cannot be reused, that video_id replaces data.video_id at the top level, and that callers must map asset_id wherever they previously used an image key. Any integration that wrapped HeyGen will have comparable field-level work.

Your migration checklist

HeyGen's published checklist, in the order it gives:

1. Inventory your v1/v2 calls by logging the warning.v3_endpoint field on legacy responses.
2. Replace POST /v2/video/generate with POST /v3/videos, including multi-scene calls, which become type: "studio".
3. Replace GET /v1/video_status.get with GET /v3/videos/{video_id}.
4. Replace POST /v1/video_agent/generate with POST /v3/video-agents.
5. Replace avatar and voice listing calls with GET /v3/avatars and GET /v3/voices.
6. Replace POST /v1/audio/text_to_speech with POST /v3/voices/speech.
7. Replace POST /v2/template/{id}/generate with POST /v3/templates/{id}.
8. Replace POST /v2/video_translate with POST /v3/video-translations, and read captions from the detail response.
9. Replace GET /v1/user/me and GET /v2/user/remaining_quota with GET /v3/users/me.
10. Move /v1/webhook/endpoint.* management to /v3/webhooks/endpoints.
11. Update pagination logic to cursor-based where applicable.
12. Test all migrated endpoints in staging before October 31, 2026.

What the docs do not settle

Two things are worth flagging because the published pages do not answer them. The first is the date itself: with the timeline on November 1 and the Sunset header and warning text on October 31, there is no single cutoff HeyGen states without a contradiction, and a developer should treat October 31 as the working deadline. The second is price. HeyGen's API pricing help page says the API runs on a pay-as-you-go model separate from any subscription, that usage "is measured in US dollar amount" and that cost "varies by avatar engine and feature." The page prices those features by the minute, the second or the call, so a migration budget has to be built from your own expected volume rather than one published figure. The page also notes that HeyGen stopped offering free API credits in February 2026, that a standard API plan allows 10 videos processed at once, and that Enterprise workspaces get 20 concurrent jobs and can burst up to 50 more per workflow type at 1.5 times the contract rate. Re-read the pricing page, not this article, before you size a bill.

Worth knowing before you rename anything: HeyGen's page lists v3 replacements for avatar video, translation, templates and webhooks, but it does not claim the v3 call is a drop-in for the v2 one. The request body, the asset inputs and the pagination all move with the path, which is why the checklist ends on a staging test rather than a deploy.

Start with the API itself: create a key, confirm it with GET /v3/users/me, then run your current integration for a day and collect the warning.v3_endpoint values your own traffic reports.