wan wan2.2-animate-mix 動画キャラクター置き換え API リファレンス - Alibaba Cloud Model Studio

動画内のメインキャラクターを画像のキャラクターに置き換え、元のシーン・照明・トーンを維持してシームレスな統合を実現します。

主な機能：指定された画像の人物で動画内のキャラクターを置き換え、元の動画の動作・表情・環境を保持します。
利用シーン：二次創作コンテンツやポストプロダクションにおけるキャラクター置き換えに最適です。

重要

シンガポールリージョン向けのレガシドメイン https://dashscope-intl.aliyuncs.com はまもなく非推奨になります。できるだけ早く新しいドメイン https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com へ移行してください。

使用例

wan2.2-animate-mix は標準モード (wan-std) とプロフェッショナルモード (wan-pro) の 2 つのサービスモードをサポートしています。パフォーマンスおよび課金の違いについては、「課金とレート制限」をご参照ください。

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

HTTP

API キーの作成および API キーを環境変数としてエクスポートします。

重要

北京およびシンガポールリージョンでは、それぞれ独立した API キー および リクエストエンドポイント を使用します。これらは相互に使用できません。リージョンをまたいだ呼び出しは認証エラーまたはサービスエラーを引き起こします。

キャラクター置き換え処理には時間がかかるため、この API は非同期呼び出しを使用します。タスクを作成した後、結果をポーリングで取得します。

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

シンガポール：POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/image2video/video-synthesis

WorkspaceId は、実際のワークスペース ID に置き換えてください。

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

説明

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

リクエストパラメーター	動画キャラクター置き換え以下はシンガポールリージョンの URL です。WorkspaceId は実際のワークスペース ID に置き換えてください。URL はリージョンによって異なります。 curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.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 です。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 です。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 生成」のウォーターマークを追加します。 `false` (デフォルト)：ウォーターマークなし。 `true`：ウォーターマークを追加。
parameters `object` (必須) プロパティ check_image `boolean` (オプション) 処理前に入力画像をチェックするかどうかを制御します。 `true` (デフォルト)：処理前に入力画像をチェックします。 `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://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

呼び出し時に、WorkspaceId は実際のワークスペース ID に置き換えてください。

北京

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

説明

ポーリングの推奨設定：動画生成には数分かかります。15 秒程度の適切な間隔でポーリングメカニズムを使用してください。
タスク状態の遷移：PENDING → RUNNING → SUCCEEDED または FAILED。
結果リンク：タスクが成功すると、24 時間 有効な動画 URL が返されます。OSS などの永続ストレージに動画をダウンロードして保存してください。
task_id の有効期間：24 時間。この期間を過ぎると、照会時にタスクステータスが UNKNOWN として返されます。

リクエストパラメーター	タスク結果の照会 `0385dc79-5ff8-4d82-bcb6-xxxxxx` は、実際の task_id に置き換えてください。以下はシンガポールリージョンの URL です。WorkspaceId は実際のワークスペース ID に置き換えてください。URL はリージョンによって異なります。 `curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.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 + 08:00 で、形式は YYYY-MM-DD HH:mm:ss.SSS です。 scheduled_time `string` タスクが実行された時刻です。時刻は UTC + 08:00 で、形式は YYYY-MM-DD HH:mm:ss.SSS です。 end_time `string` タスクが完了した時刻です。時刻は UTC + 08:00 で、形式は YYYY-MM-DD HH:mm:ss.SSS です。 results `object` プロパティ video_url `string` 生成された動画の URL です。`task_status` が SUCCEEDED の場合にのみ返されます。有効期間は 24 時間です。動画は H.264 エンコーディングの MP4 形式です。 code `string` エラーコードです。失敗したリクエストでのみ返されます。「エラーコード」をご参照ください。 message `string` 詳細なエラーメッセージです。失敗したリクエストでのみ返されます。「エラーコード」をご参照ください。
usage `object` 成功したタスクでのみ返されます。プロパティ video_duration `float` 生成された動画の再生時間（秒単位）です。 video_ratio `string` このリクエストで使用されたサービスモードです。`wan-std` モードの場合は `standard`、`wan-pro` モードの場合は `pro` が返されます。
request_id `string` トレースおよびトラブルシューティング用の一意のリクエスト識別子です。

制限事項

データ保持期間：タスク ID および動画 URL は 24 時間保持されます。有効期限が切れる前に動画をローカルデバイスにダウンロードしてください。

コンテンツモデレーション：すべての入力および出力コンテンツはモデレーションの対象となります。禁止されたコンテンツの場合、IPInfringementSuspect または DataInspectionFailed のエラーが返されます。詳細については、「エラーコード」をご参照ください。

課金とレート制限

無料クォータおよび単位価格については、「モデルの価格設定」をご参照ください。
レート制限については、「Wan シリーズ」をご参照ください。
課金の詳細：
- 課金は、正常に生成された動画の出力動画の再生時間（秒単位）に基づいて行われます。入力は課金対象外です。
- 失敗した呼び出しおよび処理エラーは、料金が発生せず、無料クォータも消費しません。

エラーコード

呼び出しが失敗した場合は、「エラーコード」をご参照ください。

よくある質問

Q：モデル呼び出しの使用量を確認するにはどうすればよいですか？

A：呼び出しデータには約 1 時間の遅延があります。モニタリングページ (シンガポールまたは北京) で、メトリック（呼び出し量、回数、成功率）を確認できます。詳細については、「モデル呼び出しレコードの確認方法」をご参照ください。

Q：生成される動画の品質を向上させるにはどうすればよいですか？

A：より良い結果を得るには、以下の点に注意してください。

入力画像とリファレンス動画の両方で、キャラクターの構図を一貫性のあるものにしてください。
画像と動画の間で体の比率を一致させてください。
高精細なソース素材を使用してください。ぼやけた画像やフレームレートの低い動画は、ディテールの精度を低下させます。

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

A：直接変換はサポートされていません。バックエンドで動画をダウンロードし、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：タスクの作成

リクエストパラメーター

動画キャラクター置き換え

ヘッダー

リクエスト本文

レスポンスパラメーター

成功時のレスポンス

エラー時のレスポンス