Skip to content

v0.2.0

Release Date: 2026-07-19

Adds asset upload, v2 avatar discovery, a public-avatar catalog, and an OmniAvatar render adapter — together enabling audio-driven avatar video generation behind the provider-agnostic OmniAvatar interfaces.

Highlights

  • New asset package for uploading audio, images, and video to HeyGen's asset service (upload.heygen.com, a separate host from the main API)
  • avatar.ListV2/SearchV2 return generation-ready v2 avatar IDs, plus a static public-avatar catalog
  • New omniavatar subpackage — an OmniAvatar render adapter on top of this SDK

Added

  • asset.Client with Upload(ctx, contentType, reader) returning a hosted Asset whose URL is usable in other HeyGen APIs — for example as video.VoiceInput{Type: "audio", AudioURL: ...} for audio-driven video generation. Includes asset.ContentType* constants (JPEG, PNG, MP4, WebM, MPEG audio), asset.WithBaseURL, and the Client.Asset facade field
  • heygen.Client.RequestURL for raw-body requests against absolute URLs, used by endpoints hosted outside the configured API base URL
  • avatar.ListV2 and avatar.SearchV2 for the v2 avatars API, returning IDs directly usable as avatar_id in generation (unlike the v3 avatar-group IDs, which the generation endpoint rejects)
  • liveavatar public avatar catalog: PublicAvatars (26 avatars), GetAvatarByID/GetAvatarByName, gender/type filters, avatar constants, and panel presets
  • omniavatar subpackage: an OmniAvatar render adapter implementing the omniavatar-core render interfaces (render.Provider, render.AudioUploader via the asset API, render.AvatarLister via v2 avatars) on top of this SDK. It depends only on omniavatar-core, keeping HeyGen-specific render knowledge in this repo. The real-time (live) LiveAvatar adapter, which needs LiveKit, lives in the batteries-included omniavatar package
  • Unit tests for asset upload (headers, body, error envelope), RequestURL, retry body rewind, and v2 avatars

Fixed

  • Retries now rewind the request body via GetBody, so a 429-retried POST resends the full payload instead of an empty body. Previously a rate-limited JSON POST (or asset upload) would silently retry with an empty body.

Dependencies

  • Require omniavatar-core v0.3.0 (interfaces + render helpers) for the render adapter
  • Bump github.com/livekit/protocol to v1.50.0

Documentation

  • README: asset upload feature and usage, API coverage row, and an OmniAvatar Integration section
  • MkDocs site: Asset API page and the shared PlexusOne theme

Full Changelog | Compare