Stock AI avatars API: find a ready-made avatar for a talking video

To use a stock AI avatar with the Sume API, search the avatar catalog with POST /v1/avatar-catalog/search, pick a ready result, and pass its handle as avatar_handle to POST /v1/avatar-1.0/talking-video. Results cover public system avatars, which every authenticated caller can use, plus the avatars your own workspace owns.

The request and response fields come from the API reference schema, and the route is listed on Sume's API reference docs page, read on 2026-09-26. To make your own presenter instead, see How to create a reusable AI avatar.

How do I search the avatar catalog?

Send a text query to search, or leave it out to browse. With a query the default mode is search, a relevance-first ranking that stays deterministic unless you ask for shuffle. Without one the default is explore, which adds seeded diversity for browsing. Filters narrow either mode; this request asks for ready public avatars:

curl -X POST https://api.sume.com/v1/avatar-catalog/search \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "warm skincare creator",
    "filters": {
      "status": "ready",
      "visibility": "public",
      "product_category": "beauty"
    },
    "limit": 10
  }'

Which search fields can I send?

Every field is optional, including query:

What does a search result contain?

The response wraps data.avatars[] with count, the echoed query and filters, the mode used, seed_used, and relaxed_filters, which lists what auto_expand relaxed and is empty when nothing was. Each avatar carries:

• id and handle. The handle is what a talking video takes.
• metadata: an avatar_profile_v1 profile, or null. It describes the persona (summary, speaking style, language fit), the appearance, suitability such as best_for, avoid_for, and product_categories, and sample media.
• search_score and search_reasons: the text-search score metadata for that result.

How do I use a catalog avatar in a talking video?

The talking-video route builds a script-driven video from a ready avatar handle. Pass the result's handle as avatar_handle; the API currently resolves a public system avatar's handle as well as your own avatars'. Keep the default status: "ready" filter, since the route needs a ready avatar. If the avatar is not ready for video, the route answers 409 with avatar_not_ready.

You skip avatar creation, a one-time $0.95 per avatar on API pricing. The video itself bills at the per-second avatar-video rate, $0.184/s standard, $0.245/s plus, $0.55/s max (no product image), plus a 5.5% agent fee by default.

curl -X POST https://api.sume.com/v1/avatar-1.0/talking-video \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: catalog-avatar-video-001" \
  -d '{
    "avatar_handle": "HANDLE_FROM_SEARCH",
    "script": "Meet the Acme travel mug, now in three colors.",
    "aspect_ratio": "9:16"
  }'

What does the catalog search not do?

Catalog search finds avatars; it does not make or change them.

• It creates nothing. A new avatar is POST /v1/avatar-1.0/generate, a paid job.
• Private results are limited to the authenticated owner workspace, so you never see another workspace's avatars.
• auto_expand never relaxes language, visibility, or ownership. Set it to false for strict filters.
• On hosted MCP, the same search is avatars_search, listed with the read tools rather than the paid ones.