dev-avatar-service

Name: dev-avatar-service
Author: picsart

github.com/picsart開発6312 回インストール2 日前に更新

リポジトリ

dev-avatar-service について

dev-avatar-serviceは、固定シードとフォールバック順序を使うブランドアバターのエンドポイント構築スキルです。生成、キャッシュ、イニシャル入りSVGへのフォールバック、既存ユーザー向けの一括準備を扱います。

主な機能

01シードに基づく一貫したアバター
02写真と生成アバターのフォールバック
03シード単位のURLキャッシュ
04イニシャル入りSVGへのフォールバック
05キャッシュの一括事前生成

活用シーン

01サインアップ時のアバター提供
02フォーラムやディレクトリの画像補完
03オンボーディング中のプレースホルダー表示
04ステージングデモ用アバターの準備

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/picsart/gen-ai-skills --skill dev-avatar-service

インストール後、Claude Code で/dev-avatar-serviceを入力して読み込まれたか確認します。

詳細

アバターサービス

あらゆるユーザー向けに、ブランドイメージに合ったアバター（フォトリアル、イラスト、ピクセルアート）を返すサービスエンドポイントです。シード（ユーザー ID／メールアドレスのハッシュ／イニシャル）から結果が決まります。フォールバックの優先順位（実際の写真 → アップロード画像 → イニシャルから AI 生成 → 静的なデフォルト画像）を軸に構築され、シードごとにキャッシュするため、ユーザーごとの費用は一度だけです。

使用する場面

すぐにプロフィール画像が必要な新規ユーザー登録。
デフォルトでグラバターを使用するコメントシステムやフォーラム。
アップロードされた写真がないチームページ、ディレクトリ、リーダーボード。
ユーザーがアバターを選ぶ前のオンボーディング中に表示するプレースホルダーアバター。
Gravatar／UI Avatars／DiceBear の代わりとなる、ブランドに合ったアバター。
ステージング／デモ環境用のモックデータ。

対象外：1 枚の写真から実在の人物のディープフェイクを作成すること（ツールも倫理も不適切です）、またはすでに素晴らしいアップロード済み写真をスタイライズすること（ユーザーが自分の写真をそのまま使えるようにしてください）。

前提条件

構築を始める前に、以下の 5 つの質問を 1 回のメッセージで確認してください。

シードのソース：ユーザー ID、メールアドレスのハッシュ、ユーザー名、イニシャルのどれですか？永久に変わらない値ですか？
スタイル：フォトリアルなポートレート、イラスト（Pixar／Disney 風）、フラットベクター、ピクセルアート、クレイモーフィズム、モノグラムのどれですか？
ブランドパレット：背景とモノグラムのフォールバックに使うアクセントカラーは何ですか？
ストレージとキャッシュ：S3／CDN と DB カラム、Picsart Drive URL、KV キーのどれですか？TTL はどうしますか？
フォールバックの順序：写真 → AI アバター → 色付き背景にイニシャル → デフォルト SVG のどれにしますか？順序が重要です。

ユーザーが詳細なブリーフを渡してくれた場合は、省略してください。

実行方法

**まずフォールバックの優先順位を決めます。**サービス全体の要となる部分です。

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

モデルを見積もり、検証します。

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

**決定的なシード → プロンプト。**シードをハッシュ化して、固定の属性を選びます。Math.random() やタイムスタンプは絶対に埋め込まないでください。

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'

シードをキーにして、バイナリではなく URL をキャッシュします。保存先には、Redis、KV、Postgres カラム、または固定ファイル名を使う S3 を利用できます。

**イニシャルへのフォールバック（クレジット不要）。**生成 AI が停止中、レート制限中、または予算超過の場合は、同じシードから導出した色相を背景にユーザーのイニシャルを配置した SVG を返します。ユーザーに壊れた画像を見せることはありません。

const initials = name.split(' ').map(p => p[0]).slice(0, 2).join('').toUpperCase();
const hue = parseInt(sha1(seed).slice(0, 2), 16);
const svg = `<svg viewBox="0 0 64 64"><rect width="64" height="64" fill="hsl(${hue} 70% 45%)"/><text x="32" y="40" text-anchor="middle" font-size="28" fill="#fff" font-family="system-ui">${initials}</text></svg>`;

エンドポイントを接続します。/avatar/:seed → 写真を確認 → キャッシュを確認 → 生成 AI → イニシャル。成功時は CDN URL に 302 リダイレクトし、フォールバック時はインライン SVG を返します。
**既存ユーザー分のキャッシュをバッチで事前にウォームアップします。**これにより、本番環境へのリリース時に生成 AI へ大量のリクエストが集中するのを防げます。
```
gen-ai batch run avatars-backfill.json -c 4 -o ./avatars-out
```

クイックリファレンス

既存ユーザー 500 人分をバックフィルします。

{
  "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" }
  ]
}

出力は ./avatars-out/<user-id>.webp に保存されます。同じキーで CDN にアップロードしてください。results.json はシード → URL のルックアップテーブルになります。

クイックリファレンス

サブタスク	モデル	理由
イラスト／ベクター／フラットなアバター	`recraftv4`	きれいで一貫性があり、低コスト。デフォルトに最適です
フォトリアルなポートレート（合成、一般的な人物）	`flux-2-pro`	顔の品質が最高です。一般的な特徴の記述だけで使用してください
ピクセルアートのアバター	ピクセルスタイルのプロンプトを使った `recraftv4`	クレジット消費が最も少なく、スタイルを制御できます
アップロードされた実際の写真のスタイライズ（オプトイン）	`flux-kontext-pro` + `-i photo.jpg`	編集モデルは本人の特徴を維持します
低コストのドラフト／スタイルの検討	`gemini-3.1-flash-image`	呼び出しごとのコストが最も低くなります
サイズ違いでも本人の特徴を固定したバリエーション	`ideogram-character` + `-i master.png`	複数のアバターで同じ顔を維持します

gen-ai models --mode image で、利用可能な最新の ID を確認してください。

手順

決定性＝キャッシュ可能性です。 すべての可変属性（色相、ポーズ、表情）をシードのハッシュから導出します。同じシード → 同じプロンプト → 同じ画像 → クレジット消費は一度だけです。
プロンプトテンプレートにバージョンを付けます。 スタイルを変更したら、キャッシュキーの V=2 を更新します。古いアバターは順次失効し、新しいアバターは要求に応じて再生成されます。
フォールバックは必須です。 イニシャルを色相付きで表示する SVG は、常に動作する必要があります。gen-ai が 429 を返したからといって、UI で壊れたアバターを表示してはいけません。
ネガティブプロンプトは重要です。 常に text, watermark, letters, realistic face of specific person を除外します。アバターが実在の有名人に似たり、意図せず文字を描画したりしないようにします。
ページを読み込むたびに生成しないでください。 シードごとに一度生成し、キャッシュを永続的に保持します（テンプレートのバージョンを上げる場合を除きます）。登録が急増しても、gen-ai の呼び出しが急増しないようにします。
保存には Drive を使用します。 --save-to-drive --drive-folder avatars を指定すると、追加のインフラなしで安定した CDN URL を利用できます。
ローンチ前にウォームアップします。 既存ユーザー分を一括生成します。キャッシュが空の状態で、稼働中のトラフィックを移行しないでください。
ユーザーのアップロードを尊重します。 ユーザーが実際の写真をアップロードしている場合は、それを返し、決して上書きしないでください。AI アバターは写真がない場合にのみ使用します。
エッジでレート制限します。 IP ごとの gen-ai 呼び出しを 1 時間あたりで制限します。/avatar/:random を試すボットが、数分でクレジット予算を使い切る可能性があります。

注意点

注意点	対処方法
更新するたびにアバターが異なる	プロンプトが非決定的です。シードをハッシュ化し、属性を導出して、乱数やタイムスタンプを使わないでください
スタイル変更後もキャッシュが無効にならない	プロンプトテンプレートにバージョンを付けます（キャッシュキーで `V=3` を指定）
AI が有名人に似たリアルな顔を生成する	`negativePrompt: "realistic face of specific person, celebrity, known individual"` を追加します
アバターにテキストやウォーターマークが表示される	`negativePrompt: "text, watermark, letters, logos"` を追加します
ボットのトラフィックがクレジット予算を使い切る	IP ごとにレート制限します。認証済みユーザーのみがジェネレーターを利用できるようにし、匿名ユーザーにはイニシャルを表示するフォールバックを使用します
Gen-ai の 429 によってアバター UI が壊れる	SVG のイニシャル表示によるフォールバックを、処理チェーンの最後の手順にします
一括バックフィルが一部失敗する	`gen-ai batch resume <out>` を実行すると、失敗分のみ再試行します
アプリ内でアバターのスタイルが統一されない	プロンプトテンプレートをコミットし、呼び出し元から生のプロンプトを渡せないようにします

検証

gen-ai whoami を実行して認証を確認し、その後、失敗したコマンドを --debug を付けて再実行します。

コストと時間

タスク	クレジット	時間
アバター 1 枚（Recraft V4、イラスト）	1-2	約 4-8 秒
アバター 1 枚（Flux 2 Pro、フォトリアル）	3-5	約 10-15 秒
アバター 1 枚（Gemini 3.1 Flash、下書き）	1	約 3-5 秒
イニシャルの SVG フォールバック	0	<1ms
キャッシュ読み取り（KV/Redis ヒット）	0	約 2-5ms
同時実行数 4 で 500 件を一括処理	約 750-1000	約 15-20 分

通常の状態では、キャッシュヒット率が 99% を超え、継続的なコストはほぼゼロになる見込みです。

基本情報

作者: picsart
リポジトリ: picsart/gen-ai-skills
カテゴリ: 開発
インストール数: 312
GitHub スター: 6

問題を報告

dev-avatar-service

dev-avatar-service について

主な機能

活用シーン

インストール

詳細

アバターサービス

使用する場面

前提条件

実行方法

クイックリファレンス

クイックリファレンス

手順

注意点

検証

コストと時間

関連項目

コメント