Pick a stock avatar by avoid_for and brand_safety_notes, not looks

Search the avatar catalog with POST /v1/avatar-catalog/search and read each result's metadata.suitability before you choose: best_for, acceptable_for, avoid_for, brand_safety_notes, and casting_notes tell you where a presenter works and where it does not. A face that looks right but lists your category under avoid_for is a casting miss you can avoid for free.

What the profile exposes

Per the Sume OpenAPI, results are scoped to public system avatars plus avatars owned by your workspace. Each result has id, handle, metadata, a search_score, and search_reasons. The metadata object (avatar_profile_v1) groups persona, appearance, suitability, sample media, search text, and provenance. The suitability block is the one that helps with a casting decision.

A casting query

The request takes a free-text query, a limit up to 100, and filters such as status (default ready), visibility, product_category, use_case, best_for, and language. By default auto_expand relaxes thin results, and the response lists what it relaxed in relaxed_filters, so check that field before trusting a result as an exact match.

This script asks for calm support-style presenters and prints anything whose avoid_for mentions the words you care about. The word list is yours, not a Sume taxonomy.

import json, os, urllib.request

API = "https://api.sume.com"
AVOID = {"support", "healthcare", "finance"}

def search(query):
    body = json.dumps({"query": query, "limit": 20,
                       "filters": {"status": "ready"}}).encode()
    req = urllib.request.Request(
        API + "/v1/avatar-catalog/search", data=body, method="POST",
        headers={"Authorization": "Bearer " + os.environ["SUME_API_KEY"],
                 "Content-Type": "application/json",
                 "User-Agent": "casting/1.0"})
    with urllib.request.urlopen(req, timeout=30) as r:
        return json.load(r)["data"]

data = search("calm clear explainer for customer support")
print("relaxed:", data.get("relaxed_filters"))
for a in data["avatars"]:
    suit = ((a.get("metadata") or {}).get("suitability")) or {}
    avoid = {w.lower() for w in suit.get("avoid_for", [])}
    flag = "SKIP" if avoid & AVOID else "ok"
    print(flag, a["handle"], suit.get("brand_safety_notes", "")[:80])

Then preview, do not guess

Metadata narrows the field; it does not replace looking at the face in your own scene. Pass two or three handles through the same script and compare their first frames with an avatar video preview before paying for any full render. A preview is the cheap place to find out that a presenter reads too young, too casual, or too salesy for your tone.

Metadata can be null on an avatar that has not been backfilled or curated, and the confidence and provenance fields say how sure the profile is. For an avatar you created yourself from a photo, expect to write your own casting notes in your own records. The create avatar docs cover the three ways to create one.