ローカルまたはホスト型の vision LLM に画像を見せて、16×16 のピクセルアートへ変換する評価アプリです。 推論は 1 モデルずつ 実行し、結果は brushstroke として SQLite に保存します。後から複数 run を選んで、スクリーンショットのように side-by-side で同時再生できます。
- 画像アップロード、またはブラウザ上で絵文字を PNG 化して task 作成
- OpenAI公式 API、OpenAI互換 API、Gemini ネイティブ API で vision LLM を呼び出し
- 既定の
vision_planでは、VLM が元画像そのものから特徴を抽出し、16×16ドラフトを自己修正 - 必要なら実用変換用の
grid、まとめ塗りのbatch、旧来のstroke推論モードへ切り替え可能 vision_plan/vision_loop/batch/strokeモードではモデルが同じピクセルを塗り直す「後悔」や、全体の書き直しも記録- side-by-side replay、再生速度変更、途中停止、run/task 削除
- タイムラインのクリック / ドラッグでシーク、キーボード操作(Space 再生/停止、←/→ コマ送り、Shift+←/→ で±10、Home/End ジャンプ)
- 画像のドラッグ&ドロップや Ctrl+V 貼り付けでタスク作成、絵文字クイックチップでワンクリック作成
- 各 run の実行時間表示、操作成功のトースト通知
- SQLite 永続化:
data/pixel_showdown.db
このアプリは、BenchLocal の Pixelate テストと、次の公開投稿に着想を得た独立実装です。
https://x.com/stevibe/status/2070514425392681410
Pixelate や BenchLocal のソースコードは参照・利用していません。また、このプロジェクトは BenchLocal とは非提携です。
cd ai-pixel-art-converter
uv sync
cp .env.example .env.env を編集します。
LLM_PROVIDER=openai
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-5.5
OPENAI_API_KEY=your-openai-api-key
INFERENCE_MODE=vision_plan
MAX_BRUSHSTROKES=256
VISION_PLAN_PASSES=0
VISION_PLAN_MAX_PAINTED_CELLS=256
BATCH_STROKES=16OpenAI互換 API を使う場合は、LLM_PROVIDER=openai-compatible にして OPENAI_BASE_URL をローカルまたはホスト先の /v1 endpoint にします。
LLM_PROVIDER=openai-compatible
OPENAI_BASE_URL=http://127.0.0.1:8000/v1
OPENAI_MODEL=your-vision-model-name
OPENAI_API_KEY=not-needed
INFERENCE_MODE=vision_planGemini API を直接使う場合は、LLM_PROVIDER=gemini にして GEMINI_API_KEY を環境変数または .env に定義します。
LLM_PROVIDER=gemini
OPENAI_MODEL=gemini-3.1-flash-lite
GEMINI_API_KEY=your-google-ai-studio-key
INFERENCE_MODE=vision_planOPENAI_MODEL は現在のモデル名として使われ、UI で保存するモデル設定名や run 表示名の既定にもなります。Gemini でも同じ変数名を使えます。必要なら UI の API / モデル設定 からプロバイダ、API key、モデル名を保存できます。
起動します。
uv run python -m app.mainブラウザで http://127.0.0.1:8000 を開きます。
このアプリはローカル実行を前提にしています。API キーをブラウザ UI から扱うため、認証やリバースプロキシなしでインターネットへ公開しないでください。必要な場合だけ HOST=0.0.0.0 を指定できます。
テストを実行します。
uv run pytest- 画像をアップロードするか、
🐤、🪅、けなどを入力して 作成。 - API / モデル設定 でプロバイダとモデルを確認し、必要なら保存する。
- 1モデルずつ推論 で使うモデル設定を選び、推論開始。
- 別モデルを試すときは API / モデル設定 で別のモデル設定を保存してから、同じ task に対して run を追加。
- run を選択して ▶ を押すとまとめて再生できます。
補足: この実装は
load_settings()を run 作成時に呼ぶため、環境によっては server を再起動しなくても.envの変更が反映されます。ただしプロセス管理の混乱を避けるため、モデルを切り替えたら再起動する運用を推奨します。
既定の INFERENCE_MODE=vision_plan は VLM 評価用です。バックエンドはまず 元画像そのもの だけを渡し、VLMに特徴抽出と完成形の16×16設計をさせます。その後、各 refinement pass で 元画像 と VLM自身が作った現在ドラフト画像 と 現在gridテキスト を渡して、完全な rows を書き直させます。
重要: vision_plan では、元画像から作った16×16 downsample、target grid、セル単位の参照情報はVLMへ渡しません。
モデルは次の形式を返します。
{
"analysis": "compact visual notes",
"rows": [
["..", "..", "#F4C542", "..", "..", "..", "..", "..", "..", "..", "..", "..", "..", "..", "..", ".."]
]
}実際の rows 応答では 16 行、各行に 16 セルが必要です。
INFERENCE_MODE=vision_loop は、より逐次的な VLM 評価用です。バックエンドは各 iteration で 元画像 と 現在の16×16キャンバス画像 と 現在グリッドの座標テキスト を渡します。採点用の target_grid はプロンプトに出しません。
モデルは次のいずれかを返します。
{"strokes":[{"action":"paint","x":7,"y":5,"color":"#C000FF"}]}全体構造が間違っている場合は、ゼロからの書き直しとして完全な rows も返せます。
{
"rows": [
["..", "..", "#A020F0", "..", "..", "..", "..", "..", "..", "..", "..", "..", "..", "..", "..", ".."]
]
}実際の rows 応答では 16 行、各行に 16 セルが必要です。
完了判断もモデル自身が行います。
{"action":"done"}INFERENCE_MODE=grid は実用変換用です。バックエンドがまず完成形の 16x16 参照グリッドをプロンプトに渡し、feedback loop で改善します。VLM ベンチマークとしては答えに近い情報を渡すため、比較用途には vision_plan または vision_loop を使ってください。
{
"model": "your-vision-model-name",
"messages": [
{"role": "system", "content": "..."},
{
"role": "user",
"content": [
{"type": "text", "text": "current 16x16 canvas..."},
{"type": "image_url", "image_url": {"url": "data:image/png;base64,..."}}
]
}
],
"temperature": 0,
"max_tokens": 4096
}grid モードのモデル応答は次の形式です。
{
"rows": [
["..", "..", "#A020F0", "..", "..", "..", "..", "..", "..", "..", "..", "..", "..", "..", "..", ".."]
]
}アプリ側は最終的に採用したグリッドを stroke list に変換して保存するため、リプレイ UI は従来通り 1 ピクセルずつ再生できます。
INFERENCE_MODE=batch にすると、1 request で複数 brushstrokes を要求します。
{"strokes":[{"action":"paint","x":7,"y":5,"color":"#C000FF"}]}INFERENCE_MODE=stroke にすると旧来の 1 API call = 1 brushstroke 方式で動きます。
ローカルサーバが response_format をサポートする場合は、.env で OPENAI_RESPONSE_FORMAT_JSON=true にできます。
LLM が未準備でも UI と replay を確認できます。
MOCK_LLM=true
MOCK_DELAY_SECONDS=0.02このモードでは downsampled target grid を元に、API を呼ばずに疑似 stroke を生成します。vision_plan/vision_loop/batch/stroke モードでは stroke 列、grid モードでは一括グリッドとして動きます。
- vision 対応の model/API が必要です。text-only model では失敗します。
INFERENCE_MODE=vision_planが既定です。VLM には source-derived 16×16情報や scoring target を渡さず、元画像と自分のドラフトだけで改善させます。INFERENCE_MODE=vision_loopは逐次stroke寄りの評価モードです。元画像と現在キャンバスだけを見せますが、長いrunでは局所判断になりやすいです。INFERENCE_MODE=gridは実用変換用です。GRID_FEEDBACK_PASSES回まで refinement を行い、低品質出力は失敗扱いにします。INFERENCE_MODE=batchはBATCH_STROKES=16などで複数 stroke をまとめて要求します。モデルの「迷い」を残しつつ、API call 数を減らせます。INFERENCE_MODE=strokeは旧方式です。MAX_BRUSHSTROKES=256でも最大 256 API calls になります。SEND_IMAGE_EVERY_STEP=falseはbatch/strokeモード用です。速くなりますが、2 request 目以降は画像を再送しないため品質が落ちることがあります。- サーバは単一プロセス・単一 worker で動かしてください。内部 executor は
max_workers=1で、推論を 1 run ずつ流します。
このプロジェクトは MIT License で公開しています。詳細は LICENSE を参照してください。
絵文字から task を作成する際、ブラウザは Twemoji の SVG アセットを jsDelivr 経由で取得します。Twemoji のコードは MIT License、グラフィックは CC-BY 4.0 で公開されています。