qianwen-video-generation

Qwen Video Generation

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

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

• kf2v（最初と最後のフレーム）：長さは5秒に固定されています。他の値を指定すると失敗します。出力は無音のみです。
• 解像度パラメーターはモードだけでなく、モデルファミリーによっても異なります：size、resolution、ratio を選択する前に、現在のモデルカタログを確認してください。たとえば、happyhorse-1.1-t2v は resolution と ratio を使用し、wan2.6-t2v は size を使用します。

スキルディレクトリ

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

場所	目的
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 キーや認証情報を平文で出力しないでください。 常に変数参照（シェルでは $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-...）のキーに対応しています。キーを公開せずに API キーの種類を判別してください：

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 はローカルファイルのアップロードに対応していません。i2v/r2v/kf2v モードでは、ローカルパスではなく、アクセス可能な URL（https:// または oss://）で参照画像や動画を指定してください。

Token Plan で使用できるのは特定のモデルのみです。上記のリファレンスに記載されたモデルを正確に使用し、モデルが利用可能か推測したり、試しにリクエストを送信したりしないでください。PAYG の場合は、以下に進んでください。

モード選択ガイド

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

モデルの選択

1. ユーザーがモデルを指定した場合 → そのまま使用します。
2. モデルの選択が機能、シナリオ、または料金に左右される場合は、qianwen-model-selector スキルを参照します。

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

エンドポイント：/services/aigc/video-generation/video-synthesis。

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

モデルの詳細：特定のモデルについて詳しく知りたい場合は、ユーザーに 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.mp4、out_2.mp4）。

前提条件

• API Key：Key Compatibility に記載されている平文でないことを検出する方法を使用してください。変数の有無を確認する方法に置き換えないでください。Key が見つからない場合、利用可能であれば qianwen-ops-auth を使用するか、.env で DASHSCOPE_API_KEY／QIANWEN_API_KEY を設定するようユーザーに案内してください。スキルは個別にインストールできます。
• Python 3.9 以降（標準ライブラリのみ、pip install は不要）
• メディアの結合（連結、トリミング、音声の重ね合わせ）については、ユーザーの環境に適した ffmpeg/moviepy の手順が記載された merge-media.md を参照してください

環境の確認

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

python3 --version  # must be 3.9+

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

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

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

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

確認：最初に python3 <this-skill-dir>/scripts/video.py --help を実行して、使用できるすべての引数を確認してください。

python3 <this-skill-dir>/scripts/video.py \
  --request '{"model":"happyhorse-1.1-t2v","prompt":"A detective in a rainy city at night","resolution":"720P","ratio":"16:9","duration":5}' \
  --print-response

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

モデルの優先順位：--model CLI フラグ > --request JSON 内の "model" フィールド > 設定されたデフォルト値。モデルが指定されていない場合は、設定されたデフォルト値が使用されます。これは必ずしも最新または最も高性能なモデルとは限りません。

結果を確認する

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

失敗時

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

Python がまったく利用できない場合 → execution-guide.md のパス 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	サーバーエラー	バックオフを適用して再試行してください
ImportError: moviepy	moviepy がインストールされていません	pip install moviepy を実行するか、代わりにシステムの ffmpeg を使用してください（merge-media.md を参照）
PermissionError	出力を書き込めません	--output を使って書き込み可能なディレクトリを指定してください

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

すべてのモードで prompt が必要です。各モードのフィールド一覧については request-fields.md を参照してください。

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

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

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

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

コストの見積もり

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

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

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

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

ローカルファイルの処理

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

本番環境：デフォルトの一時ストレージは TTL が 48 時間で、アップロード上限は 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 を参照してください。

スキル間の連携

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

• URL を直接渡してください（例："img_url": "<image-gen の image_url>"）。ダウンロードしてローカルパスとして再度渡さないでください
• スクリプトは 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 の有効期限は 24 時間です。スクリプトが --output ディレクトリに自動ダウンロードします。別のスキル（例：vace edit）と連携する場合は、video_url を直接渡してください。再ダウンロードしないでください。
• 高度なワークフローについては、workflows.md を参照してください。

エラー処理

エラー	原因	対応
401 Unauthorized	API キーが無効、または未設定	利用可能であれば qianwen-ops-auth を実行してください。そうでなければ、ユーザーにキーの設定を促してください（平文ではないことのみ確認）
current user api does not support synchronous calls	非同期ヘッダーが不足	X-DashScope-Async: enable を追加してください
429 / 5xx	レート制限またはサーバーエラー	バックオフして再試行してください
The product is not activated / Model not subscribed	アカウントでサードパーティ製モデルが有効になっていない	モデルマーケットにアクセスし、モデルを見つけて「Enable」／「有効化」をクリックしてください
タスク FAILED	生成に失敗	ポーリング応答の output.message を確認してください

出力先

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

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

更新の確認（実行後に必須）

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

シグナル：[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、コード生成、自律実行）
• request-fields.md — モード別の詳細なフィールド一覧と音声処理
• workflows.md — 再生時間の延長、音声の回避策、マルチショット、VACE パイプライン
• polling-guide.md — ポーリングのパターンと推奨タイミング
• merge-media.md — メディアの結合・トリミング・音声オーバーレイ用コードの生成ガイド
• examples.md — すべてのモードにおけるスクリプト実行の完全な例
• sources.md — 公式ドキュメントの URL