picture-it

picture-it

AI エージェント向けの Photoshop。コマンドラインから画像操作を組み合わせられます。

ソース：https://github.com/geongeorge/picture-it | npm：https://www.npmjs.com/package/picture-it

前提条件

picture-it をインストールして設定する必要があります。Node.js 18+ が必要です。

# Install (pick one)
npm install -g picture-it
pnpm add -g picture-it
bun install -g picture-it

# Setup
picture-it download-fonts

認証情報

AI 操作（generate、edit、remove-bg、upscale）には FAL API キーが必要です。環境変数または CLI で設定してください。

# Option 1: Environment variable (preferred — use platform-managed secrets)
export FAL_KEY=your-key-here

# Option 2: CLI config (stored in ~/.picture-it/config.json with 0600 permissions)
picture-it auth --fal <fal-api-key>

API キーをチャットに貼り付けないでください。必ず環境変数または CLI の auth コマンドを使用してください。FAL キーは https://fal.ai から取得できます。

注：generate、edit、remove-bg、upscale コマンドを使用する場合、ユーザーの画像は AI 処理のために fal.ai にアップロードされます。ローカルのみで動作するコマンド（crop、grade、grain、vignette、text、compose、template、info）では、データは送信されません。

基本的な考え方

すべてのコマンドは画像を入力として受け取り、画像を出力します。コマンドをつなげて、あらゆるものを作成できます。picture-it を呼び出すエージェント自体がプランナーです。ツール内に AI プランナーはありません。

生成を始める前に — まず考えましょう

画像生成には実際に費用がかかります（FAL の呼び出し1回あたり $0.03～$0.15）。4パスのワークフローでは $0.10 以上かかります。曖昧なアイデアに予算を費やさないでください。コマンドを実行する前に、時間をかけて計画しましょう。

ステップ1：目的を理解する

picture-it を使う前に、ユーザーが何を求めているのかを十分に把握してください。次の点を自問しましょう。

• この画像の用途は何ですか？（ブログのヘッダー、Instagram 広告、YouTube サムネイル、製品比較、ポスター）
• 対象となるのは誰ですか？（開発者、消費者、エンタープライズの購入者）
• 見た人にどんな気持ちになってほしいですか？（高揚感、信頼感、緊急性、好奇心）
• 伝えるメッセージは何ですか？ 優れた画像は、必ず一つのことだけを伝えます。
• どこに表示されますか？ これによって、サイズ、文字の大きさ、構図のルールが決まります。

これらの点が不明確な場合は、先にユーザーへ確認してください。30秒の質問で、無駄な生成に費やす $0.15 を節約できます。

ステップ2：構図を計画する

少なくとも3つの異なるアプローチを検討してから、1つを選びましょう。次の点を考慮してください。

• FAL を使わずに実現できますか？ テンプレートと Satori による合成は無料です。しっかりしたグラデーションと優れたタイポグラフィだけで十分なこともよくあります。
• FAL の呼び出しを最小限にするには？ 呼び出すたびに費用がかかります。目的を達成できる最少のパスを計画しましょう。
• どの手法が適していますか？ サムネイルには被写体の背後に文字を配置、製品写真には remove-bg + compose、映画のようなシーンには複数パスを使います。

上位2～3案をそれぞれ1文で簡潔にユーザーへ提示し、生成前に選んでもらいましょう。例：

「いくつかの方向性があります。

1. ドラマチックな製品写真 — 暗いステージを生成し、編集でロゴを光る3Dオブジェクトとして配置します（$0.07）
2. すっきりした比較画像 — 両方の製品から remove-bg で背景を削除し、グラデーション上に文字とともに合成します（$0.01）
3. 被写体の背後に文字を配置 — アクションシーンを生成し、編集でタイトルを被写体の背後に織り込みます（$0.07）

どの方向性にしますか？または、組み合わせますか？」

ステップ3：パイプラインを計画する

最初のコマンドを実行する前に、パイプライン全体を書き出してください。

1. generate (flux-dev $0.03) — dark stage scene
2. edit (seedream $0.04) — place logo into scene
3. compose (free) — add text overlay
4. grade + vignette (free) — post-process
Total: ~$0.07

こうすることで、途中で別のアプローチが必要だと気づき、それまでの呼び出しを無駄にする事態を避けられます。

コマンド早見表

コマンド	内容	FAL が必要？
generate	テキストプロンプトから画像を作成	はい
edit	AI で画像を編集	はい
remove-bg	背景を削除	はい
replace-bg	背景を削除して新しい背景を生成	はい
crop	正確な寸法にリサイズ／トリミング	いいえ
grade	カラーグレーディングを適用	いいえ
grain	フィルムグレインを追加	いいえ
vignette	端を暗くする効果を追加	いいえ
text	画像上にテキストを描画（Satori）	いいえ
compose	JSON から画像／テキスト／図形を重ねる	いいえ
template	組み込みテンプレート（AI 不使用）	いいえ
info	画像の寸法と色を分析	いいえ

モデルの選択

用途に合ったモデルを選び、必要以上に費用をかけないようにしましょう。

生成専用モデル：

モデル	費用	最適な用途
flux-schnell	$0.003	デフォルト。素早いラフ、背景、ベースとなるシーン
imagineart	$0.03	高精細なリアリズム、正確なテキスト描画
flux-dev	$0.03	緻密なシーン、ポートレート、映画のような品質
recraft-v3	$0.04	画像内のテキスト、ベクターアート、ブランドスタイルのグラフィック
fibo	$0.04	エンタープライズ用途、構造化・制御された生成
recraft-v4	$0.25	プレミアム。構図、照明、素材の表現が最良です。使用は控えめにしましょう

編集専用モデル：

モデル	費用	最適な用途
reve-fast	$0.02	最安。素早い反復、仕上がりより速度を重視
kontext-lora	$0.035	LoRA スタイルを使った編集、ブランドイメージに沿った変更
kontext	$0.04	デフォルト。対象を絞った局所編集、シーンの変換、テキストの配置
reve	$0.04	スタイル変換、製品バリエーション、コンテキストを考慮した編集
fibo-edit	$0.04	JSON とマスクによる精密な制御、オブジェクトの追加・削除、スタイル変更

生成と編集の両方に対応（generate または edit とともに --model を使用します）：

モデル	費用	最適な用途
seedream-v4	$0.03	低コストの選択肢。複数画像の合成に適しています
seedream	$0.04	複数画像の合成（入力は最大 10 枚）、シーンへのオブジェクトの配置
banana2	$0.08	画像の保持性能が向上。入力が 10 枚を超える場合、極端なアスペクト比、ウェブ検索
banana-pro	$0.15	プレミアム。リアリズム、タイポグラフィ、最大 5 人のキャラクターの一貫性が最良です

適切なモデルの選び方：

タスク	最適なモデル	費用	理由
素早い背景・ラフの作成	flux-schnell	$0.003	最速かつ最安
高品質なヒーロー画像	flux-dev または imagineart	$0.03	品質と費用のバランスが良好
テキストを多く含む画像の生成	recraft-v3	$0.04	生成画像内のテキスト描画が最良
素早い編集の反復	reve-fast	$0.02	半額で、ラフには十分な品質
画像 1 枚の編集（背景の差し替え、テキストの追加）	kontext	$0.04	対象を絞った編集に最適
複数の画像を 1 つのシーンに合成	seedream	$0.04	入力を最大 10 枚まで処理
スタイル転送・製品バリエーション	reve	$0.04	コンテキストを考慮した変換
マスクを使った精密な編集（オブジェクトの追加・削除）	fibo-edit	$0.04	JSON とマスクによる制御
被写体の忠実さを最優先	banana2	$0.08	画像の保持性能が最良
プレミアム品質、複雑なシーン	banana-pro	$0.15	総合的に最良ですが高価です

背景の削除：

• bria（デフォルト）— エッジの品質に優れ、切り抜きがきれいです
• birefnet — 汎用用途に適しています
• pixelcut — 代替手段
• rembg — 最安

良いプロンプトの書き方

これが、平凡な出力とプロ品質の出力の違いを生みます。コピーして調整できる、テスト済みプロンプトの完全なライブラリについては、references/prompt-library.md をご覧ください。重要なルールは次のとおりです。

生成の場合： 照明（「右上からのドラマチックなサイドライト」）、カメラ（「Canon R5 70-200mm f2.8 で撮影」）、雰囲気（「光の筋の中に見えるほこりの粒子」）を具体的に指定します。曖昧なプロンプトでは、ありきたりな結果になります。

被写体の背後にテキストを配置する場合： キーフレーズは次のとおりです。「[subject] の体が文字に重なり、一部を覆うように、『[TEXT]』を大きな太字の [color] の文字で [subject] の後ろに追加してください。」「後ろに」と、遮蔽の指示がないと、テキストが手前に浮いてしまいます。

編集の場合： 必ず 「ほかはすべて完全に同じにしてください」 で締めくくり、維持する要素を列挙します。そうしないと、変更してほしくない部分まで AI が変更します。

背景を置き換える場合： 「日中の、自然で暖かい日差しが差し込む、モダンで高級感のあるモールの入口」のように、現実的で具体的な場所を指定します。「ネオンが反射する夜の街」のような大げさな背景は、明らかに不自然に見えます。

タイポグラフィ

大きなタイトルやヒーローテキストの場合： edit で FAL モデルを使用します。大きなテキストをうまく扱い、シーンに自然に組み込めます。フォントサイズを計算する必要はありません。プロンプトで「非常に大きく太字」と指定するだけです。

小さく正確なテキスト（クレジット、URL、バッジ、カバーライン）の場合：Satori で compose または text を使用します。フォントサイズが重要になるのはこの場合です。画像はスマートフォンではかなり小さく表示されます。目安として、1080px の Instagram 画像では 36px 未満の文字は読み取れません。フォントがインストールされていない場合は、最初に picture-it download-fonts を実行してください。

階層： 画像内のテキストサイズは最大 3 種類にします。ブランド名はタグラインより大きくします。

フォントの組み合わせ： セリフ体とサンセリフ体の組み合わせが最適です。FAL モデルのテキストでは、プロンプトでスタイルを説明するだけです。Satori には 3 種類のフォントがバンドルされています。~/.picture-it/fonts/ に .ttf ファイルを追加してください。フォントがインストールされていない場合は、picture-it download-fonts を実行してください。組み合わせの提案については、references/composition-guide.md を参照してください。

構図テクニック

複数パスの詳細なワークフロー、商品写真、雑誌の表紙、オーバーレイ構成については、references/composition-guide.md をお読みください。

よくあるワークフロー

シンプル：画像を生成する

picture-it generate --prompt "dark cosmic background with nebula" --size 1200x630 -o bg.png

シンプル：画像にテキストを追加する

picture-it text -i bg.png --title "Hello World" --font "Space Grotesk" --color white --font-size 64 -o hero.png

中級：AI 背景とテキストを使ったブログヘッダー

picture-it generate --prompt "abstract dark tech background" --size 1200x630 -o bg.png
picture-it text -i bg.png --title "My Blog Post" --font "DM Serif Display" --font-size 72 -o header.png
picture-it grade -i header.png --name cinematic -o header-graded.png

中級：写真の背景を編集する

picture-it edit -i photo.jpg --prompt "replace background with modern hotel entrance, keep subject identical" --model banana-pro -o edited.jpg

上級：被写体の後ろにテキストを配置する（YouTube サムネイル風）

# 1. Generate a scene
picture-it generate --prompt "runner on mountain trail at golden hour" --model flux-dev --size 1280x720 -o runner.png

# 2. Use FAL edit to add text BEHIND the subject
picture-it edit -i runner.png --prompt "Add 'RUN FASTER' in large bold black letters BEHIND the runner — the runner's body overlaps the text" --model seedream -o thumbnail.png

上級：実際の写真を使った商品比較

# 1. Remove backgrounds from product photos
picture-it remove-bg -i product-a.png --model bria -o a-cutout.png
picture-it remove-bg -i product-b.png --model bria -o b-cutout.png

# 2. Generate a background
picture-it generate --prompt "split gradient, blue left to orange right" --size 1200x630 -o bg.png

# 3. Compose cutouts onto background with text
picture-it compose -i bg.png --overlays overlays.json -o comparison.png

上級：複数パスのシネマティックな構図

# 1. Generate base scene
picture-it generate --prompt "dark stage with green spotlight" --model flux-dev --size 2048x1080 -o stage.png

# 2. Edit scene to place objects
picture-it edit -i stage.png -i logo.png --prompt "Place Figure 2 as glowing 3D cube in the spotlight" --model seedream -o composed.png

# 3. Post-process
picture-it crop -i composed.png --size 1200x630 --position attention -o cropped.png
picture-it grade -i cropped.png --name cinematic -o graded.png
picture-it vignette -i graded.png --opacity 0.3 -o final.png

プラットフォームプリセット

generate または crop で --platform <name> を使用します。

プリセット	サイズ
blog-featured	1200x630
og-image	1200x630
youtube-thumbnail	1280x720
instagram-square	1080x1080
instagram-story	1080x1920
twitter-header	1500x500

出力の動作

• stdout：出力ファイルのパスのみ
• stderr：進行状況のログ
• 成功時は Exit 0、失敗時は Exit 1

stdout を読み取ってファイルパスを取得してください。これがコマンドを連結する方法です。

注意点

• remove-bg では常に --model bria を使用してください。デフォルトの birefnet では長方形のアーティファクトが残り、合成時に見苦しい光彩や影のハローが生じます。
• compose モードの glow エフェクトは、図形ではなく長方形のバッファ全体をぼかします。切り抜き画像には glow を使わず、代わりに背景色やライティングで光彩を表現してください。
• shadow エフェクトにも同様の長方形アーティファクトの問題があります。すっきりした背景に切り抜き画像を配置する場合は、影を完全に省いてください。
• FAL で編集すると、モデルが商品細部（ロゴ、テキスト、デザイン要素）を変更する場合があります。正確さが重要な商品画像では、元画像をそのまま保持するため、edit ではなく remove-bg と compose を使用してください。
• SeedDream の生成には約 60 秒かかります。時間がかかっても失敗したと判断しないでください。
• banana-pro で edit を使う場合、resolution や limit_generations のパラメーターは渡さないでください。自動検出されます。
• FAL で生成した後は、必ず正確な寸法に crop してください。FAL モデルの出力サイズは概算です。
• 画質が重要な場合（ヒーロー画像、ポートレート）は、flux-schnell（$0.003）ではなく flux-dev（$0.03）を使用してください。画質の差は顕著です。
• Satori は display:grid、transforms、animations、box-shadow、filters をサポートしていません。flexbox のみを使用してください。
• edit で被写体の後ろにテキストを配置する場合は、プロンプトで明確に指定してください。「テキストは被写体の後ろにあり、被写体の体が文字に重なって一部を覆う」とします。