# Dev Avatar Service

> Deterministic default-avatar generator per user.

- **Type:** Skill
- **Install:** `agentstack add skill-picsart-gen-ai-skills-dev-avatar-service`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [PicsArt](https://agentstack.voostack.com/s/picsart)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [PicsArt](https://github.com/PicsArt)
- **Source:** https://github.com/PicsArt/gen-ai-skills/tree/main/skills/dev-avatar-service

## Install

```sh
agentstack add skill-picsart-gen-ai-skills-dev-avatar-service
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Avatar service

A service endpoint that returns a branded avatar for any user: photoreal, illustrated, or pixel, deterministic from a seed (user ID / email hash / initials). Built around a fallback hierarchy — real photo → upload → AI from initials → static default — with caching by seed so you pay once per user.

## When to Use

- New user signup where you need an immediate profile image.
- Comment systems or forums that default to gravatars.
- Team pages, directories, leaderboards without uploaded photos.
- Placeholder avatars during onboarding before the user picks one.
- Branded alternative to Gravatar / UI Avatars / DiceBear.
- Mock data for staging/demo environments.

Not for: deepfaking real people from a single photo (wrong tool + wrong ethics), or stylizing an already-great uploaded photo — let users keep their own.

## Prerequisites

Before building, ask (one message, 5 questions):

1. **Seed source**: user ID, email hash, username, initials? Is it stable forever?
2. **Style**: photoreal portrait, illustrated (Pixar/Disney-ish), flat vector, pixel art, claymorphic, monogram?
3. **Brand palette**: accent color for backgrounds + monogram fallbacks.
4. **Storage + cache**: S3/CDN + DB column, Picsart Drive URL, or KV key? TTL?
5. **Fallback chain**: photo → AI avatar → initials-on-color → default SVG? Order matters.

Skip if the user hands over a detailed brief.

## How to Run

1. **Decide the fallback hierarchy first.** This is the whole service:
   ```
   1. user.photo_url          → return as-is
   2. cache.get(seed)         → return stored AI avatar URL
   3. gen-ai generate         → store URL + return
   4. initials on brand color → SVG fallback (no credits)
   5. static /default.png     → last resort
   ```

2. **Estimate + validate model.**
   ```bash
   gen-ai models info recraftv4
   gen-ai pricing recraftv4
   gen-ai generate -m recraftv4 -p "illustrated avatar, seed abc123" \
     --aspect-ratio 1:1 --dry-run --debug
   ```

3. **Deterministic seed → prompt.** Hash the seed into stable attribute picks. Never inject `Math.random()` or timestamps.
   ```bash
   SEED="u_482c91"
   # Pick palette + mood from the seed, not from RNG
   HUE=$(printf "%s" "$SEED" | shasum | cut -c1-2)   # 0-255 from hash
   gen-ai generate -m recraftv4 \
     -p "illustrated profile avatar, round frame, abstract humanoid silhouette, HSL hue ${HUE}, friendly neutral expression, flat vector, centered composition, studio background" \
     --aspect-ratio 1:1 \
     --negative-prompt "text, watermark, letters, realistic face, specific person" \
     --save-to-drive --drive-folder avatars \
     --json --no-input | jq -r '.url'
   ```

4. **Cache the URL** (not the binary) keyed on the seed. Any store: Redis, KV, Postgres column, S3 + stable filename.

5. **Initials fallback (zero credits).** When gen-ai is down, rate-limited, or over budget — return an SVG built from the user's initials on a hue derived from the same seed. Users never see a broken image.
   ```ts
   const initials = name.split(' ').map(p => p[0]).slice(0, 2).join('').toUpperCase();
   const hue = parseInt(sha1(seed).slice(0, 2), 16);
   const svg = `${initials}`;
   ```

6. **Wire the endpoint.** `/avatar/:seed` → check photo → check cache → gen-ai → initials. 302 to CDN URL on success; inline SVG on fallback.

7. **Pre-warm the cache in batch** for existing users so your prod rollout doesn't hammer gen-ai live:
   ```bash
   gen-ai batch run avatars-backfill.json -c 4 -o ./avatars-out
   ```

## Quick Reference

Backfill 500 existing users:

```json
{
  "defaults": {
    "model": "recraftv4",
    "aspectRatio": "1:1",
    "negativePrompt": "text, watermark, letters, realistic face, specific person"
  },
  "jobs": [
    { "id": "u_482c91", "prompt": "illustrated profile avatar, round frame, flat vector, hue 42, friendly neutral, studio background" },
    { "id": "u_91ac3b", "prompt": "illustrated profile avatar, round frame, flat vector, hue 128, calm expression, studio background" },
    { "id": "u_7de119", "prompt": "illustrated profile avatar, round frame, flat vector, hue 201, warm smile, studio background" }
  ]
}
```

Output lands at `./avatars-out/.webp` — upload to your CDN under the same key. `results.json` becomes the seed → URL lookup table.

## Quick Reference

| Sub-task | Model | Why |
|----------|-------|-----|
| Illustrated / vector / flat avatars | `recraftv4` | Clean, consistent, cheap — ideal default |
| Photoreal portrait (synthetic, generic person) | `flux-2-pro` | Best faces; use with generic descriptors only |
| Pixel-art avatars | `recraftv4` with pixel-style prompt | Lowest credits, stylistic control |
| Stylize an uploaded real photo (opt-in) | `flux-kontext-pro` + `-i photo.jpg` | Edit model preserves identity |
| Cheap draft / style exploration | `gemini-3.1-flash-image` | Lowest per-call cost |
| Identity-locked variants across sizes | `ideogram-character` + `-i master.png` | Same face across multiple avatars |

Verify live IDs with `gen-ai models --mode image`.

## Procedure

- **Determinism = cacheability.** Derive every variable attribute (hue, pose, expression) from a hash of the seed. Same seed → same prompt → same image → one credit forever.
- **Version the prompt template.** Bump `V=2` in the cache key when you restyle; old avatars age out, new ones regenerate on demand.
- **Fallback is not optional.** Initials-on-hue SVG must always work. Never let the UI render a broken avatar because gen-ai 429'd.
- **Negative prompt matters.** Always exclude `text, watermark, letters, realistic face of specific person` — avatars must not resemble real celebrities or render accidental copy.
- **Don't generate on every page load.** Generate once per seed, cache forever (or until template version bump). A viral signup spike must not trigger a gen-ai spike.
- **Use Drive for storage.** `--save-to-drive --drive-folder avatars` gives a stable CDN URL with no extra infra.
- **Pre-warm before launch.** Batch-generate for existing users; don't migrate live traffic onto a cold cache.
- **Respect user uploads.** If the user has uploaded a real photo, return that — never override. AI avatars are for *missing* photos only.
- **Rate-limit at the edge.** Cap gen-ai calls per IP per hour. A bot probing `/avatar/:random` can burn your credit budget in minutes.

## Pitfalls

| Pitfall | Fix |
|---------|-----|
| Regenerated avatar looks different on every refresh | Non-deterministic prompt — hash the seed, derive attributes, no RNG/timestamps |
| Cache never invalidates after restyle | Version the prompt template (`V=3` in the cache key) |
| AI renders real-looking faces resembling celebrities | Add `negativePrompt: "realistic face of specific person, celebrity, known individual"` |
| Text or watermarks appear in the avatar | Add `negativePrompt: "text, watermark, letters, logos"` |
| Bot traffic burns credit budget | Rate-limit per IP; allow only authed users to hit the generator; fallback to initials for anons |
| Gen-ai 429s cause broken avatar UI | SVG initials fallback must be the last step in the chain |
| Batch backfill half-fails | `gen-ai batch resume ` retries only failures |
| Different avatar style across the app | Commit the prompt template; never let callers pass raw prompts |

## Verification

Run `gen-ai whoami` to confirm authentication, then re-run the failed command with `--debug`.

## Cost & time

| Task | Credits | Time |
|------|---------|------|
| 1 avatar (Recraft V4, illustrated) | 1-2 | ~4-8s |
| 1 avatar (Flux 2 Pro, photoreal) | 3-5 | ~10-15s |
| 1 avatar (Gemini 3.1 Flash, draft) | 1 | ~3-5s |
| Initials SVG fallback | 0 | 99% cache hit rate — near-zero ongoing cost.

## See also

- `gen-ai-use.md` — CLI reference, auth, scripting with `--json --no-input` / `jq`
- `gen-ai-batch.md` — manifest shapes, batch resume, rate-limit strategy, Cloudflare Worker pattern
- `gen-ai-workflows.md` — Workflow 6 (headshot studio) for stylizing uploaded photos
- `dev-og-image-service` — same caching + determinism patterns for OG cards

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [PicsArt](https://github.com/PicsArt)
- **Source:** [PicsArt/gen-ai-skills](https://github.com/PicsArt/gen-ai-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-picsart-gen-ai-skills-dev-avatar-service
- Seller: https://agentstack.voostack.com/s/picsart
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.