qianwen-image-generation

Qwen Image Generation

Wan および Qwen Image モデルを使用して画像を生成・編集します。テキストからの画像生成、参照画像の編集（スタイル変換、被写体の一貫性の維持、複数画像の合成、テキストの描画）、テキストと画像を交互に出力する機能をサポートしています。 このスキルは QianWen-AI/qianwen-ai の一部です。

スキルディレクトリ

このスキルの内部ファイルを使用して、実行方法を確認してください。デフォルトのパスで問題が発生した場合、または詳細が必要な場合は、参照ファイルを必要に応じて読み込んでください。

場所	用途
scripts/image.py	デフォルトの実行方法 — 同期／非同期、アップロード、ダウンロード
references/execution-guide.md	フォールバック：curl（同期／非同期）、コード生成
references/prompt-guide.md	プロンプトの書式、スタイルキーワード、negative_prompt、prompt_extend の判断
references/api-guide.md	API の補足
references/sources.md	公式ドキュメントの URL

セキュリティ

API キーや認証情報を平文で出力しないでください。 常に変数参照を使用してください（シェルでは $DASHSCOPE_API_KEY、Python では os.environ["DASHSCOPE_API_KEY"]）。認証情報の確認や検出は、必ず平文を使わずに行ってください。値を示すのではなく、ステータス（例：「設定済み」／「未設定」、「有効」／「無効」）のみを報告してください。秘密情報が含まれる可能性のある .env ファイルや設定ファイルの内容を表示しないでください。

API キーが設定されていない場合、ユーザーにキーを直接尋ねないでください。 代わりに、プレースホルダー（DASHSCOPE_API_KEY=sk-your-key-here）を含む .env ファイルの作成を支援し、QianWen Console から取得した実際のキーに置き換えるよう案内してください。実際のキー値を書き込むのは、ユーザーが明示的に要求した場合に限ります。

キーの互換性

PAYG（sk-ws-...、旧形式の sk-...）と Token Plan（sk-sp-...）のキーをどちらもサポートしています。キーの種類は、キーを公開せずに判定してください。

python3 -c "
import sys; sys.path.insert(0, 'scripts')
from qianwen_lib import detect_api_key_type
print(detect_api_key_type('scripts/qianwen_lib.py'))
"

出力	意味
token-plan	Token Plan キー — 以下の Token Plan カタログにあるモデルのみ使用してください。
payg	従量課金キー — すべてのモデルカタログを利用できます。
not-set	キーが設定されていません。

Token Plan の場合は、最新の Token Plan モデルカタログを取得して読み込み、一覧に記載された正確なモデル名を使用してください。CDN にアクセスできない場合は、ローカルのフォールバックを使用してください。

Token Plan はローカルファイルのアップロードをサポートしていません。i2i モードでは、ローカルパスではなく、アクセス可能な URL（https:// または oss://）として参照画像を指定してください。

Token Plan で使用できるのは特定のモデルのみです。上記の参照先にあるモデルを正確に使用し、モデルが利用可能かどうかを推測したり、試して確認したりしないでください。PAYG の場合は、以下に進んでください。

モード選択ガイド

1. ユーザーがモデルを指定した場合 → そのまま使用します。
2. モデルの選択が要件、シナリオ、または料金によって異なる場合は、qianwen-model-selector スキルを参照します。

モードを選択する前、またはモデルを選択、推奨、既定として設定する前に、最新のQwen 画像生成モデルカタログを取得して読み込んでください。このカタログには、モードごとのモデルの推奨、モデル一覧、基本情報、互換性に関する注意事項、および既定のモデルが記載されています。CDN へのアクセスに失敗した場合は、ローカルの代替ファイルを使用してください。

⚠️ 重要：上記のモデル一覧は特定時点のスナップショットであり、古くなっている可能性があります。モデルの提供状況は頻繁に変わります。モデルを決定する前に、必ず最新かつ正式なカタログとして公式モデル一覧を確認してください。

モデルの詳細：特定のモデルについて詳しく知るには、ユーザーに https://www.qianwenai.com/models/<model-name> を案内してください。<model-name> は正確なモデル ID に置き換えてください。変更したり、推測したりしないでください。

動的なモデル情報の取得：qianwen-model-selector スキルまたは QianWen CLI（qianwen models info <model>）を利用できる場合は、リアルタイムのモデル情報を取得するために使用してください。CLI の使用には認証が必要です。ログイン方法については、qianwen-usage スキルを参照してください。

実行

⚠️ 複数のファイルを生成する場合：1 回のセッションで複数のファイルを生成するときは、上書きを防ぐため、各ファイル名に数値のサフィックスを付ける必要があります（例：out_1.png、out_2.png）。

前提条件

• API キー：Key Compatibility にある非平文検出機能を使用してください。変数の存在確認で代用しないでください。キーが見つからない場合は、利用可能であれば qianwen-ops-auth を使用するか、.env で DASHSCOPE_API_KEY／QIANWEN_API_KEY を設定するようユーザーに案内してください。スキルは個別にインストールできます。
• Python 3.9 以降（標準ライブラリのみ。pip install は不要です）

環境の確認

初回の実行前に、Python が利用可能であることを確認してください。

python3 --version  # must be 3.9+

python3 が見つからない場合は、python --version または py -3 --version を試してください。Python が利用できない場合、またはバージョンが 3.9 未満の場合は、execution-guide.md の**パス 2（curl）**に進んでください。

既定：スクリプトを実行する

スクリプトのパス：スクリプトは、このスキルのディレクトリ（この SKILL.md があるディレクトリ）内の scripts/ サブディレクトリにあります。**まずこのスキルのインストール先ディレクトリを特定し、その後、スクリプトの実行には必ず絶対パスを使用してください。**スクリプトが現在の作業ディレクトリにあると想定しないでください。実行前にディレクトリを切り替えるために cd を使用しないでください。

実行に関する注意：すべてのスクリプトはフォアグラウンドで実行し、標準出力が得られるまで待ってください。バックグラウンドで実行しないでください。

引数の確認：まず python3 <this-skill-dir>/scripts/image.py --help を実行し、利用可能な引数を確認してください。

# Text-to-image (use the default from the CDN model catalog)
python3 <this-skill-dir>/scripts/image.py \
  --request '{"prompt":"A cozy flower shop with wooden door"}' \
  --output output/qianwen-image-generation/images/out.png \
  --print-response

# Image editing with reference images (wan2.6-image)
python3 <this-skill-dir>/scripts/image.py \
  --model wan2.6-image \
  --request '{"prompt":"Apply watercolor painting style to this photo","reference_images":["https://img.alicdn.com/imgextra/i1/NotRealJustExample/photo.jpg"],"n":1,"size":"1K"}' \
  --output output/qianwen-image-generation/images/out.png \
  --print-response

その他の例（出力のインターリーブ、wan2.5-i2i、qwen-image-2.0-pro、qwen-image-plus）については、execution-guide.mdを参照してください。

引数	説明
--request '{...}'	JSON リクエスト本文
--file path.json	ファイルからリクエストを読み込む
--async	非同期モードを強制する（wan2.5 以前では必須。qwen-image-plus/max およびインターリーブ出力では自動的に有効化されます）
--model ID	モデルを上書きする（現在の既定モデルについては上記のモデルカタログを確認してください）
--output path	画像をパスに保存する（複数画像を出力する場合はディレクトリに保存）。同じディレクトリに複数の画像を書き込む場合、上書きを防ぐため、ファイルには OSS URL の一意の識別子が自動的に付けられます。明示的にファイルパスを指定した場合はそちらが優先されます。上書きを避けるため、呼び出しごとに異なるファイル名を使用してください
--print-response	レスポンス JSON を標準出力に表示する

モデルの優先順位：--model CLI フラグ > --request JSON の "model" フィールド > 組み込みの既定値。

結果の確認

• 終了コードが 0 で、出力に output.results または output.task_id を含む有効な JSON がある → 成功
• 0 以外の終了コード、HTTP エラー、空の応答、またはエラー JSON → 失敗
• 非同期の場合：送信時に output.task_id が返され、ポーリングで task_status: SUCCEEDED に到達する必要があります
• 実行後の確認：出力ファイルが存在し、サイズが 0 でないことを確認します（ls -la <output_path>）
• 必須 — stderr シグナルの確認：結果を確認した後、コマンドの stderr 出力に [ACTION_REQUIRED] または [UPDATE_AVAILABLE] があるかを調べます。どちらかのシグナルが含まれている場合、ユーザーに回答する前に、以下の更新の確認の指示に必ず従ってください。

失敗した場合

スクリプトが失敗した場合は、以下の診断表でエラー出力と照合し、解決方法を確認してください。一致するものがない場合は、別の方法として execution-guide.md を参照してください。curl コマンド（Path 2 — 同期および非同期）、コード生成（Path 3）、自律的な解決（Path 5）について記載されています。

Python がまったく利用できない場合 → execution-guide.md の Path 2（curl）に直接進んでください。

エラーパターン	診断	解決方法
command not found: python3	Python が PATH にありません	python または py -3 を試してください。見つからない場合は Python 3.9 以降をインストールしてください
Python 3.9+ required	スクリプトのバージョンチェックに失敗しました	Python 3.9 以降にアップグレードしてください
型ヒント付近の SyntaxError	Python < 3.9	Python 3.9 以降にアップグレードしてください
QIANWEN_API_KEY/DASHSCOPE_API_KEY not found	API キーがありません	QianWen Console でキーを取得します。.env に追加します：echo 'DASHSCOPE_API_KEY=sk-...' >> .env。または、利用可能な場合は qianwen-ops-auth を実行してください
HTTP 401	キーが無効または一致していません	qianwen-ops-auth を実行します（平文でないことの確認のみ）。キーが有効であることを確認してください
SSL: CERTIFICATE_VERIFY_FAILED	SSL 証明書の問題（プロキシ／企業ネットワーク）	macOS：Install Certificates.command を実行します。それ以外の場合は SSL_CERT_FILE 環境変数を設定してください
URLError / ConnectionError	ネットワークに接続できません	インターネット接続を確認してください。プロキシ経由の場合は HTTPS_PROXY を設定してください
HTTP 429	レート制限に達しました	待機してから、バックオフを適用して再試行してください
HTTP 5xx	サーバーエラー	バックオフを適用して再試行してください
PermissionError	出力を書き込めません	--output を使って、書き込み可能なディレクトリを指定してください

クイックリファレンス

リクエストフィールド（共通）

フィールド	型	説明
prompt	string	生成する画像のテキスト説明（必須）
negative_prompt	string	画像に含めない内容（最大 500 文字）
size	string	解像度。対応する値とデフォルトはモデルによって異なるため、上記のモデルカタログを参照してください
seed	int	再現性のための乱数シード [0, 2147483647]
model	string	モデル ID。現在のデフォルトと対応モデルについては、上記のモデルカタログを確認してください
prompt_extend	bool	プロンプトの書き換えを有効にします（デフォルト：true、画像編集モードのみ）

リクエストフィールド（wan2.7-image-pro / wan2.7-image — マルチファンクション）

フィールド	型	説明
reference_images	string[]	画像 URL またはローカルパス（0～9 件）
reference_image	string	単一の画像 URL／パス（省略形）
size	string	1K、2K（デフォルト）、または 4K（pro のみ、t2i モード）。またはピクセル寸法
enable_sequential	bool	true：連続マルチ画像モード（n=1～12）。false（デフォルト）：単一／バッチモード（n=1～4）
n	int	生成する画像数。連続モード：1～12（デフォルトは 1）。非連続モード：1～4（デフォルトは 1）。画像ごとに課金されます。
thinking_mode	bool	品質向上のための拡張推論を有効にします（デフォルト：true）。t2i（画像なし、非連続）のみ
bbox_list	List[List[List[int]]]	インタラクティブ編集領域。形式：[[[x1,y1,x2,y2],...], ...]。リストの長さは画像数と同じです。編集しない画像には空の [] を指定します
color_palette	array	カスタムカラーテーマ（3～10 色）。各項目：{"hex":"#C2D1E6","ratio":"23.51%"}。比率の合計は 100% です。非連続モードのみ
watermark	bool	「AI Generated」ウォーターマークを追加します（デフォルト：false）

注：thinking_mode を有効にするとレイテンシーは増加しますが、品質が向上します。enable_sequential は一貫性のある画像シーケンス（例：シーンをまたいで同じキャラクター）を生成します。

リクエストフィールド（wan2.6-image — 画像編集）

フィールド	型	説明
reference_images	string[]	編集モードでは画像 URL またはローカルパスを 1～4 件、インターリーブモードでは 0～1 件指定します
reference_image	string	単一の画像 URL／パス（省略形。reference_images が優先されます）
enable_interleave	bool	false（デフォルト）：画像編集モード。true：テキストと画像を交互に出力
n	int	編集モードで生成する画像数（1～4、デフォルト：1）。画像ごとに課金されます。
max_images	int	インターリーブモードでの最大画像数（1～5、デフォルト：5）。画像ごとに課金されます。
watermark	bool	「AI Generated」ウォーターマークを追加します（デフォルト：false）

その他のモデル

最新のモデル一覧とモデル固有の互換性の違いについては、上記にリンクされているモデルカタログを参照してください。

カタログの項目で複数出力が許可されている、解像度固定の非同期テキスト画像生成モデルでは、同梱スクリプトにより現在 n は 1 に制限されています。1 回のリクエストで複数の出力が必要な場合は、api-guide.md の直接 API フローを使用してください。

全パラメータ表：詳細なパラメータについては、api-guide.md を参照してください。

サイズの目安（wan2.6-image）

• 編集モード：1K（デフォルト、約 1280×1280）または 2K（約 2048×2048）
• インターリーブモード：[768×768, 1280×1280] の範囲内の総ピクセル数となるピクセル寸法

一般的なアスペクト比：1280*1280（1:1）、960*1280（3:4）、1280*960（4:3）、720*1280（9:16）、1280*720（16:9）

レスポンスフィールド

フィールド	説明
image_url	生成画像の URL（有効期間は 24 時間）。別のスキルに連携する場合はこちらを使用してください。
image_urls	すべての画像 URL の配列（マルチ画像出力、wan2.6-image、qwen-image-edit）
image_count	生成された画像数
local_path	ダウンロードした画像のローカルファイルパス。ユーザーのプレビューまたは API 以外の操作に使用してください。
local_paths	ローカルファイルパスの配列（マルチ画像出力）
interleaved_content	{type, text/image} オブジェクトの配列（インターリーブモード）
width / height	画像の寸法
seed	使用されたシード

API の詳細

• 同期エンドポイント（wan2.6-t2i、wan2.6-image の編集、qwen-image-edit シリーズ）：POST /api/v1/services/aigc/multimodal-generation/generation
• 非同期エンドポイント（wan2.6 およびそれ以前の t2i）：POST /api/v1/services/aigc/image-generation/generation と X-DashScope-Async: enable
• 非同期エンドポイント（wan2.5-i2i-preview）：POST /api/v1/services/aigc/image2image/image-synthesis と X-DashScope-Async: enable
• 非同期エンドポイント（qwen-image-plus、qwen-image-max）：POST /api/v1/services/aigc/text2image/image-synthesis と X-DashScope-Async: enable
• wan2.6-t2i の解像度：[1280x1280、1440x1440] の範囲の総ピクセル数、アスペクト比 [1:4、4:1]
• wan2.6-image の解像度：編集モード [768x768、2048x2048]、インターリーブモード [768x768、1280x1280]、アスペクト比 [1:4、4:1]
• 入力画像（wan2.6-image）：JPEG/JPG/PNG/BMP/WEBP、各辺 240～8000px、≤10MB
• ローカルファイル：スクリプトが DashScope の一時ストレージ（oss:// URL、TTL は 48h）に自動アップロードします。ローカルパスを直接渡してください。手動でアップロードする必要はありません。
• 本番環境：デフォルトの一時ストレージは TTL が 48h、アップロード上限が 100 QPS のため、本番環境、高同時実行、負荷テストには適していません。独自の OSS バケットを使用するには、.env で QWEN_TMP_OSS_BUCKET と QWEN_TMP_OSS_REGION を設定し、pip install alibabacloud-oss-v2 をインストールして、QWEN_TMP_OSS_AK_ID / QWEN_TMP_OSS_AK_SECRET または標準の OSS_ACCESS_KEY_ID / OSS_ACCESS_KEY_SECRET を使って認証情報を指定してください。最小権限（対象バケットのみの oss:PutObject と oss:GetObject）を付与した RAM ユーザーを使用してください。qianwen-ops-auth がインストールされている場合は、完全な設定ガイドについて references/custom-oss.md を参照してください。
• インターリーブ同期：ストリーミング（X-DashScope-Sse: enable と stream: true）が必要です。代わりに、このスクリプトで非同期モードを使用してください。

スキル間の連携

生成した画像を別のスキル（例：video-gen i2v、vision analyze）の入力として使用する場合：

• image_url を直接渡してください。ダウンロードしてローカルパスとして再度渡してはいけません。
• 以降のすべてのスクリプトは URL のプレフィックス（https://、oss://）を検出し、再アップロードせずにそのまま渡します。
• ユーザーのプレビューや API 以外の操作（例：エディターで開く）に限り、local_path を使用してください。

シナリオ	使用する値
別のスキル（video-gen、vision、image-edit）に渡す	image_url（URL）
ユーザーに表示する／エディターで開く	local_path（ローカルファイル）

エラー処理

HTTP	意味	対応
401	API キーが無効または未設定です	利用可能な場合は qianwen-ops-auth を実行してください。そうでない場合は、キーを設定するようユーザーに求めてください（平文かどうかの確認のみ）
400	不正なリクエスト（プロンプトまたはサイズが無効）	パラメーターと制約を確認してください
400 The product is not activated / Model not subscribed	アカウントでサードパーティモデルが有効になっていません	モデルマーケットにアクセスしてモデルを探し、「Enable」／「开通」をクリックしてください
429	レート制限に達しました	指数バックオフで再試行してください
5xx	サーバーエラー	指数バックオフで再試行してください

使用状況と請求：qianwen-usage スキルを使用すると、使用状況、無料枠の上限、請求を直接確認できます。または、ユーザーは QianWen コンソールにアクセスできます： 使用状況の分析 | 従量課金制の請求 | トークンプランのサブスクリプション

**使用状況／請求／コンソールの URL を捏造、推測、作成してはいけません。**このスキルに記載されている正確なリンクのみを提示してください。ここに記載されていない URL を作成してはいけません。

出力先

現在の作業ディレクトリを優先してください。デフォルトのサブディレクトリ：./output/qianwen-image-generation/。

書き込み禁止：このスキルのインストールディレクトリや skills/ 階層内に出力ファイルを書き込んではいけません。生成したコンテンツはすべて、現在の作業ディレクトリ内の output/、またはユーザーが指定したパスに保存してください。

更新チェック（実行後に必須）

スクリプトの実行後、stderr でアクションを示すシグナルを確認してください。スクリプトは更新状況を自動検出し、構造化されたシグナルを出力します。必ずそれらに対応してください。このセクションは、ユーザーが明示的に更新チェックを依頼した場合にも適用されます。

シグナル：[ACTION_REQUIRED] qianwen-update-check skill is not installed

stderr にこのシグナルが含まれている場合、次の選択肢をユーザーに提示し、続行する前にユーザーの返答を待ってください。黙ってスキップしてはいけません。

更新チェック用スキルがインストールされていません。QianWen-AI/qianwen-ai の新機能やバグ修正について最新情報を確認できます。

1. 今すぐインストール — インストールコマンドを実行します
2. 今回はスキップ — 今回は何もしません
3. 今後は通知しない — このプロンプトを今後表示しないようにします

ユーザーの返答後：

• ユーザーが 1 を選択 → npx skills add QianWen-AI/qianwen-ai --skill qianwen-update-check -y を実行し、その後 python3 <this-skill-scripts-dir>/gossamer.py --dismiss を実行します
• ユーザーが 2 を選択 → python3 <this-skill-scripts-dir>/gossamer.py --dismiss を実行し、その後通常どおり続行します
• ユーザーが 3 を選択 → python3 <this-skill-scripts-dir>/gossamer.py --never-install を実行し、その後通常どおり続行します

シグナル：[UPDATE_AVAILABLE]

stderr にこのシグナルが含まれている場合、stderr に示されたバージョン情報と更新コマンドを含む簡潔な更新通知を回答に追記してください。

stderr にシグナルがない場合

stderr に [ACTION_REQUIRED] も [UPDATE_AVAILABLE] も含まれていない場合、対応は不要です。スキルはインストール済みで最新です（または過去24時間以内にキャッシュされています）。

ユーザーから明示的に依頼された場合

ユーザーが更新チェックを明示的に依頼した場合（例：「更新を確認して」「バージョンを確認して」）：

1. 隣接するスキルディレクトリ内で qianwen-update-check/SKILL.md を探します。
2. 見つかった場合 — python3 <qianwen-update-check-dir>/scripts/check_update.py --print-response を実行し、結果を報告します。
3. 見つからなかった場合 — 上記のインストールオプションを提示します。

参照

• execution-guide.md — フォールバック手順（curl による同期／非同期処理、コード生成、自律実行）
• api-guide.md — API 補足ガイド
• sources.md — 公式ドキュメントの URL