Wevion's Avatar library (/creative-hub/avatars): browse shared avatars and create custom text-to-avatar or photo-to-avatar spokespeople for UGC ads.

Avatar library & custom avatars

TL;DR: The Avatars module (/creative-hub/avatars, GA, no feature flag) is Wevion's reusable avatar library. Browse a shared library of avatars, filter by scenario / gender / age, and create your own custom avatar in two modes: text-to-avatar (describe it) or photo-to-avatar (upload a source image). Backed by GET/POST/DELETE /api/v1/creative-hub/avatars. Custom creation queues an async generation (HTTP 202) polled every 3 seconds. This is distinct from the legacy HeyGen talking-avatar video route in ch-115.

Who is this for

Mediabuyers producing UGC-style spokesperson creatives who want a persistent, reusable roster of avatars — either curated library faces or custom avatars matched to a brand persona.

Library vs custom avatars

The avatar list (GET /api/v1/creative-hub/avatars) returns two kinds of records, distinguished by the is_library flag:

• Library avatars — a shared, curated set available to every team.
• Your avatars — custom avatars your team created.

The scope query filter selects which set you see: library, mine, or all.

Filters

The list endpoint accepts these query parameters (verified apps/backend/src/routes/api/creative-hub-avatars.route.ts):

• scenario
• gender
• age_bracket
• q (free-text search)
• scope (library | mine | all)

The response also returns estimated_credits — the credit cost of creating a new custom avatar.

Avatar fields

Each avatar record includes: name, gender, age_bracket, scenario, image_url, thumbnail_url, preview_video_url, prompt, voice_id, provider, is_library, status, tags, and metadata, plus ownership (team_id, created_by) and timestamps.

Creating a custom avatar

POST /api/v1/creative-hub/avatars queues a custom avatar generation. Request body:

• mode (required): text (text-to-avatar) or photo (photo-to-avatar)
• name (required, 1–120 chars)
• prompt (optional, ≤2000 chars) — the description for text mode
• template_avatar_id (optional) — base an avatar on a template
• source_image_url (optional) — the source photo for photo mode
• gender (optional, ≤20 chars)
• age_bracket (optional, ≤20 chars)
• scenario (optional, ≤40 chars)
• voice_id (optional)

Response: 202 Accepted with avatar_id, generation_id, status, estimated_credits, and polling_interval_ms (3000). The avatar appears in your library with a working status until the generation completes.

Deleting an avatar

DELETE /api/v1/creative-hub/avatars/:id soft-deletes a custom avatar you own. Library avatars are shared and are not user-deletable through this flow.

How to use it

1. Open Creative Hub → Avatars (/creative-hub/avatars).
2. Browse the library, or switch scope to mine to see only your custom avatars.
3. Filter by scenario, gender, age, or search text to narrow results.
4. To create a custom avatar, choose text or photo mode, give it a name, and provide a prompt (text) or a source image (photo). Optionally set gender, age bracket, scenario, and a voice.
5. Submit. Wevion returns a queued generation and polls every 3 seconds until the avatar is ready.

Relationship to talking-avatar video

This library manages the avatar identities themselves. Turning an avatar into a lip-synced talking video (from a script) is the legacy HeyGen flow documented in ch-115 create AI avatars. Use the library here to build and organize the faces; use ch-115 to make them speak.

Credits and errors

Creating a custom avatar costs the estimated_credits shown on the list and create responses. If you lack credits, the create route returns 402 (insufficient_credits), or 402 credit_cap_exceeded when a monthly cap is hit; other failures return 500 generation_failed. See ch-112 AI credits.

FAQ

What is the difference between the avatar library and custom avatars in Wevion?

The Wevion avatar library is a shared, curated set of avatars available to every team, marked with is_library. Custom avatars are ones your team creates and owns. The list endpoint's scope filter lets you view library, mine, or all. You can search and filter both by scenario, gender, and age bracket to find the right spokesperson quickly.

How do I create a custom avatar?

Open Creative Hub → Avatars and start a custom avatar in one of two modes: text-to-avatar, where you describe it with a prompt, or photo-to-avatar, where you upload a source image URL. Give it a name and optionally set gender, age bracket, scenario, and a voice. Wevion queues the generation and returns HTTP 202, then polls every three seconds until it is ready.

How is this different from the HeyGen avatar video in ch-115?

The Avatars library manages avatar identities — the faces you reuse across creatives. The ch-115 flow is a separate legacy route that renders a lip-synced talking video from a script through HeyGen. Build and organize your avatars here, then generate spokesperson videos from them where that flow is available. The two work together rather than overlapping.

Can I delete a custom avatar?

Yes. Wevion soft-deletes custom avatars you own through DELETE /api/v1/creative-hub/avatars/:id, so they disappear from your library while remaining recoverable at the data layer. Shared library avatars are not deletable through this flow because they belong to the curated set available to all teams, not to a single team.

Steps

1. Open Creative Hub → Avatars (/creative-hub/avatars).
2. Browse the library, or switch scope to mine to see only your custom avatars.
3. Filter by scenario, gender, age, or search text to narrow results.
4. To create a custom avatar, choose text or photo mode, give it a name, and provide a prompt (text) or a source image (photo). Optionally set gender, age bracket, scenario, and a voice.
5. Submit. Wevion returns a queued generation and polls every 3 seconds until the avatar is ready.

Last updated: 2026-07-02

Related articles

• Create AI avatars (UGC videos)