Avatar catalog search: explore mode, seed and diversity

To browse Sume's reusable avatars without a search term, call POST /v1/avatar-catalog/search with no query: the mode defaults to explore, which applies seeded diversity jitter. Pass the same seed string and you get a stable order for that session; change the seed to reshuffle. diversity runs from 0 to 1 and defaults to 0.5 in explore mode and 0.2 in search mode, and limit is 1 to 100 (default 20).

What is the difference between search and explore?

Per the OpenAPI schema, a request with a query defaults to search, which keeps relevance-first deterministic ranking. A request with no or empty query defaults to explore. You can set mode yourself to override either default.

Results are scoped to public system avatars plus avatars owned by your workspace, and the response includes mode and seed_used so you can see which one ran.

How do I keep the order stable across pages?

Send the same seed on every call. The schema says identical seeds stay stable for explore and shuffle jitter, and that jitter is always seeded: it never uses an unseeded random call. Search without shuffle stays deterministic even when you omit the seed.

A natural choice is a session id from your app as the seed: the same visitor sees the same grid on reload, a new visitor gets another one.

import os
import requests

resp = requests.post(
    "https://api.sume.com/v1/avatar-catalog/search",
    headers={"Authorization": f"Bearer {os.environ['SUME_API_KEY']}"},
    json={"mode": "explore", "seed": "session-abc", "limit": 20, "diversity": 0.5},
    timeout=30,
)
resp.raise_for_status()
data = resp.json()["data"]
print(data["mode"], data["seed_used"], data["count"])
for a in data["avatars"]:
    print(a["handle"], a["search_score"])

What does diversity change?

The schema describes diversity as an attribute MMR knob: higher values spread results across attributes, and it maps to the MMR lambda as 1 minus diversity. Source-identity dedupe also collapses candidates that share a normalized still or photo URL before ranking, unless you set dedupe to off.

Once you pick an avatar, use its handle as avatar_handle on the avatar video route.