draw-thing

Draw Thing

draw-things-cli によるローカル AI 画像・メディア生成です。Draw Things の現行コマンド体系を使用します：generate、models list、models ensure、models import、train lora。

対象範囲： Draw Things によるローカル画像生成、画像編集、モデルのセットアップ、モデル一覧の確認、インポート、短いローカルメディアの生成です。UI 実装（デザイン）、広告クリエイティブ戦略（ad-creative）、クラウド画像 API、一般的な AI モデル市場の調査は対象外です。

---

標準用語

用語	意味	該当しないもの
txt2img	テキストから画像を生成します：プロンプトを入力し、画像ファイルを出力します	img2img
img2img	画像から画像を生成します：入力画像とプロンプトを使用します	txt2img
media	--frames と動画出力を使った動画または音声付き動画の生成	UI アニメーション
model id	Draw Things のモデルファイル名、または --model で使用できるモデル参照	表示名の推測
recommended pack	この Mac 向けに承認された、現行の環境に対応するモデルセット	インストール済みの全モデル
legacy model	互換性のために保持されている旧モデル。デフォルトでは推奨されません	削除対象
cfg	現行 CLI の案内フラグ：--cfg	旧 --guidance-scale
strength	img2img の変更量：低いほど元画像を保持し、高いほど描き直します	出力スケール
seed	同一のプロンプトと設定で再現するための値	モデルの選択
config file	アプリの詳細設定に使う、--config-file で渡す JSON ファイル	CLI の直接フラグ

---

振り分け

$ARGUMENTS	モード	アクション
generate <prompt> / create <prompt>	生成	現行の最適な画像設定で txt2img を実行します
自然言語による画像の説明	自動：生成	プロンプトの意図を判定し、モデルを選択します
edit <path> <prompt> / transform <path>	編集	--image と --strength を使って img2img を実行します
画像のパス + 変更の意図	自動：編集	元画像を保持し、新しい出力ファイルを書き出します
video <prompt> / media <prompt> / animate <prompt>	メディア	--frames を使って短いローカルメディアを生成します
setup / download models / best models	セットアップ	環境を確認し、推奨モデルセットを揃えます
inventory / models / model status	一覧確認	モデル一覧ヘルパーを実行し、不足を要約します
import <path-or-url>	インポート	draw-things-cli models import を使います
model <name>	モデル情報	現在の用途、設定、ステータスを表示します
batch <prompt> / variations <prompt>	バッチ	シェルループを使い、複数のシードと出力を生成します
refine / iterate	調整	シードを固定し、パラメーターを 1 つ変更して再実行します
upscale <path> / controlnet ... / lora ...	詳細設定	実行前に config-file のワークフローを確認します
(空)	ヘルプ	CLI を確認し、モードと例を表示します

自動判定のヒューリスティック

1. インストール、ダウンロード、設定、または最適なモデルの選択を求めるプロンプト → セットアップ。
2. モデル一覧、現在のダウンロード状況、または不足しているモデルを尋ねるプロンプト → インベントリ。
3. 動画、モーション、mp4、mov、フレーム、またはアニメーションを尋ねるプロンプト → メディア。
4. 既存のファイルパスに加えて、編集／スタイル変更／変更／変換を求めるプロンプト → 編集。
5. 既存のファイルパスに加えて、アップスケール／制御／LoRA／インペイントを求めるプロンプト → 高度な操作。実行前に、現在の CLI／設定が対応しているか確認してください。
6. ファイルパスを含まない説明文 → 生成。
7. 曖昧な場合 → どのモードにするか尋ね、トレードオフを伝えてください。

---

前提条件プロトコル

生成またはモデルの変更を行う前に、必ず実行してください。

1. CLI を確認します：command -v draw-things-cli。
2. 見つからない場合は、インストールコマンドを表示して終了します：

   brew install drawthingsai/draw-things/draw-things-cli
   

3. インストール済みのコマンド構成を確認します：draw-things-cli generate --help。
4. セットアップ／インベントリでは、以下を優先してください：

   uv run python skills/draw-thing/scripts/model_inventory.py --format json
   

5. 常に --output を指定してください。指定しない場合、現在の CLI は対応端末でプレビューを表示するだけで、ファイルを書き込まないことがあります。

---

現在の最適モデルの方針

2026-05-15 時点で、この Mac は Apple M1 Pro、arm64、macOS 26.5、ユニファイドメモリ 32 GiB です。現在の Draw Things 最適化チェックポイントを使用し、ユーザーが互換性を明示的に求めない限り、旧式の SDXL／SD1.5／FLUX.1 系モデルは推奨しないでください。

役割	モデル ID	状態	デフォルトの用途
高速画像生成のデフォルト	z_image_turbo_1.0_q8p.ckpt	推奨	高速な下書き、8 ステップ、--cfg 0
テキスト／レイアウト／リアリズム重視	qwen_image_2512_q8p.ckpt	推奨	ポスター、タイポグラフィ、仕上がりの良い画像
クリエイティブ用途のベースモデル	z_image_1.0_q8p.ckpt	推奨	一般的なクリエイティブ探索
ハイエンド FLUX／参照／編集	flux_2_dev_q6p.ckpt	推奨	32 GiB での FLUX.2 ワークフロー
指示に基づく画像編集	qwen_image_edit_2511_q8p.ckpt	推奨	画像から画像への変換／編集プロンプト
アート／プロンプト追従の代替モデル	hidream_i1_full_q5p.ckpt	推奨ダウンロード	最高品質のアート向け代替モデル
ローカルでの高速メディア生成	ltx_2.3_22b_distilled_q6p.ckpt	推奨ダウンロード	短いテキスト／動画の生成
この構成に適した Wan メディアモデル	wan_v2.2_5b_ti2v_q8p.ckpt	推奨ダウンロード	32 GiB での最新 Wan 動画生成

旧式または重複するダウンロード済みモデルは、承認なしに削除対象にしないでください：flux_1_schnell_q8p.ckpt、flux_1_fill_dev_q8p.ckpt、および flux_2_klein_4b_q6p.ckpt。

補助的なテキスト／VLM ファイルや、ダウンロードが未完了のファイルは、生成用として推奨されるモデルではありません。たとえば、llama_3.1_8b_instruct_q8p.ckpt.part は不完全で古い補助ファイルであり、2026 年 5 月中旬の最適モデル一式ではありません。

Qwen Layered は現在も任意のワークフロー対象ですが、この構成で最適モデル一式として確実にインストールできるわけではありません：qwen_image_layered_1.0_bf16_q6p.ckpt はチェックサムの不一致で検証に失敗し、qwen_image_layered_1.0_bf16_q8p.ckpt は CLI でのダウンロード中に繰り返し停止しました。ユーザーが Layered の再試行を明示的に求めない限り、ローカルでの安定した編集には qwen_image_edit_2511_q8p.ckpt を使用してください。

正確なインストールコマンド、現行モデルと旧式モデルの区別、量子化のルールについては、references/model-catalog.md を読み込んでください。

---

コアの生成プロトコル

どのモードも次の手順に従います。

1. 検証：CLI が存在すること、入力ファイルが存在すること、モデルがダウンロード済みであること、または --download-missing を意図的に指定していることを確認します。
2. デフォルトを選択：ユーザーが --model を指定していない場合は、役割に応じて最新のモデルを選びます。
3. コマンドを作成：draw-things-cli generate --help に表示されるフラグのみを使用するか、高度なアプリ設定には --config-file を使用します。
4. コマンドを表示：実行前に、コマンド全体を表示します。
5. 実行：Bash 経由で実行し、出力を取得します。
6. 報告：出力パス、シード、モデル ID、サイズ、ステップ数、cfg を出力します。

モード：生成

高速なドラフトのデフォルト：

draw-things-cli generate \
  --model z_image_turbo_1.0_q8p.ckpt \
  --prompt "<prompt>" \
  --steps 8 \
  --cfg 0 \
  --width 1024 \
  --height 1024 \
  --seed <seed> \
  --output <output.png>

品質／テキストのデフォルト：

draw-things-cli generate \
  --model qwen_image_2512_q8p.ckpt \
  --prompt "<prompt>" \
  --steps 40 \
  --cfg 4 \
  --width 1328 \
  --height 1328 \
  --seed <seed> \
  --output <output.png>

モード：編集

draw-things-cli generate \
  --model qwen_image_edit_2511_q8p.ckpt \
  --image <input.png> \
  --prompt "<edit instruction>" \
  --strength 0.55 \
  --steps 30 \
  --cfg 4 \
  --seed <seed> \
  --output <output.png>

微細な編集には --strength 0.25-0.4、目に見える編集には 0.5-0.65、大幅な描き直しには 0.75+ を使用します。

モード：メディア

draw-things-cli generate \
  --model ltx_2.3_22b_distilled_q6p.ckpt \
  --prompt "<motion prompt>" \
  --frames 49 \
  --width 768 \
  --height 512 \
  --seed <seed> \
  --output <output.mov>

この環境では、まず LTX distilled を使用します。幅と高さは 32 で割り切れる値、フレーム数は 8 の倍数に 1 を加えた値にしてください。

モード：セットアップ

まずインベントリを実行します。

uv run python skills/draw-thing/scripts/model_inventory.py --recommended-pack all --format json

次に、ユーザーに表示してから、不足している ensure_command の項目を実行します。ユーザーが別途削除処理を承認しない限り、古いモデルを削除しないでください。

モード：インベントリ

uv run python skills/draw-thing/scripts/model_inventory.py --format json

インストール済みモデル、おすすめモデルの不足分、重複している古いダウンロードをまとめます。 ヘルパーファイルや古い .part ファイルを現在の最適なモデルと誤認しないよう、incomplete_downloads と auxiliary_or_dependency_files は分けて報告します。

モード：バッチ

現在の CLI では --batch-count を使用できません。シェルループを使用し、出力名を明示します。

for seed in 1201 1202 1203 1204; do
  draw-things-cli generate \
    --model z_image_turbo_1.0_q8p.ckpt \
    --prompt "<prompt>" \
    --steps 8 \
    --cfg 0 \
    --width 1024 \
    --height 1024 \
    --seed "$seed" \
    --output "$HOME/Pictures/draw-thing/run-$seed.png"
done

モード：高度な設定

現在の generate --help では、--controls、--loras、--mask、--upscaler、--batch-count、--sampler、--guidance-scale などの以前の直接指定フラグは使用できません。ControlNet、LoRA、インペイント、アップスケール、タイリングなど、アプリレベルの設定には次の手順に従います。

1. draw-things-cli generate --help を再確認します。
2. スキーマが検証済みの場合に限り、Draw Things アプリが管理する設定、または --config-json ／ --config-file を使用します。
3. 古い例をもとに直接指定フラグを作り出さないでください。

---

プロンプト早見表

モデルファミリー	スタイル	ネガティブプロンプト
Z Image Turbo/Base	自然言語による直接的な指示。構図の詳細は簡潔にします	必要に応じて使用できます。短くまとめます
Qwen Image 2512	レイアウト、タイポグラフィ、正確なテキスト、エディトリアルな表現を明示します	使用できます。対象を絞ります
Qwen Edit/Layered	命令形の編集指示と、保持する制約を指定します	変更を避ける対象に限って使用します
FLUX.2	自然言語で、参照や編集の詳細、シーンの意図を正確に伝えます	モデルごとに確認します。FLUX.1 のルールを前提にしないでください
HiDream I1 Full	豊かなアートディレクション、スタイル、媒体、ライティング、構図を指定します	使用する場合は、対象を絞った短いネガティブプロンプトにします
LTX/Wan メディア	動きの経時変化、カメラの動き、時間的な連続性を描写します	静止画像だけを対象とするタグの羅列は避けます

テンプレートとトラブルシューティングについては、references/prompt-patterns.md を読み込んでください。

---

スケーリング戦略

リクエストの規模	戦略
単一画像	品質やテキストに Qwen 2512 が必要でない限り、z_image_turbo_1.0_q8p.ckpt を使用します
テキスト／レイアウトが重要	qwen_image_2512_q8p.ckpt を使用し、テキスト／レイアウトを明示したプロンプトを指定します
既存画像を編集	まずは控えめな強度で qwen_image_edit_2511_q8p.ckpt を使用します
レイヤー／編集可能なワークフロー	Qwen Layered がすでにインストールされている場合にのみ使用します。そうでなければ、以前のインストール失敗について説明し、再試行する前に確認を求めます
高品質なアート	hidream_i1_full_q5p.ckpt を試し、メモリ不足の兆候があれば切り替えます
短い動画	まず LTX distilled q6p を使用し、サイズを適度に保ちます
多数のバリエーション	シェルループ、固定の出力パス、控えめなシード数を使用します

---

出力の扱い

• スキルのデフォルト出力ディレクトリ：~/Pictures/draw-thing/。
• 生成前に作成します：mkdir -p "$HOME/Pictures/draw-thing"。
• 常に --output <file> を指定し、暗黙の出力動作に頼らないでください。
• 元画像を上書きせず、内容がわかる新しいファイル名を使用します。
• 出力ファイル、シード、モデル、ステップ数、cfg、サイズ、実行中にモデルをダウンロードしたかどうかを必ず報告します。

---

エラーからの復旧

エラー	考えられる原因	対応
unknown flag	古い手順、または CLI との不一致	draw-things-cli generate --help を実行し、古い直接指定のフラグを削除します
モデルが見つからない	ID が誤っている、またはダウンロードされていない	draw-things-cli models list を実行し、models ensure --model <id> を使用します
出力ファイルがない	--output の指定漏れ、またはターミナルがプレビュー専用モード	明示的なファイルパスを指定して再実行します
強制終了／OOM	モデルが大きすぎる、またはサイズが大きすぎる	サイズを小さくする、q6p／q5p を使用する、またはより高速なモデルに切り替えます
テキストの品質が低い	タイポグラフィに適さないモデル／プロンプト	正確な引用テキストを指定して Qwen Image 2512 を使用します
動画生成に失敗	モデルが見つからない、またはメモリ不足	LTX q6p があることを確認し、サイズ／フレーム数を減らします

---

参考ファイル

一度に読み込む参考ファイルは 1 つにしてください。

ファイル	内容	読み込むタイミング
references/cli-reference.md	現在のコマンド一覧、フラグ、モデル関連サブコマンド、設定に関する注意点	複雑なコマンドを組み立てるとき
references/model-catalog.md	2026-05-15 時点で最適なモデルパック、正確な ensure コマンド、旧バージョンに関する注記	モデルを選択／ダウンロードするとき
references/prompt-patterns.md	Qwen、Z Image、FLUX.2、HiDream、LTX／Wan のプロンプトパターン	複雑なプロンプトや品質の問題があるとき
references/controlnet-guide.md	古いフラグに関する警告を含む、高度な制御／インポート／設定のガイド	ControlNet、LoRA、インペイント、アップスケール
references/workflow-recipes.md	現在のレシピ。公開されているフラグとシェルループを使用	複数ステップのクリエイティブなワークフロー

検証契約

変更を完了とする前に、このスキルのディレクトリから実行してください。

python scripts/check.py
python scripts/model_inventory.py --format json

完了条件：

1. scripts/check.py が 0 で終了すること。
2. モデルの一覧で、推奨パックのステータスが示されていること。
3. コマンド例に、現在の generate --help でサポートされていない古い直接指定フラグが使われていないこと。
4. このスキルのディレクトリ内に、ポータブル CLI の違反が残っていないこと。

---

重要なルール

1. 生成またはモデルの変更を行う前に、必ず command -v draw-things-cli を確認してください。
2. 直接指定フラグの信頼できる情報源として、必ず draw-things-cli generate --help を使用してください。
3. 必ず --output を指定してください。プレビューのみの出力では、エージェントのワークフローには不十分です。
4. 古い --guidance-scale ではなく、--cfg を使用してください。
5. 現在のヘルプまたは設定スキーマでサポートが確認できない限り、古い直接指定フラグである --sampler、--batch-count、--upscaler、--mask、--controls、--loras は使用しないでください。
6. レガシーな SDXL、SD1.5、SD2.x、SVD、FLUX.1、Qwen 1.0、Qwen Edit 2509、Wan 2.1、または古いコミュニティチェックポイントよりも、推奨される 2026 年版リグパックを優先してください。
7. 別途明示的なユーザーの承認を得ずに、モデルを削除または整理しないでください。
8. 実行前に、コマンド全体を表示してください。
9. ソース画像を保持し、新しい出力ファイルを書き込んでください。
10. シード、モデル ID、出力パス、寸法、ステップ数、cfg を報告してください。
11. 動画では、寸法を適度に保ち、フレーム数を 8 の倍数に 1 を加えた数にしてください。
12. 高度な ControlNet／LoRA／インペイント／アップスケールのワークフローでは、実行前に --config-json または --config-file のスキーマを確認してください。
13. 補助的なテキスト／VLM ファイル、サイドカーファイル、不完全な .part ダウンロードを、推奨される生成／メディアモデルとして扱わないでください。