VideoRetalk API による唇同期ビデオの生成 - Model Studio

VideoRetalk は、指定された音声トラックと人物の口の動きを同期させることで、新しい動画を生成するモデルです。本ドキュメントでは、API を使用して動画を生成する方法について説明します。

重要

本ドキュメントは、中国 (北京) リージョンのみに適用されます。モデルをご利用になるには、中国 (北京) リージョンの API キーをご使用ください。

HTTP

VideoRetalk API は HTTP 呼び出しのみをサポートしています。待ち時間を短縮し、リクエストのタイムアウトを防止するため、非同期処理が採用されています。このため、動画を生成するには、以下の 2 つの別個のリクエストを実行する必要があります：

タスクの送信：動画生成タスクを作成するリクエストを送信します。API はタスク ID を返します。
タスク状態の照会および結果の取得：返されたタスク ID を使用して、タスクの状態を照会し、生成された動画を取得します。

前提条件

API キーを作成済みであり、API キーを環境変数として設定済みである必要があります。

入力制限事項

動画の要件：
- ファイル形式：MP4、AVI、MOV 形式がサポートされています。ファイルサイズは 300 MB 以下である必要があります。再生時間は 2 秒以上 120 秒以下である必要があります。
- プロパティ：動画のフレームレートは 15 fps 以上 60 fps 以下である必要があります。H.264 または H.265 でエンコードされている必要があります。各辺の長さは 640 ピクセル以上 2,048 ピクセル以下である必要があります。
- コンテンツ：正面を向いた人物のクローズアップショットである必要があります。極端な横角度や非常に小さい顔は避けてください。
音声の要件：
- ファイル形式：WAV、MP3、AAC 形式がサポートされています。ファイルサイズは 30 MB 以下である必要があります。再生時間は 2 秒以上 120 秒以下である必要があります。
- コンテンツ：明瞭かつ大きな音量の人間の声を含む必要があります。周囲の雑音やバックグラウンドミュージックなどの干渉は除去してください。
キャラクター参照画像の要件：
- ファイル形式：JPEG、JPG、PNG、BMP、WebP 形式がサポートされています。ファイルサイズは 10 MB 以下である必要があります。
- コンテンツ：動画に登場する人物の明瞭な正面顔画像である必要があります。また、動画からのスクリーンショットを使用することもできます。
ファイル URL の要件：
- アップロードした動画、音声、画像ファイルは、HTTP リンク経由でアクセス可能である必要があります。ローカルパスはサポートされていません。また、プラットフォームが提供する一時記憶領域を使用してローカルファイルをアップロードし、リンクを作成することもできます。

タスクの送信

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

リクエストパラメーター

フィールド	型	場所	必須	説明	例
Content-Type	String	Header	はい	リクエストタイプ：application/json	application/json
Authorization	String	Header	はい	API キー。例：Bearer d1**2a	Bearer d1**2a
X-DashScope-Async	String	Header	はい	タスクを非同期で作成することを示すために、`enable` を設定します。	enable
model	String	Body	はい	呼び出すモデルを指定します。	videoretalk
input.video_url	String	Body	はい	アップロードした動画ファイルの URL です。 URL は公開可能である必要があり、HTTP または HTTPS プロトコルを使用する必要があります。動画ファイルの要件：サイズ：ファイルサイズは 300 MB 以下である必要があります。形式：MP4、AVI、または MOV 形式がサポートされています。再生時間：2 秒以上 120 秒以下である必要があります。フレームレート：15 fps 以上 60 fps 以下である必要があります。エンコーディング：H.264 または H.265 を推奨します。辺の長さ：640 ピクセル以上 2048 ピクセル以下である必要があります。コンテンツ：正面を向いた人物のクローズアップショットである必要があります。極端な横角度や非常に小さい顔は避けてください。動画に顔全体または顔が含まれていない場合は、「よくある質問」をご参照ください。	http://aaa/bbb.mp4
input.audio_url	String	Body	はい	アップロードした音声ファイルの URL です。 URL は公開可能である必要があり、HTTP または HTTPS プロトコルを使用する必要があります。音声ファイルの要件：サイズ：ファイルサイズは 30 MB 以下である必要があります。形式：WAV、MP3、または AAC 形式がサポートされています。再生時間：2 秒以上 120 秒以下である必要があります。動画と音声の再生時間が異なる場合は、「よくある質問」をご参照ください。コンテンツ：明瞭かつ大きな音量の人間の発話が含まれている必要があります。背景ノイズや音楽はすべて除去してください。	http://aaa/bbb.wav
input.ref_image_url	String	Body	いいえ	参照用顔画像の URL です。 URL は公開可能である必要があり、HTTP または HTTPS プロトコルを使用する必要があります。入力動画に複数の顔が含まれる場合、どの顔を口の動きと同期させるかを指定するために本パラメーターを使用します。動画に 1 つの顔のみが含まれる場合は、本パラメーターは不要です。本パラメーターを省略した場合、システムは顔が検出される最初のフレーム内で最も大きい顔を自動的に選択します。画像ファイルの要件：コンテンツ：動画に登場する人物の明瞭な正面顔画像である必要があります。ファイルサイズ：10 MB 以下である必要があります。画像サイズ：縦横比は 2 以下である必要があります。最大辺の長さは 4,096 ピクセル以下である必要があります。形式：JPEG、JPG、PNG、BMP、または WebP 形式がサポートされています。	http://aaa/bbb.jpg
parameters.video_extension	ブール値	Body	いいえ	入力音声の再生時間が動画より長い場合に、動画の再生時間を延長するかどうかを指定します。デフォルト値は `false` です。 `true`：動画を「逆再生・順再生」パターンでループすることで、動画の再生時間を音声の長さに合わせて延長します。 `false`：動画の再生時間を延長しません。生成された動画の再生時間は元の動画と同じになり、音声は切り捨てられます。	false
parameters.query_face_threshold	Integer	Body	いいえ	参照用顔画像が指定されている場合の顔マッチングの信頼度レベルを調整します。値の範囲は 120 ～ 200 です。値が小さいほどマッチングが緩くなり、大きいほど厳しくなります。デフォルト値は 170 です。注：input.ref_image_url が空の場合、本パラメーターは無視されます。	170

応答パラメーター

フィールド	型	説明	例
output.task_id	String	送信された非同期タスクの ID です。この ID を使用して、タスク状態照会 API を呼び出して実際のタスク結果を取得します。	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	送信後のタスクのステータスです。	"PENDING"
request_id	String	リクエスト ID です。	7574ee8f-38a3-4b1e-9280-11c33ab46e51

サンプルリクエスト

curl --location 'https://dashscope.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": "videoretalk",
    "input": {
        "video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250717/pvegot/input_video_01.mp4",
        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250717/aumwir/stella2-%E6%9C%89%E5%A3%B0%E4%B9%A67.wav",
        "ref_image_url": ""
     },
    "parameters": {
        "video_extension": false
    }
  }'

サンプル応答

{
    "output": {
	"task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1", 
    	"task_status": "PENDING"
    },
    "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51"
}

タスク状態の照会および結果の取得

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

リクエストパラメーター

フィールド	型	場所	必須	説明	例
Authorization	String	Header	はい	API キー。例：Bearer d1**2a。	Bearer d1**2a
task_id	String	Url Path	はい	照会対象のタスク ID です。これはタスク送信 API から返された値です。	a8532587-fa8c-4ef8-82be-0c46b17950d1

応答パラメーター

フィールド	型	説明	例
output.task_id	String	照会対象のタスク ID です。	a8532587-fa8c-4ef8-82be-0c46b17950d1
output.task_status	String	照会対象のタスクのステータスです。	タスクステータス： PENDING PRE-PROCESSING RUNNING POST-PROCESSING SUCCEEDED FAILED UNKNOWN：タスクが存在しない、またはそのステータスが不明です。
output.video_url	String	生成された動画です。video_url は、タスク完了後 24 時間有効です。	https://xxx/1.mp4"
usage.video_duration	Float	生成された動画の再生時間（秒単位）です。	"video_duration": 10.23
usage.video_ratio	String	生成された動画のアスペクト比タイプです。「standard」が値であり、デフォルトでは出力動画のアスペクト比が入力動画と同じになります。	"video_ratio": "standard"
usage.size	String	生成された動画の解像度で、入力動画と同じ解像度です。	"size": "1080*1920"
usage.fps	Integer	生成されるビデオのフレームレートと解像度は、入力ビデオと同じです。	"fps": 25
request_id	String	リクエスト ID です。	7574ee8f-38a3-4b1e-9280-11c33ab46e51

サンプルリクエスト

curl -X GET 'https://dashscope.aliyuncs.com/api/v1/tasks/<YOUR_TASK_ID>' \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

サンプル応答

{
    "request_id": "87b9dce5-7f36-4305-a347-xxxxxx",
    "output": {
        "task_id": "3afd65eb-9604-48ea-8a91-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-11 20:15:29.887",
        "scheduled_time": "2025-09-11 20:15:36.741",
        "end_time": "2025-09-11 20:16:40.577",
        "video_url": "http://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "video_duration": 7.2,
        "size": "1080*1920",
        "video_ratio": "standard",
        "fps": 25
    }
}

サンプルエラー応答

{
    "request_id": "7574ee8f-38a3-4b1e-9280-11c33ab46e51",
  	"output": {
        "task_id": "a8532587-fa8c-4ef8-82be-0c46b17950d1", 
    	"task_status": "FAILED",
    	"code": "xxx", 
    	"message": "xxxxxx" 
    }  
}

エラーコード

一般的な状態コードについては、「エラーメッセージ」をご参照ください。

本モデルには、以下の特定のエラーコードもあります：

HTTP リターンコード	エラーコード	エラーメッセージ	説明
400	InvalidParameter	必須フィールド：xxx	リクエストパラメーターが不足しているか、形式が正しくありません。
400	InvalidURL.ConnectionRefused	${url} への接続が拒否されました。利用可能な URL を指定してください。	ダウンロードが拒否されました。利用可能な URL を指定してください。
400	InvalidURL.Timeout	${url} のダウンロードがタイムアウトしました。ネットワーク接続をご確認ください。	ダウンロードがタイムアウトしました。タイムアウト期間は 60 秒です。
400	InvalidFile.Size	不正なファイルサイズです。動画／音声／画像ファイルのサイズは ** MB 未満である必要があります。	動画、音声、または画像ファイルは ** MB 未満である必要があります。
400	InvalidFile.Format	不正なファイル形式です。要求されたファイル形式は、MP4、AVI、MOV、MP3、WAV、AAC、JPEG、JPG、PNG、BMP、WEBP のいずれかである必要があります。	ファイル形式が不正です。動画は MP4、AVI、MOV 形式がサポートされています。音声は MP3、WAV、AAC 形式がサポートされています。画像は JPG、JPEG、PNG、BMP、WebP 形式がサポートされています。
400	InvalidFile.Resolution	不正な動画解像度です。動画の高さまたは幅は 640 ～ 2048 である必要があります。	動画の辺の長さは 640 ピクセル以上 2048 ピクセル以下である必要があります。
400	InvalidFile.FPS	不正な動画 FPS です。動画の FPS は 15 ～ 60 である必要があります。	動画のフレームレートは 15 fps 以上 60 fps 以下である必要があります。
400	InvalidFile.Duration	不正なファイル再生時間です。動画／音声ファイルの再生時間は 2 秒～ 120 秒である必要があります。	動画または音声ファイルの再生時間は 2 秒以上 120 秒以下である必要があります。
400	InvalidFile.ImageSize	画像サイズが制限を超えています。	画像サイズが制限を超えています。画像の縦横比は 2 以下である必要があり、最長辺は 4,096 ピクセル以下である必要があります。
400	InvalidFile.Openerror	不正なファイルです。動画／音声／画像としてファイルを開けません。	動画、音声、または画像ファイルを開くことができません。
400	InvalidFile.Content	入力画像に人体がなく、または複数の人体があります。他の単一人物の画像をアップロードしてください。	入力画像に人物がいないか、複数の人物が含まれています。
400	InvalidFile.FaceNotMatch	提供された参照画像と一致する顔が動画内に見つかりません。	参照画像の顔と動画内の顔が一致しません。

よくある質問

入力動画と音声の再生時間が異なる場合、どのように対応すればよいですか？
デフォルトでは、長い方のファイルが短い方の再生時間に合わせて切り捨てられます。
入力音声の再生時間が動画より長い場合に、音声の長さに基づいて動画を生成したい場合は、video_extension パラメーターを true に設定します。これにより、動画が「逆再生・順再生」パターンでループされ、再生時間が音声の長さに一致するまで延長されます。
入力音声内の無音セグメントに対して、API はどのように処理しますか？
モデルは、入力音声内の無音セグメントに対応して、人物の口が閉じた状態のフレームを生成します。
動画フレームに顔が含まれていないが、対応する音声に発話がある場合、どうなりますか？
元の動画フレームは保持され、音声はそのまま再生されます。口の動きとの同期は、検出可能な顔が存在するフレームに対してのみ適用されます。
複数の人物が映っている動画で、特定の人物の口の動きを同期させるにはどうすればよいですか？
API は動画内の 1 人のみの口の動きを同期できます。アルゴリズムは、入力参照画像（input.ref_image_url）を使用して指定された顔を検出します。指定されていない場合は、顔が検出される最初のフレーム内で最も大きい顔をデフォルトで選択します。