HeyGen API v2 retirement: the date and the v3 endpoints

HeyGen's API v2 (and v1) is being retired: HeyGen's timeline says v1 and v2 endpoints stay fully operational until October 31, 2026 and are retired on November 1, 2026, and all traffic should move to v3 by then. The main swap is POST /v2/video/generate to POST /v3/videos, and every legacy response already names its v3 replacement.

The facts below come from HeyGen's own Endpoint Version Comparison and Quick Start pages, read on 2026-09-29. HeyGen can change them; check the page before you plan a cutover.

When does the HeyGen API v2 stop working?

HeyGen's page gives two phases. Until October 31, 2026, v1 and v2 remain fully operational, and v3 is live and recommended for new work. From November 1, 2026, v1 and v2 endpoints will be retired. The Quick Start says the same: v1/v2 are supported until October 31, 2026.

The dates on the page are not all the same day. The timeline says retirement on November 1, but legacy responses carry a Sunset header of Sat, 31 Oct 2026 00:00:00 GMT, and the warning text says the endpoint "will be removed on 2026-10-31". HeyGen's own checklist says to test migrated endpoints in staging before October 31, 2026, so plan to be on v3 before the earliest of those dates.

How do I find the v2 calls my code still makes?

Run your integration and read the responses. Per HeyGen, every v1 and v2 response carries Deprecation: true and a Sunset header, and the JSON body gains a warning object. Its v3_endpoint field is the exact operation to move to; HeyGen suggests logging it across a day of traffic to build your migration list.

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

What replaces each v1 and v2 endpoint?

The calls most integrations make, from HeyGen's feature map. The page lists more (templates, avatars, assets, account info).

What else changes in HeyGen API v3?

Beyond new paths, HeyGen lists platform changes that touch client code:

• Pagination: cursor-based on all v3 list endpoints, instead of offset-based or none.
• Request body: a discriminated union on type (avatar, image, cinematic_avatar or studio) instead of a flat object.
• Assets: one url / asset_id / base64 union on all v3 creation endpoints.
• Webhooks: managed endpoints with event types, signed payloads and secret rotation, instead of a callback_url parameter.
• Voice: voice_id falls back to the avatar's default voice when omitted.
• Translation captions: read from the translation's detail response instead of GET /v2/video_translate/caption.
• New in v3 only: POST /v3/videos/batches submits up to 100 videos in one request.

Should I move to v3 or to another avatar API?

If you stay on HeyGen, its page says all traffic should be routed to v3 by November 1, 2026. If you are also weighing a switch, a different API means rewriting requests, not renaming paths. Sume's avatar endpoint, for example, is not a drop-in replacement for HeyGen v3: `POST /v1/avatar-1.0/talking-video` accepts scripts Sume estimates at 4–60 seconds, resolution is currently 720p, and in current code the avatar speaks English only. It is billed per second of output: $0.184/s standard, $0.245/s plus, $0.55/s max (no product image), per API pricing. For a side-by-side, see Sume vs HeyGen; for HeyGen's own credit prices, see HeyGen API pricing.