skill-image-qwen スキル

千問Qwen-Image-3.0で画像を生成または編集します。モデルは**テキストから画像生成（T2I）と画像から画像/画像編集（I2I）**の両方をサポートし、テキストプロンプトから直接生成するか、1～3枚の参照画像と編集指示を組み合わせて正確に編集できます。中心的な目標は「綺麗」から「使える」への転換であり、生成された画像がそのまま納品可能な成果物となることを目指します。基本原則：プロンプトを活用してモデルの能力を最大限に引き出すこと。「要求の明確化」「プロンプトの審査・最適化」と「生成前の確認」を最も重要視します。

V3 コアアップグレード：三段式トークンチェーン（コードで担保、唯一100%有効）

V2は二段階（prepare/generate）であり、理論上モデルは最適化審査を経ずにprepareに進むことが可能でした。V3では「プロンプト最適化審査工程」をコードレベルゲートとして追加し、三段式トークンチェーンを形成します：

フェーズ1 optimize：モデルは公式テンプレート（6ステップパラダイム）に従って審査と最適化を完了し、登録を提出します。登録には「最適化前後の比較＋変更説明」を強制（手抜き防止）。コードはトークンAを生成（最適化後プロンプトの内容フィンガープリント sha256 にバインド）、ディスクに記録します。実際のAPIを決して呼び出しません。
フェーズ2 prepare：コードはトークンAをチェック（トークンAなし→拒否、「先に審査最適化工程を完了する必要があります」と表示）。通過後、ユーザーに「元の要求→最適化後プロンプト→変更説明」をそのまま提示し確認を求めます。トークンBを生成し、トークンAを破棄（使い捨て）。実際のAPIを決して呼び出しません。
フェーズ3 generate：コードはトークンBをチェック（トークンBなし/一致しない/内容が改ざん→拒否）。通過後にAPI呼び出しを実行し、成功後にトークンBを破棄（使い捨て）。

トークンリレー：optimize ->(トークンA)-> prepare ->(トークンB)-> generate、チケットが一枚欠けるとゲートは開きません。モデルが元の要求から直接生成に飛びつこうとすると、prepareまたはgenerateで阻止されます。

トークンはプロセスの副産物であり、ハードコードされたパスワードではない：コードによって動的に内容フィンガープリント（sha256(プロンプト)）が生成され、モデルがソースコードを読んでも偽造できません。該当工程をきちんと完了した者のみが鍵を取得できます。

トークンは内容にバインド：リクエストごとに異なるトークンが生成され、提出内容と登録/確認バージョンが一致しない場合は拒否されます。「見せかけ用と生成用で異なる」を防止します。

トークンの範囲：フィンガープリントはプロンプト内容のみをカバーし、サイズ/フォーマットなどの技術パラメータは登録記録から取得し、フィンガープリントには含めません。ゲートがロックする核心は「ユーザーが内容を確認した」という事実であり、技術パラメータは柔軟に処理し、サイズ変更のたびに全フローをやり直す必要はありません。

使い捨て：prepareはトークンAを消費すると即座に破棄、generateは成功後にトークンBを即座に破棄し、古いトークンを使ってステップを飛ばして再実行することを防ぎます。

拒否情報による逆方向教育：エラーメッセージはフローガイドとなり、阻止された後でも自己修正して正しいフローに戻れます。

手抜き防止メカニズム：optimizeの登録には「最適化前後の比較＋変更説明」が強制され、prepareでそのままユーザーに提示されます。手抜きしようとすると、その場で変更理由をでっち上げる必要があり、手抜きのコストが上昇します。ユーザーは確認時に最適化の根拠を確認でき、方向性の逸脱（例：「写実風」が「カートゥーン風」に変更）を発見できます。一つの出力が「手抜き防止課題」と「ユーザー確認根拠」の両方の役割を果たし、追加の工程を増やしません。

モデルとバージョン

バージョン	モデルID	位置づけ	生成単価
標準版（デフォルト）	`qwen-image-3.0`	品質-速度のバランス、日常創作に便利	1K/2K ともに 0.18 元/枚
Pro版（オプション）	`qwen-image-3.0-pro`	密集レイアウト、極限のディテール、豊富な知識	1K 0.25 元/枚、2K 0.50 元/枚

モデルの中核能力（公式の「三実」）：

能力	説明	主要指標
内容豊富	一枚のページ全体を収容：試験用紙、新聞、図鑑、情報図を一度に生成	指示長が4.5Kトークンに向上
ディテール真實	拡大に耐える：テクスチャの質感がリアルな素材に迫る	10pxの小さな文字がはっきり読め、毛穴や髪の毛の細部まで表現
知識豊富	何でも知っている：多言語、多分野	12言語、100以上のアートスタイル、多様なUIインターフェースをカバー

デフォルトは標準版を使用。ユーザーが明示的にPro版の能力（図中の図密集レイアウト、微表情/毛穴/髪の毛のリアルなディテール）を必要とする場合、またはPro版を要求した場合のみ切り替えます。
入力価格は両バージョンとも同じ（0.02 元/枚）。詳細は references/pricing_and_models.md を参照。
モデルの能力境界と選定アドバイスは references/pricing_and_models.md を参照。

ワークフロー（必ず遵守）

①意図識別と要求の明確化 -> ②バージョン選択 -> ③プロンプト作成とoptimize（審査最適化） -> ④エコーバック確認 -> ⑤prepare確認 -> ⑥generate生成と反復 -> ⑦消費報告。

ステップ1：意図識別と要求の明確化（最重要、省略不可）

AI画像生成の専門家として、ユーザーの要求が十分に明確かつ詳細かを判断します。ユーザーの初期要求は通常曖昧であり、このステップが画像品質の鍵です。 ユーザーと何度も確認する必要があります。

意図を解析：ユーザーのテキスト質問 + 添付ファイル（参照画像/スケッチ/スクリーンショット）を基に、以下の点を判断：
- タスクタイプ：ゼロからの創作（T2I）？既存画像の編集（I2I）？
- 特定の実在人物/ブランド/オブジェクトの忠実度要求の有無
- 参照画像の数と各画像の役割（編集対象 / スタイル参照 / 主体のソース）
多次元で詳細化（曖昧な場合は項目ごとに確認。request_user_input で一括質問または自然なフォローアップが可能。詳細な場合は軽い確認でOK）：
1. 主体内容 2. スタイル 3. 構図とアングル 4. 雰囲気と照明 5. サイズ比率 6. 枚数 7. 用途 8. 参照画像 9. 忠実度要求
実在人物が含まれる場合：各人の識別特徴（髪型/髪色/眼鏡/肌色/顔の形/服装/体型/年齢）を質問し記録。プロンプトのアンカーとして使用。
「画像スペック」としてまとめ、ユーザーにエコーバックして確認。

効率の原則：要求が明確な場合は軽い確認のみ（復唱＋「これで合ってますか、調整しますか？」）、機械的に全リストを確認しない。曖昧または高リスクな次元（忠実度、参照画像の役割）でのみ深掘り。

ステップ2：バージョン選択

ステップ1で明確になった要求に基づき、選定アドバイスに従ってバージョンを選択（詳細は references/pricing_and_models.md を参照）：

シナリオ	推奨バージョン
日常的なポスター、イラスト、SNS画像、UIプロトタイプ、バッチ生成	標準版（デフォルト）
高解像度2K出力だが極端なディテール不要	標準版（2Kも同価格でお得）
EC商品画像の家場景への合成（I2I複数画像）	標準版で十分。極限の質感を求める場合はPro版
新聞レイアウト、試験用紙、絵コンテ、メニュー、情報図表（密集レイアウト）	Pro版
人物写真、商品クローズアップ（微表情/毛穴/髪の毛のリアルなディテール）	Pro版
知識図鑑、歴史教育用情報図（マルチモジュール＋多言語）	Pro版

デフォルトは標準版。Pro版が必要な場合は、コスト差（2KでPro版は178%割高）を明確にユーザーに伝えること。
ユーザーがバージョンを指定しない場合、デフォルトの標準版を使用し、生成プランでその旨を説明すること。

ステップ3：プロンプト作成とoptimizeの呼び出し（審査最適化登録、APIは決して呼び出さない）

ステップ1の意図とスペックに基づき、ベストプラクティスとケースライブラリを参考にプロンプトを審査最適化し、モードを選択した上で、optimize を呼び出します（直接生成はしません）。optimizeはモデルの能力を最大限に引き出す中核工程です。元の要求は通常簡潔で曖昧なため、公式の6ステップパラダイムに従って描写力のあるプロンプトに拡張し、「最適化前後の比較＋変更説明」を登録します。

3.1 ベストプラクティスとケースライブラリの参照

まず references/best_practices.md と references/case_library.md を確認し、同じようなシナリオの公式ケースがないかを探し、そのプロンプト構造パターンと重要なテクニックを学び、陥りやすい落とし穴を特定して事前に回避します。

シナリオからケースへのクイックリファレンス：

ユーザーシナリオ	参照ケース	プロンプトの重点
試験用紙/ドキュメント/レポートのレイアウト	ケース1（国語試験用紙）	エリアごとのスキャン的記述＋文字の一字一句書き込み
マクロ撮影/商品クローズアップ	ケース2（刺繍マクロ）	素材繊維＋操作瞬間＋浅い被写界深度
手書きノート/数式	ケース3（数学ノート）	3色注釈＋数式の一字一句＋幾何図形
EC商品画像の場景合成	ケース4（商品画像合成I2I）	編集ルール（抽出/無視/保持/生成）
キャラクター設定/マルチアングル一貫性	ケース5（キャラクター設定シート）	単一人物の極めて詳細な描写＋マルチアングル分割
手描き地図/情報図	ケース6（グルメマップ）	エリアごとの描写＋番号ポイント＋凡例システム
メニュー/価格表	ケース7（潮州料理メニュー）	セクション分割＋料理リスト＋写真埋め込み
知識図鑑/科学普及ポスター	ケース8（襦裙図鑑）	モジュール化描写＋メインビジュアル人物＋補助モジュール
ベクター運動/ガイド情報図	ケース9（ハイキングガイドマップ）	英語ベクタースタイル＋配色システム＋ルート経由地
歴史教育/多言語情報図	ケース10（安史の乱）	バイリンガルモード＋ワイド横長＋ネガティブ制約
商業人物写真	ケース11（イタリアンストリートポートレート）	多層的背景ストーリー＋人物の極めて詳細＋フィルム調
照明人物写真	ケース12（麦わら帽子の照明ポートレート）	照明の原因と落ち方＋撮影パラメータ＋ネガティブ制約

完全な12公式ケースのプロンプト構造解析と重要なテクニックは references/case_library.md を参照。完全な原文プロンプトは Qwen-Image-3.0公式ベストプラクティスケースと完全プロンプトマニュアル.md を参照。

3.2 方式の選択（目標に応じて）

目標	方式	呼び出し
ゼロからの創作、参照画像なし	テキストから画像T2I	プロンプトのみ、`--image` は指定しない
既存画像の人物や内容を保持/拡張	画像から画像I2I	プロンプト + 1〜3 `--image`

3.3 プロンプトの記述（公式6ステップパラダイム）

公式が12のケースから導き出したプロンプト構造の骨格に従って内容を整理します（詳細は references/best_practices.md 第3章を参照）：

冒頭のトーン設定：一文で画面のタイプ、フレームの向き、全体的なスタイルと雰囲気を説明。例：「これは縦型の……ポスターで、全体的な背景は……です」
空間の動線：空間的な順序（上から下、左から右、主体から背景へ）に厳密に従ってエリアごとに記述し、各要素の相対的な位置関係を明記。
文字の一字一句書き込み：レンダリングが必要なすべての文字（タイトル/本文/ラベル/価格/フッター）を引用符で一字一句プロンプトに記述し、フォント/サイズ/色/位置を指定。
ディテール五要素：色には具体的な色名、素材には質感を示す言葉、照明には方向と硬さ、フォントにはスタイル、構図には階層感を与える。
締めくくりの制約：「避けること」でネガティブ制約（文字化け/位置ずれ/歪み/露出オーバー/透かしなど）を列挙。--negative-prompt パラメータも使用可能。
フレームサイズと撮影パラメータ：写実/人物ポートレート系では、フレーム比率、レンズ焦点距離、絞りなどのパラメータを付記（例：「縦型3:4、85mm、f/2」）。

公式3つの使用テクニック：

指示は「長く」できる：4.5Kトークンを複雑なレイアウトに割り当て、各エリア、各テキスト、各相対位置を詳細に記述。
小さな文字は「指名」する：正確なテキストを直接指示に書き込み、引用符で囲み、フォント/サイズ/色/位置を指定。
スタイルは「完全に」説明する：写真風なら光、レンズ、雰囲気（焦点距離/絞り/露出/フィルムグレイン）を、イラスト風なら素材、配色、筆致を記述。

編集/参照系（I2I）の特別なポイント：「Xを保持し、Yのみ変更」と明記し、反復時には不変条件を再確認してドリフトを防止。複数画像合成の重点は編集ルール（何を抽出/無視/保持/生成するか）であり、「必須」「禁止」などの強い制約語を使用して参照画像の完全な利用を確保。

3.4 optimizeの呼び出し（比較＋変更説明を登録、トークンAを返し、APIは決して呼び出さない）

プロンプトの審査最適化が完了したら、optimize フェーズを呼び出します（直接生成はしません）。optimize は手抜き防止（元/最適化/変更説明が揃い、変更説明に実質的な内容があること）を検証し、パラメータを検証し、最適化後プロンプトのフィンガープリントを計算し、審査記録をディスクに保存し、トークンAを返します。実際のAPIを決して呼び出さず、費用も発生しません：

optimize テキストから画像：python scripts/generate_image.py optimize --original-prompt "元の要求" --optimized-prompt "最適化後プロンプト" --change-explanation "変更説明" --size 1024*1024
optimize 画像から画像：python scripts/generate_image.py optimize --original-prompt "元の要求" --optimized-prompt "最適化後プロンプト" --change-explanation "変更説明" --image ref.png --model qwen-image-3.0-pro
optimize 複数画像：python scripts/generate_image.py optimize --original-prompt "..." --optimized-prompt "..." --change-explanation "..." --n 4

optimize 必須パラメータ：--original-prompt（元の要求）、--optimized-prompt（最適化後プロンプト）、--change-explanation（変更説明：何を最適化したか、なぜか—手抜き防止の課題であり、ユーザー確認の根拠でもある）。よく使うパラメータ：--model（デフォルト qwen-image-3.0）、--image（1-3枚の参照画像）、--size 幅*高さ、--n（1-6）、--negative-prompt、--seed、--watermark、--no-prompt-extend、--prompt-extend-mode direct|agent、-o 出力パス。すべてのパラメータはoptimize時に記録にロックされ、後続のフェーズで改ざん不可（generateの -o のみ出力パスを上書き可能）。

プロンプト系パラメータは @ファイル 構文をサポート：値が @ で始まる場合、その後のパスからファイル内容を読み込みます（超長プロンプトに対応し、コマンドライン長制限を回避）。例：--optimized-prompt @optimized.txt。

optimize の出力：元の要求、最適化後プロンプト、変更説明、生成プラン（モード/モデル/サイズ/枚数/リライトモード/推定費用）、審査トークン（トークンA）。これらをすべてステップ4に持ち込みます。

ステップ4：エコーバック確認（ユーザー確認を強制待機）

optimize から返された**「元の要求 → 最適化後プロンプト → 変更説明」＋生成プラン＋トークンA**をすべてユーザーに表示し、ユーザーの明確な確認を待ちます：

ユーザー確認 → ステップ5に進み、トークンAで prepare を呼び出します。
ユーザーが変更を要求 → ステップ3に戻り、審査最適化をやり直して再度 optimize を実行（新しいトークンAが生成され、古いトークンAは自然に無効/期限切れでクリア）、再度エコーバック確認。
⚠️ ユーザーが確認する前に prepare/generate を呼び出してはいけません。コードのバックストップは「ユーザーが実際に見たかどうか」を検証しませんが、prepareは有効なoptimizeトークンAに依存する必要があります。規範的なエコーバック確認は品質とコストの重要なゲートです。ユーザーは確認時に変更説明と照らし合わせて、最適化の方向性が逸脱していないか（例：「写実風」が「カートゥーン風」に変更）を確認できます。

ステップ5：prepare確認（トークンAを消費、トークンBを返す、APIは呼び出さない）

ユーザー確認後、トークンA＋optimizeで登録されたものと完全に同一の最適化後プロンプトで prepare を呼び出します：

prepare：python scripts/generate_image.py prepare --token <トークンA> --optimized-prompt "<optimizeで登録された最適化後プロンプト>"

スクリプトは3つのチェック（審査記録の存在 / トークンAの一致 / 最適化後プロンプトと登録バージョンの一致）を通過した後、「元の要求 → 最適化後プロンプト（確認バージョン） → 変更説明」＋生成プランをそのまま表示し、確認トークン（トークンB）を返し、トークンAを破棄（使い捨て）。
技術パラメータ（画像/サイズ/枚数など）はoptimize記録から取得してロックされ、prepareフェーズで改ざん不可。
トークンAがない、または内容が一致しない → 拒否（エラーメッセージはフローガイド）。

ステップ6：generate生成と単一ポイント反復

トークンB＋prepareで確認されたバージョンと完全に同一のプロンプトで generate を呼び出します：

generate：python scripts/generate_image.py generate --token <トークンB> --prompt "<確認版プロンプト>" [-o 出力パス]

スクリプトは3つのチェック（確認記録の存在 / トークンBの一致 / プロンプトと確認バージョンの一致）を通過した後にのみAPIを呼び出します。その他のパラメータは記録から取得してロックされ、generateフェーズで改ざん不可。
成功後、自動的に実際のサイズ、使用量、費用を出力し、トークンBを破棄（一回限り、再利用不可）。
画像は絶対パスで表示。
反復：一度に一箇所だけ変更 → 再度 optimize（新しいトークンA）→ エコーバック確認 → prepare（新しいトークンB）→ generate。効果が不十分な場合は、まず「スタイル/雰囲気」や「構図」を調整するか、ステップ3に戻って戦略を変更。

ステップ7：消費状況の報告

生成後、スクリプトは自動的に今回の使用量と費用（バージョン、入力/出力の段階、画像枚数、単価、合計）を出力します。返信でユーザーに以下の情報をまとめて報告します：

使用したバージョンと方式（T2I/I2I）、モデルID。
出力サイズ、生成枚数、課金段階（1K/2K）。
入力費用、出力費用、合計費用（元）。
リクエストID（トレーサビリティ用）。

費用計算ルールと例は references/pricing_and_models.md を参照。

トークンと記録メカニズム（三段式チェーン、コードバックストップの詳細）

トークンフォーマット：sha256(プロンプト)-nonce8（フィンガープリントはプロンプト内容にバインド。nonceにより同じプロンプトで複数回登録しても互いに上書きされない）。トークンAとトークンBは同じ内容で同じフィンガープリントを持つが、nonceが異なり、別のトークン。
トークンリレー：optimizeがトークンAを生成 → prepareがトークンAを消費しトークンBを生成（Aを破棄） → generateがトークンBを消費（成功後Bを破棄）。一環欠けると拒否。
記録ストレージ：システム一時ディレクトリ下の2つのディレクトリ—skill_image_qwen_optimize/<tokenA>.json（トークンA、original_prompt/optimized_prompt/change_explanation/paramsを含む）、skill_image_qwen_pending/<tokenB>.json（トークンB、確認バージョンと取得パラメータを含む）。optimize は画像パス/URLのみを保存し、画像内容は読み込まないため、記録は軽量。
トークンの範囲：フィンガープリントはプロンプト内容のみをカバー（sha256(プロンプト)）。サイズ/フォーマットなどの技術パラメータは記録から取得し、フィンガープリントには含めない—サイズ変更のたびに全フローをやり直す必要なし（サイズ/透かし自体がユーザー確認が必要なコンプライアンス要素でない限り）。
手抜き防止：optimize登録には「最適化前後の比較＋変更説明」が強制され、変更説明は最低文字数に達する必要がある。prepareでそのままユーザーに提示。
ライフサイクル：prepare成功後、即座にトークンAを破棄。generate成功後、即座にトークンBを破棄（一回限り、再利用防止）。API呼び出し失敗時はトークンBを保持し、同じトークンでのリトライを許可（再確認不要）。記録は2時間を超えると自動的に無効化・クリア。
パラメータロック：画像/サイズ/枚数/リライトモードなどは optimize 時に記録にロックされ、後続フェーズでは記録から取得して使用され、改ざん不可。generate では -o でのみ出力パスを上書き可能。
画像ファイルはgenerate時に存在している必要がある：optimize は存在確認とパス記録のみを行い、generate 時にディスクから読み込んでdata URIに変換。

プロンプト作成規範

6ステップパラダイム：冒頭のトーン設定 → 空間動線 → 文字の一字一句書き込み → ディテール五要素 → 締めくくりの制約 → フレームサイズと撮影パラメータ（詳細は references/best_practices.md を参照）。
Qwenの特性：詳細で描写力のある長い説明を好む（上限4.5Kトークン）。prompt_extend はデフォルトで有効で、短いプロンプトを強化。
図中の文字：引用符で内容を囲み、フォント/サイズ/色/位置を指定し、一字一句レンダリングを要求。
編集/参照：「Xを保持し、Yのみ変更」と明記し、反復時には不変条件を再確認してドリフトを防止。
サイズ：幅*高さ（アスタリスク区切り、例：1920*1080）。指定しない場合、モデルが自動推奨。
完全なベストプラクティスとFAQは references/best_practices.md を参照。12公式ケースの構造解析は references/case_library.md を参照。APIパラメータは references/api_reference.md を参照。

参照ファイルインデックス

ファイル	内容
`references/best_practices.md`	三実能力概要、3つの公式テクニック、6ステッププロンプトパラダイム、FAQ、サイズ段階、反復アドバイス
`references/case_library.md`	12公式ケースの分類インデックス、プロンプト構造解析、重要なテクニック、シナリオからモードへのクイックリファレンス
`references/api_reference.md`	APIエンドポイント、リクエストボディ構造、パラメータ説明、レスポンスボディ、usageフィールド、エラーコード
`references/pricing_and_models.md`	モデル比較、価格表、費用計算、選定アドバイス
`Qwen-Image-3.0公式ベストプラクティスケースと完全プロンプトマニュアル.md`	公式原文：12ケースの完全プロンプト、使用テクニック、API価格
`scripts/generate_image.py`	三フェーズ生成スクリプト（optimize/prepare/generate、T2I/I2I、純粋標準ライブラリ、三段式トークンチェーンによる強制審査最適化＋確認、手抜き防止、自動課金）

重要な制約

キーセキュリティ：環境変数 DASHSCOPE_API_KEY からのみ読み取り、絶対にスキルファイルに書き込まず、チャットでユーザーに平文キーを要求しない。未設定の場合は、設定手順を示して待機。
三フェーズは回避不可：optimize トークンAがないと prepare が拒否される。prepare トークンBがないと generate が拒否される。optimize/prepare はAPIを呼び出さず、費用も発生しない。モデルは元の要求から直接生成に飛びつけない。
手抜き防止強制：optimize は「最適化前後の比較＋変更説明」を登録する必要があり、変更説明には実質的な内容が必要。prepare でそのままユーザーに提示。
エコーバック確認強制：optimize 後は必ず「元の要求 → 最適化後プロンプト → 変更説明」＋プランをユーザーに表示して確認を求め、確認前に prepare/generate を実行してはいけない。
明確化してから生成：ステップ1（意図識別と要求の明確化）を完了する前にスクリプトを呼び出してはいけない。
出力場所：デフォルトでは現在の作業ディレクトリの output/ に保存。画像が現在のプロジェクトで使用される場合は、生成後にプロジェクトの適切な場所に移動。
上書き禁止：ユーザーが明示的に置き換えを要求しない限り、バージョン番号付きのファイル名を使用。
画像の有効期限：APIが返す画像URLの有効期限は24時間。スクリプトは自動的にローカルにダウンロード。

環境準備

環境変数 DASHSCOPE_API_KEY（阿里雲百煉 APIキー）を必ず設定すること。
PowerShellでの一時設定（プロンプトに従って入力、キーはコマンド履歴に残らない）： $env:DASHSCOPE_API_KEY = Read-Host -Prompt 'DASHSCOPE_API_KEY'
永続設定：システム環境変数画面から DASHSCOPE_API_KEY を書き込むか、setx を使用してからターミナルを再起動。実際の値をリポジトリファイルに書き込まないこと。
オプション DASHSCOPE_BASE_URL：デフォルトエンドポイント https://dashscope.aliyuncs.com を上書き（例：ビジネススペース専用ドメインを使用する場合）。
APIキー取得：https://help.aliyun.com/zh/model-studio/get-api-key

skill-image-qwen

skill-image-qwen とは？

お気に入りのAIに質問する

ドキュメント