VideoRetalk ビデオ生成 API リファレンス - Alibaba Cloud Model Studio

VideoRetalk は、人物ビデオ生成モデルです。人物のビデオと音声ファイルを使用して、入力された音声と人物の口の動きが同期した新しいビデオを生成できます。このドキュメントでは、このモデルが提供するビデオ生成機能の API の呼び出し方法について説明します。

重要

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

HTTP

VideoRetalk ビデオ生成 API は、HTTP 経由でのみ呼び出すことができます。待機時間を短縮し、リクエストのタイムアウトを回避するために、この API は非同期処理方式を採用しています。したがって、ビデオを生成するには 2 回のリクエストを行う必要があります。

タスクの送信：ビデオ生成タスクを作成するリクエストを送信します。API はタスク ID を返します。
タスクステータスのクエリと結果の取得：返されたタスク ID を使用してタスクステータスをクエリし、生成されたビデオを取得します。

前提条件

API キーを取得し、API キーを環境変数として設定済みであること。

入力制限

ビデオ要件：
- ファイル制限：MP4、AVI、MOV 形式のファイルがサポートされています。ファイルサイズは 300 MB 以下、時間は 2 秒から 120 秒の間である必要があります。
- ビデオ制限：ビデオのフレームレートは 15 fps から 60 fps の間、エンコーディングは H.264 または H.265 である必要があります。各辺の長さは 640 ピクセルから 2048 ピクセルの間でなければなりません。
- ビデオコンテンツ：ビデオは、正面を向いた人物のクローズアップである必要があります。極端な横顔や非常に小さい顔は避けてください。
音声要件：
- ファイル制限：WAV、MP3、AAC 形式のファイルがサポートされています。ファイルサイズは 30 MB 以下、時間は 2 秒から 120 秒の間である必要があります。
- 音声コンテンツ：音声には、クリアで大きな人間の声が含まれている必要があります。環境ノイズや BGM などの干渉は除去してください。
人物参照画像要件：
- ファイル制限：JPEG、JPG、PNG、BMP、WebP 形式のファイルがサポートされています。ファイルサイズは 10 MB 以下である必要があります。
- 画像コンテンツ：画像には、人物の顔がはっきりと正面から写っており、その人物がビデオに登場している必要があります。ビデオからキャプチャしたスクリーンショットを人物参照画像として使用することもできます。
アップロードされたファイルリンクの要件：
- アップロードされたビデオ、音声、および画像ファイルは、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 秒未満である必要があります。ビデオと音声の時間が異なる場合の対処法については、「よくある質問」をご参照ください。コンテンツ：音声には、クリアで大きな人間の声が含まれている必要があります。環境ノイズや BGM などの干渉は除去してください。	http://aaa/bbb.wav
input.ref_image_url	String	Body	いいえ	アップロードした参照顔画像の URL。 URL は、公開アクセス可能なアドレスであり、HTTP または HTTPS プロトコルをサポートしている必要があります。入力ビデオに複数の顔が存在する場合、このパラメーターを使用してリップシンクする顔を指定できます。ビデオに顔が 1 つしか存在しない場合は、指定する必要はありません。参照顔画像を提供しない場合、デフォルトでは、顔が含まれる最初のフレームで最も大きい顔が選択されます。画像ファイルの要件：コンテンツ：画像には、人物の顔がはっきりと正面から写っており、その人物がビデオに登場している必要があります。ファイルサイズ：ファイルサイズは 10 MB 以下である必要があります。画像サイズ：アスペクト比は 2 以下、最大辺長は 4096 ピクセル以下である必要があります。フォーマット：JPEG、JPG、PNG、BMP、または WebP。	http://aaa/bbb.jpg
parameters.video_extension	Boolean	Body	いいえ	入力音声がビデオより長い場合にビデオの長さを延長するかどうかを指定します。デフォルト値は `false` です。`true` または `false` に設定できます。このパラメーターを `true` に設定すると、ビデオの時間が音声の時間と一致するまで、元のビデオフレームが「逆再生」を交互に行うパターンで延長されます。このパラメーターを `false` に設定すると、ビデオの長さは延長されません。生成されるビデオは元のビデオと同じ時間になり、音声は切り捨てられます。	false

レスポンスパラメーター

フィールド	タイプ	説明	例
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/20250717/pvegot/input_video_01.mp4",
        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/20250717/aumwir/stella2-audiobook7.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 パス	はい	クエリするタスクの 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"
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.16,
        "video_ratio": "standard"
    }
}

エラーレスポンス例

{
    "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	Field required: xxx	リクエストパラメーターが欠落しているか、フォーマットが正しくありません。
400	InvalidURL.ConnectionRefused	Connection to ${url} refused, please provide avaiable URL	ダウンロードが拒否されました。利用可能な URL を提供してください。
400	InvalidURL.Timeout	Download ${url} timeout, please check network connection.	ダウンロードがタイムアウトしました。タイムアウト期間は 60 秒です。
400	InvalidFile.Size	Invalid file size. The video/audio/image file size must be less than **MB.	ビデオ、音声、または画像ファイルのサイズは ** MB 未満である必要があります。
400	InvalidFile.Format	Invalid file format，the request file format is one of the following types: MP4, AVI, MOV, MP3, WAV, AAC, JPEG, JPG, PNG, BMP, and WEBP.	ファイル形式が無効です。MP4、AVI、または MOV 形式のビデオ、MP3、WAV、または AAC 形式の音声、JPG、JPEG、PNG、BMP、または WebP 形式の画像がサポートされています。
400	InvalidFile.Resolution	Invalid video resolution. The height or width of video must be 640 ~ 2048.	ビデオの辺の長さは 640 から 2048 ピクセルの間でなければなりません。
400	InvalidFile.FPS	Invalid video FPS. The video FPS must be 15 ~ 60.	ビデオのフレームレートは 15 から 60 fps の間でなければなりません。
400	InvalidFile.Duration	Invalid file duration. The video/audio file duration must be 2s ~ 120s.	ビデオまたは音声ファイルの時間は 2 秒から 120 秒の間でなければなりません。
400	InvalidFile.ImageSize	The size of image is beyond limit.	画像サイズが制限を超えています。画像のアスペクト比は 2 以下、最長辺は 4096 ピクセル以下である必要があります。
400	InvalidFile.Openerror	Invalid file, cannot open file as video/audio/image.	ビデオ、音声、または画像ファイルを開けません。
400	InvalidFile.Content	The input image has no human body or multi human bodies. Please upload other image with single person.	入力画像に人物が含まれていないか、複数の人物が含まれています。
400	InvalidFile.FaceNotMatch	There are no matched face in the video with the provided reference image.	参照画像の顔が、ビデオ内のどの顔とも一致しません。

よくある質問

入力された音声とビデオの時間が一致しない場合はどのように処理されますか？
デフォルトでは、長い方のファイルが短い方のファイルの長さに合わせて切り捨てられます。
入力音声がビデオより長く、音声の長さに基づいてビデオを生成したい場合は、`video_extension` パラメーターを `true` に設定できます。アルゴリズムは、ビデオの時間が音声の時間と一致するまで、元のビデオフレームを使用して「逆再生」を交互に行うパターンでビデオの時間を延長します。
入力音声の無音部分はどのように処理されますか？
音声の無音部分では、ビデオ内の人物は口を閉じたままになります。
入力ビデオに人物がいない、または顔が不完全な場合はどのように処理されますか？
音声に人間の声が含まれているが、ビデオフレームに人物やその口が見えない場合、元のビデオフレームが保持され、音声は通常通り再生されます。
入力ビデオに複数の人物がいる場合はどのように処理されますか？
置き換えられる顔は 1 人だけです。アルゴリズムは、入力された参照画像 (`input.ref_image_url`) を使用して指定された顔を検出します。参照画像が提供されない場合、アルゴリズムはデフォルトで、顔が含まれる最初のフレームで最も大きい顔を選択します。