Wan2.2 Animate Mix でビデオキャラクターを交換 - Model Studio

Wan ビデオキャラクター入れ替えモデルは、ビデオ内のメインキャラクターを画像内のキャラクターに置き換えます。このモデルは、元のビデオのシーン、ライティング、トーンを維持し、シームレスな統合を実現します。

主な特徴： 元のビデオの動作、表情、環境を維持しながら、ビデオ内のキャラクターを指定された画像の人物に置き換えます。
利用シーン： 二次創作やポストプロダクションなど、キャラクターの入れ替えが必要なシナリオに適しています。

例

wan2.2-animate-mix は、パフォーマンスと課金が異なる 2 つのサービスモードで利用できます：標準モード wan-std とプロフェッショナルモード wan-pro です。詳細については、「課金とレート制限」をご参照ください。

キャラクター画像	リファレンスビデオ	出力ビデオ (標準モード`wan-std`)	出力ビデオ (プロフェッショナルモード`wan-pro`)

HTTP

API キーを取得し、API キーを環境変数としてエクスポートしてください。

重要

北京リージョンとシンガポールリージョンでは、API キーとリクエストエンドポイントがそれぞれ異なります。これらを相互に使用しないでください。リージョンをまたいだ呼び出しは、認証失敗やサービスエラーの原因となります。

ビデオキャラクター入れ替えタスクは時間がかかるため、API は「タスクの作成 → 結果のポーリング」の 2 つのステップからなる非同期呼び出しを使用します。

ステップ 1：タスクの作成

シンガポール：POST https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

北京：POST https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

説明

タスクが作成された後、返された task_id を使用して結果をクエリします。task_id は 24 時間有効です。重複したタスクを作成しないでください。代わりに、ポーリングを使用して結果を取得してください。
初心者向けチュートリアルについては、「Postman」をご参照ください。

リクエストパラメーター	ビデオキャラクター入れ替え以下はシンガポールリージョンの base_url です。北京リージョンのモデルを使用する場合は、base_url を次のように置き換えてください：`https://dashscope.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis` curl --location 'https://dashscope-intl.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis' \ --header 'X-DashScope-Async: enable' \ --header "Authorization: Bearer $DASHSCOPE_API_KEY" \ --header 'Content-Type: application/json' \ --data '{ "model": "wan2.2-animate-mix", "input": { "image_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg", "video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4", "watermark": true }, "parameters": { "mode": "wan-std" } }'
ヘッダー
Content-Type `string` (必須) リクエストのコンテントタイプです。`application/json` である必要があります。
Authorization `string` (必須) Model Studio API キーを使用した認証情報です。例：`Bearer sk-xxxx`
X-DashScope-Async `string` (必須) 非同期処理を有効にします。HTTP リクエストは非同期処理のみをサポートするため、`enable` に設定する必要があります。重要このヘッダーを含めないと、「current user api does not support synchronous calls」というエラーが返されます。
リクエストボディ
model `string` (必須) モデル名です。`wan2.2-animate-mix` に設定します。
input `object` (必須) 基本的な入力情報です。プロパティ image_url `string` (必須) 入力画像へのパブリックにアクセス可能な HTTP または HTTPS リンクです。URL には中国語などの非 ASCII 文字を含めることはできません。含まれている場合は、渡す前に URL をエンコードする必要があります。フォーマット：JPG、JPEG、PNG、BMP、または WEBP。解像度の制限：画像の幅と高さは `[200, 4096]` ピクセルの範囲内である必要があります。アスペクト比は 1:3 から 3:1 の間でなければなりません。ファイルサイズ：5 MB まで例: `https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/bhkfor/mix_input_image.jpeg` video_url `string` (必須) 入力ビデオへのパブリックにアクセス可能な HTTP または HTTPS リンクです。URL には中国語などの非 ASCII 文字を含めることはできません。含まれている場合は、渡す前に URL をエンコードする必要があります。推奨事項：生成されるビデオの品質を向上させるために、リファレンスビデオの解像度とフレームレートを高くすることを推奨します。フォーマット：MP4、AVI、または MOV。解像度の制限：ビデオの幅と高さは `[200, 2048]` ピクセルの範囲内である必要があります。アスペクト比は 1:3 から 3:1 の間でなければなりません。ファイルサイズ：200 MB まで長さ：2～30 秒例: `https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4` watermark `boolean` (任意) ウォーターマークを追加するかどうかを指定します。ウォーターマークは、「AI Generated」という固定テキストでビデオの右下隅に配置されます。 false (デフォルト) true
parameters `object` (必須) プロパティ check_image `boolean` (任意) 画像検出を実行するかどうかを指定します。 `true` (デフォルト)：API が入力画像を検出します。 `false`：画像検出をスキップし、画像を直接処理します。 mode `string` (必須) モデルサービスモードです。以下の 2 つのモードがサポートされています： `wan-std`：標準モード。このモードは結果をより速く生成し、コスト効率が高いです。迅速なプレビューや基本的なアニメーションシナリオに適しています。 `wan-pro`：プロフェッショナルモード。このモードはより滑らかなアニメーションと優れた効果を提供しますが、それに応じて処理時間とコストが増加します。詳細については、「例」および「課金とレート制限」をご参照ください。

レスポンスパラメーター	成功レスポンス `task_id` を保存して、タスクのステータスと結果をクエリします。 `{ "output": { "task_status": "PENDING", "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx" }, "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx" }` エラーレスポンスタスクの作成に失敗しました。問題を解決するには、「エラーコード」をご参照ください。 `{ "code": "InvalidApiKey", "message": "No API-key provided.", "request_id": "7438d53d-6eb8-4596-8835-xxxxxx" }`
output `object` タスクの出力情報です。プロパティ task_id `string` タスクの ID です。最大 24 時間、タスクのクエリに使用できます。 task_status `string` タスクのステータスです。列挙 PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN：タスクが存在しないか、ステータスが不明です
request_id `string` リクエストの一意の識別子です。問題のトレースとトラブルシューティングに使用します。
message `string` 詳細なエラーメッセージです。リクエストが失敗した場合にのみ返されます。詳細については、「エラーコード」をご参照ください。
code `string` エラーコードです。リクエストが失敗した場合にのみ返されます。詳細については、「エラーコード」をご参照ください。

ステップ 2：タスク ID による結果のクエリ

シンガポール：GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/{task_id}

北京：GET https://dashscope.aliyuncs.com/api/v1/tasks/{task_id}

説明

ポーリングの推奨事項：ビデオ生成には数分かかる場合があります。15 秒などの適切なクエリ間隔でポーリングメカニズムを使用して結果を取得することを推奨します。
タスクステータスの遷移：PENDING → RUNNING → SUCCEEDED または FAILED。
結果の URL：タスクが成功すると、ビデオの URL が返されます。URL は 24 時間有効です。URL を取得した後、すぐにビデオをダウンロードし、Object Storage Service (OSS) などの永続的なストレージサービスに保存する必要があります。
task_id の有効期間：24 時間。この期間を過ぎると、結果をクエリできなくなり、API はタスクステータスとして UNKNOWN を返します。

リクエストパラメーター	タスク結果のクエリ `0385dc79-5ff8-4d82-bcb6-xxxxxx` を実際の task_id に置き換えてください。以下のベース URL はシンガポールリージョン用です。北京リージョンのモデルを使用する場合は、ベース URL を次のように置き換えてください：`https://dashscope.aliyuncs.com/api/v1/tasks/0385dc79-5ff8-4d82-bcb6-xxxxxx` `curl -X GET https://dashscope-intl.aliyuncs.com/api/v1/tasks/0385dc79-5ff8-4d82-bcb6-xxxxxx \ --header "Authorization: Bearer $DASHSCOPE_API_KEY"`
ヘッダー
Authorization `string` (必須) Model Studio API キーを使用した認証情報です。例：`Bearer sk-xxxx`
URL パスパラメーター
task_id `string` (必須) クエリするタスクの ID です。

レスポンスパラメーター	タスク成功ビデオ URL は 24 時間のみ保持され、その後自動的にパージされます。生成されたビデオは速やかに保存してください。 `{ "request_id": "a67f8716-18ef-447c-a286-xxxxxx", "output": { "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx", "task_status": "SUCCEEDED", "submit_time": "2025-09-18 15:32:00.105", "scheduled_time": "2025-09-18 15:32:15.066", "end_time": "2025-09-18 15:34:41.898", "results": { "video_url": "http://dashscope-result-bj.oss-cn-beijing.aliyuncs.com/xxxxx.mp4?Expires=xxxxxx" } }, "usage": { "video_duration": 5.2, "video_ratio": "standard" } }` タスク失敗タスクが失敗すると、`task_status` は FAILED に設定され、エラーコードとメッセージが返されます。問題を解決するには、「エラーコード」をご参照ください。 `{ "request_id": "daad9007-6acd-9fb3-a6bc-xxxxxx", "output": { "task_id": "fe8aa114-d9f1-4f76-b598-xxxxxx", "task_status": "FAILED", "code": "InternalError", "message": "xxxxxx" } }`
output `object` タスクの出力情報です。プロパティ task_id `string` タスクの ID です。最大 24 時間、タスクのクエリに使用できます。 task_status `string` タスクのステータスです。列挙値 PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN：タスクが存在しないか、ステータスが不明です submit_time `string` タスクが送信された時刻です。時刻は UTC+8 です。フォーマット：`YYYY-MM-DD HH:mm:ss.SSS`。 scheduled_time `string` タスクの実行が開始された時刻です。時刻は UTC+8 です。フォーマット：`YYYY-MM-DD HH:mm:ss.SSS`。 end_time `string` タスクが完了した時刻です。時刻は UTC+8 です。フォーマット：`YYYY-MM-DD HH:mm:ss.SSS`。 results `object` プロパティ video_url `string` 生成されたビデオの URL です。`task_status` が SUCCEEDED の場合にのみ返されます。 URL は 24 時間有効です。この URL を使用して、H.264 エンコーディングの MP4 形式でビデオをダウンロードします。 code `string` エラーコードです。リクエストが失敗した場合にのみ返されます。詳細については、「エラーコード」をご参照ください。 message `string` 詳細なエラーメッセージです。リクエストが失敗した場合にのみ返されます。詳細については、「エラーコード」をご参照ください。
usage `object` 成功した結果の統計のみを出力します。プロパティ video_duration `float` 生成されたビデオの長さ (秒単位) です。 video_ratio `string` このリクエストで使用されたモデルサービスモードです。有効な値： `standard` および `pro`。 `mode` パラメーターを `wan-std` に設定した場合、このパラメーターは `standard` を返します。`mode` パラメーターを `wan-pro` に設定した場合、このパラメーターは `pro` を返します。
request_id `string` リクエストの一意の識別子です。問題のトレースとトラブルシューティングに使用します。

制限事項

データ保持期間：タスク ID とビデオ URL は 24 時間のみ保持されます。有効期限が切れた後は、クエリやダウンロードはできません。ビデオをローカルデバイスにダウンロードする必要があります。

コンテンツ審査：入力と出力の両方のコンテンツが Content Moderation の対象となります。禁止されているコンテンツを含むリクエストは、`IPInfringementSuspect` または `DataInspectionFailed` エラーを返します。詳細については、「エラーメッセージ」をご参照ください。

課金とレート制限

無料クォータと単価については、「モデル価格」をご参照ください。
レート制限については、「Wan シリーズ」をご参照ください。
課金の詳細：
- 入力に対しては課金されません。正常に生成されたビデオの長さ (秒単位) に基づいて出力に対して課金されます。
- モデルの呼び出し失敗や処理エラーは、料金が発生したり、無料クォータを消費したりすることはありません。

エラーコード

モデルの呼び出しが失敗し、エラーメッセージが返された場合は、「エラーメッセージ」を参照して問題を解決してください。

よくある質問

Q：モデル呼び出しの使用状況を表示するにはどうすればよいですか？

A：モデルの呼び出しデータには約 1 時間の遅延があります。モデルを呼び出してから約 1 時間後に、モニタリング (シンガポールまたは北京) ページに移動して、呼び出し量、呼び出し回数、成功率などのメトリックを表示できます。詳細については、「モデル呼び出し記録の表示方法」をご参照ください。

Q：生成されるビデオの品質を最適化するにはどうすればよいですか？

A：以下の提案をご検討ください：

入力画像におけるキャラクターのフレーミングが、リファレンスビデオのフレーミングと類似していることを確認してください。
画像とビデオの両方で、キャラクターの体の比率を一貫させてください。
高解像度のソース素材を使用してください。ぼやけた画像や低フレームレートのビデオを避け、正確な詳細認識を確保してください。

Q：一時的なビデオリンクを永続的なリンクに変換するにはどうすればよいですか？

A：リンクを直接変換することはできません。正しい方法は、バックエンドサービスが URL を使用してビデオファイルをダウンロードし、それを Object Storage Service (OSS) にアップロードして新しい永続的なアクセスリンクを生成することです。

サンプルコード：ビデオをローカルデバイスにダウンロードする

import requests

def download_and_save_video(video_url, save_path):
    try:
        response = requests.get(video_url, stream=True, timeout=300) # タイムアウトを設定
        response.raise_for_status() # HTTP ステータスコードが 200 でない場合に例外を発生させる
        with open(save_path, 'wb') as f:
            for chunk in response.iter_content(chunk_size=8192):
                f.write(chunk)
        print(f"ビデオが正常にダウンロードされました：{save_path}")
        # ここに永続ストレージへのアップロードロジックを追加できます
    except requests.exceptions.RequestException as e:
        print(f"ビデオのダウンロードに失敗しました：{e}")

if __name__ == '__main__':
    video_url = "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxxx"
    save_path = "video.mp4"
    download_and_save_video(video_url, save_path)

Q：返されたビデオリンクはブラウザで直接再生できますか？

A：リンクは 24 時間後に有効期限が切れるため、推奨されません。ベストプラクティスは、バックエンドでビデオをダウンロードして保存し、再生には永続的なリンクを使用することです。

Q：ビデオストレージのドメイン名ホワイトリストを取得するにはどうすればよいですか？

A：モデルによって生成されたビデオは OSS に保存されます。API は一時的なパブリック URL を返します。このダウンロード URL のファイアウォールホワイトリストを設定するには、次の点にご注意ください：基盤となるストレージは動的に変更される可能性があります。このトピックでは、古い情報によるアクセス問題を避けるため、固定の OSS ドメイン名ホワイトリストは提供していません。セキュリティ制御の要件がある場合は、アカウントマネージャーに連絡して最新の OSS ドメイン名リストを取得してください。

例

HTTP

ステップ 1：タスクの作成

リクエストパラメーター

ビデオキャラクター入れ替え

ヘッダー

リクエストボディ

レスポンスパラメーター

成功レスポンス

エラーレスポンス