qwencloud-video-generation

Qwen Video Generation

Wan モデルを使用して動画を生成します。すべてのタスクは非同期です。リクエストを送信した後、完了するまでポーリングしてください。 このスキルは qwencloud/qwencloud-ai の一部です。

⚠️ 重要なパラメーターの違い：

• kf2v（最初と最後のフレーム）：長さは5 秒固定です。他の値を指定すると失敗します。出力は音声なしのみです。
• 解像度パラメーターはモードだけでなく、モデルファミリーによって異なります：size、resolution、ratio を選択する前に、最新のモデルカタログを取得してください。

スキルディレクトリ

このスキルの内部ファイルを使用して、実行方法を確認してください。既定のパスで失敗した場合や、詳細が必要な場合は、必要に応じてリファレンスファイルを読み込んでください。

場所	用途
scripts/video.py	既定の実行方法。モードの自動検出、送信、ポーリング、ダウンロードを行います
references/execution-guide.md	フォールバック：5 つすべてのモードに対応した curl とコード生成
references/request-fields.md	モード別のフィールド一覧と音声の扱い
references/workflows.md	長さの延長、マルチショット、VACE パイプライン
references/polling-guide.md	ポーリングのパターンとタイミング
references/merge-media.md	連結、トリミング、音声の重ね合わせ — ffmpeg/moviepy のレシピ
references/prompt-guide.md	モード別のプロンプトの形式、サウンドの説明、マルチショットの構成
references/examples.md	モード別のスクリプト例
references/sources.md	公式ドキュメントの URL

セキュリティ

API キーや認証情報を平文で出力しないでください。 必ず変数参照を使用してください（シェルでは $QWENCLOUD_API_KEY、Python では os.environ["QWENCLOUD_API_KEY"]）。スクリプトは QWENCLOUD_API_KEY、QWEN_API_KEY、DASHSCOPE_API_KEY の順に受け付けます。認証情報の確認や検出は、必ず非平文で行ってください。「設定済み」／「未設定」、「有効」／「無効」のように状態のみを報告し、値は決して報告しないでください。秘密情報が含まれる可能性のある .env や設定ファイルの内容を表示しないでください。

API キーが設定されていない場合、ユーザーに直接キーの提供を求めないでください。 代わりに、プレースホルダー（QWENCLOUD_API_KEY=sk-your-key-here）を記載した .env ファイルの作成を支援し、QwenCloud Console から取得した実際のキーに置き換えるよう案内してください。実際のキー値を書き込んでよいのは、ユーザーが明示的に依頼した場合のみです。

キーの互換性

スクリプトは、標準の QwenCloud API キー（sk-...）と Token Plan キー（sk-sp-...）の両方に対応しています。Token Plan キーは、対応する動画モデルの場合、自動的に Token Plan エンドポイントにルーティングされます。詳しくは、以下のToken Plan のサポートを参照してください。

Token Plan では curl を使用せず、必ず同梱の Python スクリプトを使用してください。

Coding Plan キー（同じく sk-sp- で始まりますが、Coding Plan のサブスクリプションで購入したキー）は使用できません。動画生成モデルは Coding Plan では利用できません。標準キーでは動画生成に秒単位の料金が発生します。スクリプトは起動時にキーの種類を検出し、適切なエンドポイントにルーティングします。qwencloud-ops-auth がインストールされている場合は、詳細について references/codingplan.md を参照してください。

API キーを公開せずに種類を検出します：

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

出力	意味
token-plan	Token Plan キーが検出されました（sk-sp- プレフィックス）
payg	標準の PAYG キーが検出されました
not-set	環境内に API キーが見つかりませんでした

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

モード選択ガイド

ユーザーの要望	モード	主なフィールド
テキストによる説明のみから動画を生成する	t2v	prompt のみ
1 枚の画像をアニメーション化する	i2v	img_url または reference_image
wan2.7 の統合 i2v：最初のフレーム、最初と最後のフレーム、動画の続き、音声同期	i2v	media（配列）、first_frame_url、first_clip_url、driving_audio_url
2 枚の画像間をトランジションさせる（⚠️ 5s 固定、音声なしのみ）	kf2v	first_frame_url + last_frame_url
ロールプレイ：キャラクターに新しい台本を演じさせる	r2v	reference_urls または media。モデル固有の制限については CDN モデルカタログを確認してください
動画編集：複数画像の参照、再描画、部分編集、延長、アウトペイント	vace	function。現在のデフォルトについては CDN モデルカタログを確認してください
メディアプロトコルを使った動画編集	videoedit	--model + media または video_url。対応モデルについては CDN モデルカタログを確認してください
参照動画の人物の動作や表情をキャラクター画像に転写する	animate	--model + image_url + video_url + mode。対応モデルについては CDN モデルカタログを確認してください

モデルの選択

🚫 重大 — ユーザーが指定したパラメーターを決して上書きしないでください。 ユーザーがプロンプトまたはリクエスト JSON でモデルを明示的に指定した場合は、必ずそのモデルをそのまま使用してください。次のことは禁止されています。

• 「より適している」または新しいモデルに置き換えること（例：タスクが「オールインワンの処理に見える」からといって、ユーザー指定の wan2.6-t2v を wan3.0-video に差し替えること）
• 選択したモデルのドキュメントに記載された形式で必要とされる場合を除き、ユーザーの入力フィールドを置き換えたり、再構成したりすること（例：ユーザー指定の img_url／media の構成を変換すること）。変換が必要な場合も、ユーザーのメディアの順序と内容はそのまま維持してください
• ユーザーが要求していないパラメーター（prompt_extend、shot_type、スタイルのヒント）を追加すること。なお、shot_type: "multi" には prompt_extend: true が必須ですが、ユーザーが実際にマルチショットを要求した場合に限ります
• 明示的に指定されたユーザーの選択（duration、size、resolution、prompt）を「最適化」すること

以下の選択ガイドは、ユーザーがモデルを指定していない場合に限り適用されます。

1. ユーザーがモデルを指定している → 必須：そのモデルをそのまま使用してください。代替、最適化、要求されていないパラメーターの追加は禁止です。
2. モデルの選択が機能、シナリオ、または価格によって異なる場合は、qwencloud-model-selector スキルを参照してください。

モデル

モデルを選択、推奨、またはデフォルトとして設定する前に、最新の QwenCloud 動画生成モデルカタログを取得して確認してください。カタログには、モデル一覧、基本情報、モードの推奨事項、互換性に関する注意事項、デフォルトが記載されています。CDN にアクセスできない場合は、ローカルの代替ファイルを使用してください。

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

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

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

実行

⚠️ 複数の成果物：1 回のセッションで複数のファイルを生成する場合、上書きを防ぐため、各ファイル名に必ず数字のサフィックスを付けてください（例：out_1.mp4、out_2.mp4）。

前提条件

• API Key：QWENCLOUD_API_KEY、QWEN_API_KEY、次にDASHSCOPE_API_KEYの順で、非プレーンテキストの方法のみを使って確認します（例：シェルで次のように確認します。 [ -n "$QWENCLOUD_API_KEY" ]。報告するのは「設定済み」または「未設定」のみとし、キーの値は決して表示しないでください）。未設定の場合は、利用可能であれば*qwencloud-ops-auth**スキルを実行します。利用できない場合は、QwenCloud Consoleからキーを取得し、.envファイル（プロジェクトのルートまたは現在のディレクトリでecho 'QWENCLOUD_API_KEY=sk-your-key-here' >> .envを実行）または環境変数で設定するようユーザーに案内します。スクリプトは、現在の作業ディレクトリとプロジェクトのルートにある.envを検索します。スキルは個別にインストールされる場合があるため、qwencloud-ops-authが存在するとは限りません。 注：スクリプトは、エクスポート済み環境変数に加えて、現在のディレクトリとプロジェクトのルートにある.envを自動的に読み込みます。シェルの確認結果で$QWENCLOUD_API_KEYが「未設定」と表示されても、スクリプトが失敗するとは限りません。.envにキーがある可能性があります。シェルでの確認はあくまで参考情報として扱ってください。確実な確認方法は、スクリプトを実行することです。キーがどこにも見つからない場合は、明確なエラーを出して終了します。
• Python 3.9 以降（標準ライブラリのみ、pip install は不要です）
• メディアの結合（連結、トリミング、音声の重ね合わせ）については、ユーザーの環境に適した ffmpeg/moviepy の手順を記載したmerge-media.mdを参照してください。

環境の確認

初回実行の前に、Pythonが利用可能であることを確認します。

python3 --version  # must be 3.9+

python3が利用できない場合、またはバージョンが3.9未満の場合、PAYGでは**パス 2（curl）**を使用できます。Token Planでは、代わりにPython 3.9以降をインストールする必要があります。

デフォルト：スクリプトを実行

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

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

確認：まずpython3 <this-skill-dir>/scripts/video.py --helpを実行し、利用可能な引数を確認します。

python3 <this-skill-dir>/scripts/video.py \
  --model wan2.6-t2v \
  --request '{"prompt":"A detective in a rainy city at night","size":"1280*720","duration":5}' \
  --print-response

# Image-to-animation (no prompt): transfer dance moves from reference video to a character
python3 <this-skill-dir>/scripts/video.py \
  --model wan2.2-animate-move \
  --request '{"image_url":"https://example.com/character.jpg","video_url":"https://example.com/dance.mp4","mode":"wan-std"}' \
  --print-response

引数	説明
--request '{...}'	JSONリクエスト本文
--file path.json	ファイルからリクエストを読み込みます
--mode MODE	自動検出されたモードを上書きします（t2v/i2v/kf2v/r2v/vace/videoedit/animate）
--model ID	モデルを上書きします
--output dir/	動画とレスポンスJSONをディレクトリに保存します。動画にはダウンロードURLのベース名が自動的に付けられるため、実行ごとの上書きを防げます。レスポンスデータの上書きを避けるには、呼び出しごとに異なるファイル名を使用してください
--print-response	レスポンスJSONを標準出力に表示します
--submit-only	送信して終了します（task_idを表示）
--task-id ID	既存のタスクを操作します
--poll-interval N	ポーリング間隔（秒、デフォルト：15）
--timeout N	最大待機時間（秒、デフォルト：600）

結果の確認

• 終了コードが0で、レスポンスにoutput.task_idがある → 送信成功
• ポーリングでtask_status: SUCCEEDEDに到達 → 生成完了
• 終了コードが0以外、HTTPエラー、またはステータスがFAILED → 失敗
• 実行後の確認：出力動画ファイルが存在し、サイズが0ではないことを確認します（ls -la <output_dir>）。
• 必須 — stderrシグナルの確認：結果を確認した後、コマンドのstderr出力を調べ、[ACTION_REQUIRED]または[UPDATE_AVAILABLE]がないか確認します。いずれかのシグナルがある場合、ユーザーに回答する前に、以下の更新の確認の手順に必ず従ってください。

失敗した場合

スクリプトが失敗した場合は、以下の診断表でエラー出力と一致するものを確認し、解決方法を判断してください。一致するものがない場合は、execution-guide.mdを読み、別の方法を確認してください。curl コマンド（Path 2 — 5 つのモードすべて）、コード生成（Path 3）、自律的な解決（Path 5）を利用できます。

Python がまったく利用できない場合 → PAYG では Path 2（curl）を利用できる場合があります。Token Plan では Python 3.9 以降をインストールする必要があります。

エラーパターン	診断	解決方法
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 以降にアップグレードしてください
QWENCLOUD_API_KEY/QWEN_API_KEY/DASHSCOPE_API_KEY not found	API キーがありません	QwenCloud Consoleからキーを取得し、.envに追加してください：echo 'QWENCLOUD_API_KEY=sk-...' >> .env。または、利用可能な場合は qwencloud-ops-auth を実行してください
HTTP 401	キーが無効、または一致していません	qwencloud-ops-auth を実行してください（平文の確認のみ）。キーが有効かどうか確認してください
SSL: CERTIFICATE_VERIFY_FAILED	SSL 証明書の問題です（プロキシ／企業ネットワーク）	macOS：Install Certificates.commandを実行してください。それ以外の場合は、SSL_CERT_FILE環境変数を設定してください
URLError / ConnectionError	ネットワークに接続できません	インターネット接続を確認してください。プロキシ経由の場合はHTTPS_PROXYを設定してください
HTTP 429	レート制限に達しました	待ってから、バックオフを入れて再試行してください
HTTP 5xx	サーバーエラーです	バックオフを入れて再試行してください
ImportError: moviepy	moviepy がインストールされていません	pip install moviepyを実行するか、代わりにシステムの ffmpeg を使用してください（merge-media.mdを参照）
PermissionError	出力を書き込めません	書き込み可能なディレクトリを--outputで指定してください

リクエストフィールドの概要

animate（プロンプト不要）と wan2.7 のvideoedit（プロンプトは任意）を除き、すべてのモードでpromptが必要です。各モードのすべてのフィールドテーブルについてはrequest-fields.mdを参照してください。

⚠️ モデルファミリー別の解像度パラメーター（重要）

解像度フィールドはモデルファミリーによって異なります。size、resolution、ratioのいずれを使用するか選ぶ前に、上記のモデルカタログを確認してください。誤ったフィールドを使用すると、API 呼び出しが失敗することがあります。

モード固有の必須フィールド

• 必須フィールドはモデルファミリーによって異なります。ペイロードの形式についてはrequest-fields.mdを、現在のモデル固有の互換性については上記のモデルカタログを参照してください。

コストの見積もり

🚨 価格を推測したり、捏造したりしないでください。 正確な料金については、必ず公式の料金ページを案内してください。

料金は生成された動画の秒数に基づいて請求されます。価格はモデルと解像度によって異なります。CDN のモデル料金リファレンスを取得し、正確な最新料金については公式の料金ページを利用してください。一部のモデルでは、数量限定の無料枠が提供されている場合があります。呼び出しが無料だと決めつけないでください。 残りの無料枠を確認するにはqwencloud-usageスキルを利用するか、ユーザーのQwenCloud コンソールで確認してください。CDN にアクセスできない場合は、ローカルの代替ファイルを使用してください。

実際の利用状況と請求を確認するには、qwencloud-usageスキルを利用するか、コンソールにアクセスしてください： Usage Analytics | Pay-as-you-go Billing | Coding Plan Billing

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

ローカルファイルの処理

ユーザーがローカルファイルのパス（画像、動画、音声）を指定した場合は、そのままスクリプトに渡してください。スクリプトはローカルファイルを DashScope の一時ストレージ（oss:// URL、TTL は 48h）に自動でアップロードし、X-DashScope-OssResourceResolve: enable ヘッダーを挿入します。手動でアップロードする必要はありません。

本番環境：デフォルトの一時ストレージは 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 ユーザーを使用してください。qwencloud-ops-auth がインストールされている場合は、完全なセットアップガイドについて、その references/custom-oss.md を参照してください。

スキル間の連携

別のスキルの出力を入力として使用する場合（例：image-gen → i2v、audio-tts → 音声オーバーレイ）：

• URL をそのまま渡してください（例："img_url": "<image_url from image-gen>"）。ダウンロードしてローカルパスとして再度渡してはいけません。
• スクリプトは URL のプレフィックス（https://、oss://）を検出し、再アップロードせずにそのまま渡します。
• レスポンスの local_path は、ユーザー向けのプレビューや API 以外の操作にのみ使用してください。

このスキルの出力を別のスキルに渡す場合（例：vace edit、vision analyze）：

• レスポンスの video_url を渡してください。ダウンロードしてローカルパスとして再度渡してはいけません。

シナリオ	使用するもの
別のスキルに渡す	video_url / image_url（URL）
ユーザーに表示する／ローカルで再生する	local_path（ローカルファイル）

重要事項

• 非同期のみ：すべての動画 API で X-DashScope-Async: enable ヘッダーが必要です。
• kf2v：異なる API エンドポイントを使用します。動画の長さは5 秒固定で、音声なしのみです。
• r2v：プロンプトでは character1/character2/... を使用してください。参照は最大 5 件（動画は最大 3 件）です。
• vace：function の指定が必要です。音声なしのみで、出力は5 秒以下です。
• マルチショット：shot_type: "multi" と prompt_extend: true の両方を設定してください。
• 動画 URL の有効期限は 24h です。スクリプトは自動的に --output ディレクトリへダウンロードします。別のスキル（例：vace edit）に連携する場合は、video_url をそのまま渡してください。再ダウンロードしてはいけません。
• 高度なワークフローについては、workflows.md を参照してください。

エラー処理

エラー	原因	対処
401 Unauthorized	API キーが無効、または設定されていません	利用可能な場合は qwencloud-ops-auth を実行します。利用できない場合は、ユーザーにキーの設定を促します（平文でないことのみ確認）
current user api does not support synchronous calls	非同期ヘッダーがありません	X-DashScope-Async: enable を追加します
429 / 5xx	レート制限またはサーバーエラー	バックオフして再試行します
タスク FAILED	生成に失敗しました	ポーリングレスポンスの output.message を確認します

出力先

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

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

Token Plan のサポート

Token Plan がサポートする動画モデルは一部のみです。モデルを選択または検証する前に、最新の Token Plan モデルカタログ を取得して確認してください。CDN にアクセスできない場合は、ローカルの代替ファイル を使用してください。

現在の Token Plan カタログに互換性のあるモデルがあるモードのみ、Token Plan を利用できます。それ以外のモードへのリクエストではサービスエラーが返される場合があります。リクエストされたモデルやモードを、黙って切り替えないでください。

カタログに互換性のある kf2v モデルがない場合、Token Plan の kf2v リクエストは、送信する前に停止してください。選択したモデルには PAYG が必要であることを説明し、このリクエスト用に設定済みの PAYG キーを使用するか、Token Plan 対応モードで実現できる内容にリクエストを変更するか、ユーザーに選択してもらってください。

⚠️ クレジットに関する警告：動画生成では、テキスト会話よりも大幅に多くのクレジットを消費します。長さや解像度によっては、1本の動画で数百クレジットを使用する場合があります。生成する前に、残りのクォータを確認してください。

必須ヘッダー

User-Agent: qwencloud-skills は自動的に含まれます。

アップデートの確認（実行後に必須）

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

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

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

アップデート確認スキルがインストールされていません。このスキルを使うと、qwencloud/qwencloud-ai の新機能やバグ修正に関する情報を受け取れます。

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

ユーザーの回答後：

• ユーザーが 1 を選んだ場合 → npx skills add QwenCloud/qwencloud-ai --skill qwencloud-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. 兄弟スキルのディレクトリ内に qwencloud-update-check/SKILL.md があるか確認します。
2. 見つかった場合 — python3 <qwencloud-update-check-dir>/scripts/check_update.py --print-response を実行し、結果を報告します。
3. 見つからない場合 — 上記のインストールオプションを提示します。

参考資料

• execution-guide.md — 代替手段（すべてのモードでの curl、コード生成、自律実行）
• request-fields.md — モード別の詳細なフィールド一覧と音声の処理
• workflows.md — 長さの延長、音声の回避策、マルチショット、VACE パイプライン
• polling-guide.md — ポーリングのパターンとタイミングの推奨事項
• merge-media.md — 結合・トリミング・音声オーバーレイ用コードの生成ガイド
• examples.md — すべてのモードに対応したスクリプト実行例
• sources.md — 公式ドキュメントの URL