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 秒の間である必要があります。
- 音声コンテンツ: 音声には、クリアで大きな人間の声が含まれている必要があります。環境ノイズやバックグラウンドミュージックなどの干渉は除去する必要があります。
キャラクター参照イメージ要件:
- ファイル制限: 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 秒より短い必要があります。ビデオと音声のデュレーションが異なる場合の対処方法については、「よくある質問」をご参照ください。コンテンツ: 音声には、クリアで大きな人間の声が含まれている必要があります。環境ノイズやバックグラウンドミュージックなどの干渉は除去する必要があります。	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/en-US/20250717/pvegot/input_video_01.mp4",
        "audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/en-US/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 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"
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 fps から 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) を使用して指定された顔を検出します。参照イメージが提供されていない場合、アルゴリズムはデフォルトで、顔を含む最初のフレームで最も大きい顔を選択します。