visual-identity

Name: visual-identity
Author: letta-ai

github.com/letta-aiクリエイティブ・メディア152121 回インストール4 週間前に更新

リポジトリ

visual-identity について

キャラクターの一貫性を保つ画像生成と、単発のテキスト画像生成に対応するスキルです。アバターやキャラクターアート、場面のバリエーション作成向けで、OpenAI gpt-image-1 または Flux Kontext Pro を利用します。

主な機能

01セッションをまたいだキャラクター参照の保持
02参照画像を使った場面生成
03テキストプロンプトから単発画像を生成
04OpenAI または Flux の選択
05アスペクト比と出力形式の設定

活用シーン

01エージェントのアバターやキャラクター作成
02同じ顔で異なる場面を生成
03提供された写真をもとにバリエーション作成
04一貫性を保持しない単発画像の生成

インストール

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

$npx skills add https://github.com/letta-ai/skills --skill visual-identity

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

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

LICENSE

assets/

visual-identity-small.svg

references/

api.md

scripts/

generate_image.py

詳細

ビジュアルアイデンティティ

セッションをまたいでも一貫性を保つ、永続的なビジュアルアイデンティティを構築します。OpenAI（gpt-image-1）と Flux Kontext Pro に対応しています。

2 つのワークフローがあります。

ビジュアルアイデンティティ（メイン）：参照用の外見を確立し、同じ顔や特徴を保った新しいシーンを生成します。アイデンティティは、セッションをまたいでエージェントのメモリに保持されます。
テキストから画像生成（サブ）：アイデンティティを保持せず、テキストプロンプトから一度限りの画像を生成します。

使用する場面

ユーザーが「あなたの見た目を見せて」と頼んだり、エージェントのセルフィーを希望したりした場合
ユーザーがアバター、プロフィール写真、キャラクターアートを希望した場合
ユーザーがビジュアルアイデンティティ（シーンをまたいで一貫したキャラクター）を作成したい場合
ユーザーが参照写真を提供し、バリエーションや新しいシーンを希望した場合
ユーザーが画像の生成や作成を依頼した場合

環境

スクリプトは環境変数に基づいて、使用するプロバイダーを自動検出します。

優先度	環境変数	プロバイダー	備考
1 番目	`OPENAI_API_KEY`	OpenAI gpt-image-1	推奨。すでに設定しているユーザーがほとんどです。
2 番目	`BFL_API_KEY`	Flux Kontext Pro	顔の一貫性に優れています。BFL アカウントが必要です。

--provider openai または --provider flux を指定すると、プロバイダーを上書きできます。

どちらのキーも設定されていない場合は、ユーザーに案内してください。

OpenAI（推奨）：すでに OPENAI_API_KEY が設定されている可能性があります。設定されていない場合は、https://platform.openai.com/api-keys
Flux：アカウントの作成先は https://api.bfl.ai、キーの取得先は https://api.bfl.ai/auth/login、クレジットの取得先は https://api.bfl.ai/credits です。

チャットでキー全体を貼り付けるよう、ユーザーに求めないでください。

依存関係

不足している場合はインストールしてください（uv を推奨）。

uv pip install requests Pillow

uv が利用できない場合：

pip3 install requests Pillow

ワークフロー 1：ビジュアルアイデンティティ（キャラクターの一貫性）

これはメインのワークフローです。参照用の外見を確立し、同じ顔、骨格、特徴を保った新しいシーンを生成することが目的です。

ステップ 1：参照用の外見を確立する

ユーザーが写真を提供するか、ベースとなるキャラクターを生成します。

オプション A -- ユーザーが参照写真を提供する場合： ユーザーが画像ファイルを貼り付けるか、指定します。その画像を永続的なアイデンティティディレクトリに保存します（以下の「ビジュアルアイデンティティの永続化」を参照）。

オプション B -- テキストからベースとなるキャラクターを生成する場合： テキストから画像を生成して、最初のキャラクターを作成します。身体的特徴を非常に具体的に指定してください。プロンプトの例：

肩までの長さの赤褐色の髪、緑色の目、薄いそばかすがあり、黒いレザージャケットを着た若い女性のポートレート。すっきりとした背景、スタジオ照明、3:4 のポートレート。

生成結果を参照画像として保存します。

ステップ 2：参照画像を使ってシーンを生成する

参照画像を base64 エンコードした input_image として渡します。

python3 <path-to-skill>/scripts/generate_image.py edit \
  --reference /path/to/canonical.jpg \
  --prompt "The same person is sitting at a desk coding late at night, lit by monitor glow" \
  --out /tmp/identity_coding.jpg

ステップ 3：プロンプトの軸を保つ

参照画像を使うすべてのプロンプトに、アイデンティティを固定するフレーズを必ず含めます。これにより、顔の特徴を保つようモデルに指示できます。

顔、骨格、目の色、髪を正確にそのまま保ってください。

または、より自然な形でプロンプトに組み込みます。

同じ男性が夕暮れ時の熱帯のビーチで、リネンシャツを着てくつろいでいます。ゴールデンアワーの照明。顔、骨格、目の色、髪を正確にそのまま保ってください。

ステップ 4：ユーザーと一緒に調整する

生成結果をそれぞれ見せて、フィードバックを求めます
フィードバックに基づいて、シーン、服装、照明、または設定を調整します
一貫性を保つため、必ず同じ参照画像を再利用します
ユーザーがベースの外見を変えたい場合は、ステップ 1 に戻ります

セッションの流れの例

ユーザー：「私のビジュアルアイデンティティを作ってください。これが私の写真です」
エージェント：参照画像を保存し、2～3 つのシーン（ビーチ、オフィス、ハイキング）を生成します
ユーザー：「ビーチの画像が気に入りましたが、帽子をかぶせてください」
エージェント：同じ参照画像を使って、帽子をかぶったビーチのシーンを再生成します
ユーザー：「今度は料理をしている私の画像を作ってください」
エージェント：同じ参照画像を使って、新しいシーンを生成します

ビジュアルアイデンティティの永続化

セッションをまたいで保持されるものは 2 つあります。参照画像（バイナリ）とアイデンティティのメタデータ（Markdown）です。それぞれ別の場所に保存されます。

参照画像：エージェントのデータディレクトリ

正規の参照画像を ~/.letta/agents/$AGENT_ID/reference/visual-identity/canonical.jpg に保存します。バイナリ画像によって Git 管理のメモリーリポジトリが肥大化しないよう、これは memfs の外に保存します。reference/ ディレクトリはセッションをまたいで保持されます。

mkdir -p ~/.letta/agents/$AGENT_ID/reference/visual-identity
cp /tmp/generated_portrait.jpg ~/.letta/agents/$AGENT_ID/reference/visual-identity/canonical.jpg

アイデンティティのメタデータ：memfs

ビジュアルアイデンティティを確立したら、エージェントのメモリーファイルシステム内の reference/visual-identity.md にメモリーファイルを作成します。他のすべてのメモリーファイルと同様に、これは Git 経由で同期されます。

Memory ツールを使って作成します。

memory(command="create", reason="Store visual identity metadata",
  file_path="reference/visual-identity.md",
  description="Agent's persistent visual identity -- reference image path and appearance description.",
  file_text="## Reference Image\n~/.letta/agents/$AGENT_ID/reference/visual-identity/canonical.jpg\n\n## Appearance\n- Hair: shoulder-length auburn, slight wave\n- Eyes: green\n- Skin: light with freckles\n- Build: athletic\n- Distinguishing: small scar above left eyebrow\n\n## Anchoring Phrase\nKeep the exact same face, bone structure, eye color, and hair from the reference image.\n\n## History\n- Established: 2026-04-15\n- User feedback: \"make the hair a bit darker\" -> regenerated, approved")

読み込み時の自動検出

このスキルが読み込まれたら、エージェントのメモリーツリーで reference/visual-identity.md を確認します。存在する場合：

エージェントにはすでに確立されたアイデンティティがあります
すべての画像生成リクエストで、保存された参照画像のパスを使用します
保存されたアンカーフレーズをすべてのプロンプトの先頭に追加します
ユーザーにアイデンティティを再設定するよう求めません

存在しない場合、エージェントにはまだビジュアルアイデンティティがありません。ユーザーが画像を求めた場合は、作成を提案します。

アイデンティティの更新

ユーザーがビジュアルアイデンティティの変更を希望する場合：

新しい参照画像を生成するか、受け取ります
参照ディレクトリ内の canonical.jpg を上書きします
新しい外見の詳細をメモリーファイルに記録します
History セクションに変更を記録します

ワークフロー 2：テキストから画像を生成

アイデンティティを保持する必要がない、単発の画像生成に使用します。

python3 <path-to-skill>/scripts/generate_image.py generate \
  --prompt "A corgi wearing a tiny space helmet on the moon" \
  --out /tmp/corgi_moon.jpg

または、requests を使ってインラインで実行します（OpenAI）：

import requests, base64, os

resp = requests.post(
    "https://api.openai.com/v1/images/generations",
    headers={
        "Authorization": f"Bearer {os.environ['OPENAI_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "gpt-image-1",
        "prompt": "A corgi wearing a tiny space helmet on the moon",
        "n": 1,
        "size": "1024x1024",
        "quality": "medium",
    },
).json()

img = base64.b64decode(resp["data"][0]["b64_json"])
with open("/tmp/corgi_moon.png", "wb") as f:
    f.write(img)

パラメーター

パラメーター	値	デフォルト	プロバイダー	備考
`--prompt`	文字列	必須	Both	シーンの説明
`--reference`	ファイルパス	なし	Both	アイデンティティモードの参照写真（編集時のみ）
`--provider`	`openai`, `flux`	自動	Both	プロバイダーの自動検出を上書きします
`--aspect-ratio`	`1:1`, `3:4`, `4:3`, `16:9`, `9:16`	`3:4`	Both	ポートレートには `3:4` を使用します
`--output-format`	`png`, `jpeg`, `webp`	`png`	Both
`--quality`	`low`, `medium`, `high`	`medium`	OpenAI	画像品質
`--seed`	整数	ランダム	Flux	再現可能な結果にするため固定します
`--safety-tolerance`	0-6	2	Flux	値が大きいほど制限が緩和されます
`--guidance`	1.5-100	可変	Flux	プロンプトへの準拠度

プロンプト作成のベストプラクティス

物理的な場所、照明、服装、ポーズを具体的に指定します
ポートレートでは、アスペクト比に 3:4 または 4:3 を指定します
風景やシーンでは、16:9 を使用します
照明の方向や種類を含めます：「ゴールデンアワー」、「スタジオ照明」、「ネオン照明」
服装やアクセサリーを明示的に説明します
アイデンティティモードでは、顔の特徴を維持するためのアンカーフレーズを必ず含めます
参照写真と矛盾する指定は避けます（例：参照写真で髪が暗い場合に「金髪」と指定しない）

レート制限とコスト

API キーごとの同時リクエスト数は最大 6 件です
キュー待ち時間は通常 4～10 秒ですが、負荷が高い場合は 2 分以上に延びることがあります
リクエストが Pending のまま 120 秒を超えた場合は、一度再試行します
ポーリング間隔は 2 秒で十分です
Ready レスポンス内のダウンロード URL は署名付きで有効期限があるため、画像をすぐに保存してください

CLI リファレンス

CLI の完全なドキュメント：references/api.md

一般的なコマンド：

# Text-to-image
python3 <path-to-skill>/scripts/generate_image.py generate \
  --prompt "..." --out output.jpg

# Reference-based editing (visual identity)
python3 <path-to-skill>/scripts/generate_image.py edit \
  --reference photo.jpg --prompt "..." --out output.jpg

# Dry run (show request without sending)
python3 <path-to-skill>/scripts/generate_image.py generate \
  --prompt "..." --dry-run

# Custom aspect ratio and seed
python3 <path-to-skill>/scripts/generate_image.py generate \
  --prompt "..." --aspect-ratio 16:9 --seed 42 --out wide.jpg

エラー処理

OpenAI：

HTTP 400/422：通常、不正なリクエストまたはコンテンツポリシー違反です
HTTP 429：レート制限です。待ってから再試行してください
OPENAI_API_KEY が見つからない場合：ユーザーに https://platform.openai.com/api-keys を案内します

Flux：

Insufficient credits：ユーザーに https://api.bfl.ai/credits を案内します
HTTP 422：通常、不正なリクエストです。プロンプトとパラメーターを確認してください
Pending のタイムアウト：リクエストを再試行します。キューが混雑している可能性があります
BFL_API_KEY が見つからない場合：ユーザーに https://api.bfl.ai を案内します

両方：

画像が大きすぎて base64 にできない場合：エンコード前に 10MB 未満に縮小します
API キーが見つからない場合：「環境」セクションを参照してください

Markdown 対応

ログインしてコメント

基本情報

作者: letta-ai
リポジトリ: letta-ai/skills
カテゴリ: クリエイティブ・メディア
インストール数: 121
GitHub スター: 152

問題を報告

おすすめの Skills

すべての Skills

ai-video-generation

github.com/inference-sh

1.7M

inference.sh CLI で Google Veo、Seedance 2.0、HappyHorse、Wan、Grok など 40 以上のモデルを使って AI 動画を生成する。モデル：Veo 3.1、Seedance 2.0、HappyHorse 1.0、Wan 2.5、Grok Imagine Video、OmniHuman、Fabric、HunyuanVideo。機能：テキストから動画、画像から動画、参照から動画、動画編集、リップシンク、アバターアニメーション、動画アップスケーリング、フォーリー音。用途：ソーシャルメディア動画、マーケティングコンテンツ、解説動画、製品デモ、AI アバター。トリガー：video generation、ai video、text to video、image to video、veo、animate image、video from image、ai animation、video generator、generate video、t2v、i2v、ai video maker、create video with ai、runway alternative、pika alternative、sora alternative、kling alternative、seedance、happyhorse

ai-image-generation

github.com/inference-sh

1.7M

inference.sh CLI で GPT-Image-2.5、FLUX、Gemini、Grok、Seedream、Reve など 50 以上のモデルを使って AI 画像を生成する。モデル：GPT-Image-2.5 Flare、GPT-Image-2.5 Sunburst、GPT-Image-2、FLUX Dev LoRA、FLUX.2 Klein LoRA、Gemini 3 Pro Image、Grok Imagine、Seedream 4.5、Reve、ImagineArt。機能：テキストから画像、画像から画像、インペインティング、LoRA、画像編集、アップスケーリング、テキストレンダリング。用途：AI アート、製品モックアップ、コンセプトアート、ソーシャルメディア用グラフィック、マーケティングビジュアル、イラスト。トリガー：flux、image generation、ai image、text to image、stable diffusion、generate image、ai art、midjourney alternative、dall-e alternative、text2img、t2i、image generator、ai picture、create image with ai、generative ai、ai illustration、grok image、gemini image、gpt image、openai image、chatgpt image

ai-avatar-video

github.com/inference-sh

1.7M

inference.sh CLI で AI アバターやトーキングヘッド動画を作成します。おすすめ：P-Video-Avatar（最速、最安、TTS 内蔵）。その他：OmniHuman、Fabric、PixVerse。音声：Inworld TTS-2（100以上の言語に対応し、キャラクターの感情を調整可能）、ElevenLabs、Kokoro。機能：音声駆動アバター、テキストからアバター、リップシンク動画、トーキングヘッド生成、バーチャルプレゼンター、UGC コンテンツ。用途：AI プレゼンター、解説動画、バーチャルインフルエンサー、吹き替え、マーケティング動画、UGC 広告、ゲームアバター、NPC の会話。トリガー：ai avatar、talking head、lipsync、avatar video、virtual presenter、ai spokesperson、audio driven video、heygen alternative、synthesia alternative、talking avatar、lip sync、video avatar、ai presenter、digital human、ugc、ugc video、ugc ad、avatar ugc

remotion-render

github.com/inference-sh

1.6M

inference.sh を介して React/Remotion コンポーネントコードから動画をレンダリングします。TSX コードを渡すと MP4 を取得できます。useCurrentFrame、useVideoConfig、spring、interpolate、AbsoluteFill、Sequence など、すべての Remotion API に対応します。解像度、FPS、長さ、コーデックを設定できます。用途：プログラムによる動画生成、アニメーショングラフィック、モーションデザイン、データ駆動型動画、React アニメーションの動画化。トリガー：remotion、render video from code、tsx to video、react video、programmatic video、remotion render、code to video、animated video、motion graphics code、react animation video