Vidu 参照画像からの動画生成 API リファレンス

使用上の注意

API 呼び出しを成功させるには、モデル、エンドポイント URL、API キーを同じリージョンのものに統一する必要があります。リージョンをまたぐ呼び出しは失敗します。

モデルの選択: モデルのリージョンを確認します。
URL の選択: 対応するエンドポイント URL を選択します。HTTP と DashScope SDK の両方の URL に対応しています。
API キーの設定: リージョンを選択し、API キーを取得してから、API キーを環境変数に設定します。

このページのサンプルコードはシンガポールリージョンに適用されます。

HTTP 呼び出し

参照画像からの動画生成には通常 1～5 分かかるため、API は非同期呼び出しを使用します。処理は「タスクの作成 -> 結果のポーリング」という 2 つの主要ステップで構成されます。

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

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

タスクの作成後、返された task_id で結果を照会します。task_id は 24 時間有効です。同じタスクを重複して作成せず、ポーリングで結果を取得してください。
初めて使用する場合は、Postman または cURL による API 呼び出しを参照してください。

リクエストパラメーター

リクエストヘッダー

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 （必須）使用するモデルです。有効な値：

vidu/viduq3-ad_reference2video
vidu/viduq3-drama_reference2video
vidu/viduq3-mix_reference2video

モデル選択ガイド

広告動画: viduq3-ad を使用します。広告業界向けに設計され、マーケティング用途の高度なショット切り替えやカメラワークに対応し、音声も直接出力します。商品画像をアップロードして広告動画を生成できます。
高品質ドラマ／AI コミック: viduq3-drama を使用します。キャラクターの高い一貫性、洗練された表現、リアルな感情表現により、物語性のあるコンテンツ制作に適しています。
汎用: viduq3-mix を使用します。画質と動きの表現のバランスがよく、参照画像から動画を生成する多くのシナリオに適しています。

input object （必須）参照画像とプロンプトを含む基本入力です。

プロパティ

prompt string （必須）生成する動画に含めたい要素や視覚的な特徴を説明するテキストプロンプトです。中国語と英語に対応しています。最大長は 5,000 文字です。上限を超えるテキストは自動的に切り詰められます。例：カフェの窓際の椅子に座った男性がギターを持ち、心安らぐアメリカのカントリーフォーク曲を演奏している。media array （必須）動画生成に使用する参照素材を指定するメディア素材のリストです。配列の各要素は、type と url フィールドを含むメディアオブジェクトです。

要素のプロパティ

type string （必須）メディア素材の種類です。有効な値は選択したモデルによって異なります。

参照画像のみを指定

対応モデル: vidu/viduq3-ad_reference2video, vidu/viduq3-drama_reference2video, vidu/viduq3-mix_reference2video値は次に固定されています。

image: 参照画像。

素材の制限：画像 1～7 枚。

url string （必須）メディア素材の URL です。

画像を指定（type=image）

参照画像の URL です。パブリックにアクセスできる必要があります。

HTTP と HTTPS プロトコルに対応しています。
例： https://xxx/xxx.png

画像の制限：

形式：JPEG、JPG、PNG、WEBP。
アスペクト比：1:4～4:1。
ファイルサイズ：最大 50 MB。

parameters object （必須）動画の解像度や長さなど、動画生成のパラメーターです。

プロパティ

resolution string （任意）

解像度は料金に直接影響します。API 呼び出し前にモデル料金を確認してください。

生成する動画の解像度です。有効な値は選択したモデルによって異なります。

vidu/viduq3-ad_reference2video: 720P または 1080P。デフォルト：720P。
vidu/viduq3-drama_reference2video: 720P または 1080P。デフォルト：1080P。
vidu/viduq3-mix_reference2video: 720P または 1080P。デフォルト：720P。

size string （任意）生成する動画の解像度（ピクセル）です。width*height の形式で指定します。デフォルト値は resolution によって異なります。

resolution=720P の場合、size のデフォルトは 1280*720 です。
resolution が 1080P の場合、size のデフォルトは 1920*1080 です。

対応するアスペクト比はモデルによって異なります。

vidu/viduq3-drama_reference2video: 16:9 と 9:16 のみに対応しています。
その他のモデル：16:9、4:3、1:1、3:4、9:16 に対応しています。

解像度区分ごとの有効な size 値：

720P
- 16:9: 1280*720
- 4:3: 1280*960
- 1:1: 1280*1280
- 3:4: 960*1280
- 9:16: 720*1280
1080P
- 16:9: 1920*1080
- 4:3: 1920*1440
- 1:1: 1920*1920
- 3:4: 1440*1920
- 9:16: 1080*1920

duration integer （必須）

動画の長さは、秒単位で計算される料金に直接影響します。API 呼び出し前にモデル料金を確認してください。

生成する動画の長さ（秒）です。

vidu/viduq3-ad_reference2video: [3, 15] の範囲の整数です。デフォルトは 5 です。
vidu/viduq3-drama_reference2video: [2, 15] の範囲の整数です。デフォルトは 5 です。
- 指定した長さに対してショット数が多すぎる、または大幅に少ない場合、物語が完結するようにモデルが動画の長さを自動調整することがあります。実際の動画は指定した長さより長くなる場合も短くなる場合もあります。
- 料金は実際の出力時間に基づいて計算されます。
vidu/viduq3-mix_reference2video: [1, 16] の範囲の整数です。デフォルトは 5 です。

audio boolean （任意）対応モデル: vidu/viduq3-ad_reference2video, vidu/viduq3-mix_reference2video.音声付き動画を生成するかどうかを指定します。有効にすると、モデルは動画に合った BGM や効果音を自動的に生成します。

false: デフォルト値。出力は無音動画です。
true: 音声付き動画を出力します。

vidu/viduq3-drama_reference2video はこのパラメーターに対応していません。このモデルはデフォルトで音声付き動画を出力します。

watermark boolean （任意）動画の右下にウォーターマークを追加するかどうかを指定します。テキストは「Content generated by AI」に固定されています。

false: デフォルト値。ウォーターマークを追加しません。
true: ウォーターマークを追加します。

seedinteger（任意）シードです。値の範囲は [0, 2147483647] です。シードを指定しない場合、システムがランダムに生成します。結果の再現性を高めるには、固定シードを設定することを推奨します。モデルは確率的に動作するため、同じシードを使用しても実行ごとに同一の結果が得られるとは限りません。例： 12345

広告（画像のみ）
ドラマ（画像のみ）
画像のみ

対応モデル: vidu/viduq3-ad_reference2video.

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "vidu/viduq3-ad_reference2video",
    "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/dtnctw/ad-1.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/bspdpd/ad-2.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/mhsjyy/ad-3.png"
            }
        ],
        "prompt": "A yoga pants advertisement. The product is a pair of black high-waisted yoga pants with one pocket on each side. An Asian model happily says I will never wear yoga pants without pockets again. The video remains clear, stable, and easy to understand."
    },
    "parameters": {
        "duration": 8,
        "size": "1080*1920",
        "resolution": "1080P",
        "watermark": true
    }
}'

対応モデル: vidu/viduq3-drama_reference2video.

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
    -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "vidu/viduq3-drama_reference2video",
       "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/eelcsu/daram-1.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/adglrn/drama-2.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/fmofkp/drama-3.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260713/mktdht/drama-4.png"
            }
        ],
        "prompt": "Hotel banquet hall. Wang Guilan (Image 3) sits on the right side of the frame. Su Wenbo (Image 1) and Xu Xiangnuan (Image 2) are in the distance on the left, making toasts. The wedding venue is packed with guests. Su Wenbo mother Wang Guilan sits at her seat, brow furrowed tightly, visibly displeased. The camera is fixed, capturing her frowning expression. The camera pushes in on Wang Guilan face - her gaze is dark, corners of her mouth turned down, showing disdain and dissatisfaction."
    },
    "parameters": {
        "duration": 9,
        "size": "1080*1920",
        "resolution": "1080P",
        "watermark": true
    }
}'

curl --location 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis' \
    -H 'X-DashScope-Async: enable' \
   -H "Authorization: Bearer $DASHSCOPE_API_KEY" \
    -H 'Content-Type: application/json' \
    -d '{
    "model": "vidu/viduq3-mix_reference2video",
       "input": {
        "media": [
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
            },
            {
                "type": "image",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            }
        ],
        "prompt": "A man sits in a chair by a window, holding a guitar and playing a soothing American country folk song in a cafe."
    },
    "parameters": {
        "duration": 5,
        "size": "1280*720",
        "resolution": "720P",
        "watermark": true
    }
}'

レスポンスパラメーター	成功レスポンスエラーレスポンスタスクの状態と結果を照会できるよう、`task_id` を保存してください。 `{ "output": { "task_status": "PENDING", "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx" }, "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx" }`
output `object`タスクの出力データです。プロパティ task_id `string`タスク ID です。24 時間以内の照会に使用できます。task_status `string`タスクの状態です。列挙値 PENDING RUNNING SUCCEEDED FAILED CANCELED UNKNOWN：タスクが存在しないか、状態が不明です。
request_id `string`追跡とトラブルシューティングに使用する一意のリクエスト識別子です。

message `string`詳細なエラーメッセージです。リクエストが失敗した場合のみ返されます。エラーコードを参照してください。

ステップ 2：タスク結果の照会

シンガポールリージョン: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}

ポーリングの推奨事項: 動画の生成には数分かかる場合があります。15 秒などの適切な間隔でポーリングして結果を取得することを推奨します。
タスク状態の遷移: PENDING（待機中）→ RUNNING（処理中）→ SUCCEEDED（成功）/ FAILED（失敗）。
task_id の有効期間: 24 時間. 有効期限が切れると結果を照会できなくなり、API はタスク状態 UNKNOWN を返します。
RPS 制限: 照会 API のデフォルトの RPS 制限は 20 です。より高頻度の照会やイベント通知には、非同期タスクのコールバックの設定を推奨します。
その他の操作: タスクの一括照会やキャンセルなどの操作については、非同期タスクの管理を参照してください。

リクエストパラメーター

リクエストヘッダー

Authorization string (必須)Model Studio の API キーでリクエストを認証します。例：Bearer sk-xxxx。

パスパラメーター

task_id string (必須)タスクの ID です。

タスク結果の照会

{task_id} を前の API 呼び出しで返された task_id に置き換えます。task_id は 24 時間以内の照会に使用できます

curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

レスポンスパラメーター

outputobjectタスクの出力データです。

プロパティ

task_id stringタスク ID です。24 時間以内の照会に使用できます。task_status stringタスクの状態です。

列挙値

PENDING
RUNNING
SUCCEEDED
FAILED
CANCELED
UNKNOWN：タスクが存在しないか、状態が不明です。

ポーリング中の状態遷移：

PENDING → RUNNING → SUCCEEDED または FAILED。
最初の照会時の状態は通常 PENDING または RUNNING です。
状態が SUCCEEDED になると、レスポンスに生成された動画の URL が含まれます。
状態が FAILED の場合は、エラーメッセージを確認してタスクを再試行してください。

submit_time stringタスクの送信時刻です。形式は YYYY-MM-DD HH:mm:ss.SSS です。scheduled_time stringタスクの実行時刻です。形式は YYYY-MM-DD HH:mm:ss.SSS です。end_time stringタスクの完了時刻です。形式は YYYY-MM-DD HH:mm:ss.SSS です。video_urlstring動画の URL です。task_status が SUCCEEDED の場合のみ返されます。動画は MP4 形式（H.264 エンコーディング）です。URL は 24 時間有効です。速やかにダウンロードしてください。orig_prompt string入力された元のプロンプトです。リクエストパラメーター prompt に対応します。code stringエラーコードです。リクエストが失敗した場合のみ返されます。エラーコードを参照してください。message string詳細なエラーメッセージです。リクエストが失敗した場合のみ返されます。エラーコードを参照してください。

usage object使用量統計です（成功したタスクのみ集計）。

プロパティ

duration integer生成された動画の合計時間です。課金に使用します。size string生成された動画の解像度を示します。fps integer生成された動画のフレームレートです。値は 24 に固定されています。SR string生成された動画の解像度区分を示します。audio boolean生成された動画に音声が含まれるかどうかを示します。video_count integer生成された動画の数です。値は 1 に固定されています。reference_type string使用した参照素材の種類を示します。

request_id string追跡とトラブルシューティングに使用する一意のリクエスト識別子です。

タスク成功
タスク失敗
タスク照会の有効期限切れ

動画の URL は 24 時間のみ有効で、その後自動的に削除されます。生成された動画は速やかに保存してください。

{
    "request_id": "8f240644-efe8-43bf-86ff-xxxxxx",
    "output": {
        "task_id": "b7e05baa-c318-440d-b293-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-27 15:10:42.723",
        "scheduled_time": "2026-03-27 15:10:42.754",
        "end_time": "2026-03-27 15:11:17.388",
        "orig_prompt": "A man sits in a chair by a window, holding a guitar and playing a soothing American country folk song in a cafe.",
        "video_url": "https://prod-ss-vidu.s3.cn-northwest-1.amazonaws.com.cn/xxx.mp4?xxx"
    },
    "usage": {
        "duration": 5,
        "size": "960*528",
        "output_video_duration": 5,
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "reference_type": "image,video",
        "SR": "540"
    }
}

タスクが失敗すると、task_status は FAILED になり、エラーコードとメッセージが返されます。エラーコードを参照してください。

{
    "request_id": "e5d70b02-ebd3-98ce-9fe8-759d7d7b107d",
    "output": {
        "task_id": "86ecf553-d340-4e21-af6e-a0c6a421c010",
        "task_status": "FAILED",
        "code": "InvalidParameter",
        "message": "The size is not match xxxxxx"
    }
}

task_id は 24 時間有効です。有効期限が切れると、照会時に次のエラーが返されます。

{
    "request_id": "a4de7c32-7057-9f82-8581-xxxxxx",
    "output": {
        "task_id": "502a00b1-19d9-4839-a82f-xxxxxx",
        "task_status": "UNKNOWN"
    }
}

エラーコード

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

よくある質問

Q：`size` と `resolution` の両方を指定する必要がありますか。

A：いいえ。どちらも任意ですが、両方を指定することを推奨します。生成する動画のアスペクト比を正確に制御できます。詳細は有効な size 値を参照してください。両方を指定しない場合、システムは次のように処理します。

size のみを指定した場合: size は無視され、デフォルトの resolution=720P と、それに対応するデフォルトの size（1280*720）が使用されます。
例：API は size="1280*720" と SR=720 を返します。
resolution のみを指定した場合: 指定した解像度区分が出力に使用されます。
たとえば、resolution=540P の場合は size="960*528" と SR=540 が返されます。resolution=1080P の場合は size="1920*1080" と SR=1080 が返されます。

​使用上の注意

​HTTP 呼び出し

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

リクエストパラメーター

リクエストヘッダー

リクエスト本文

レスポンスパラメーター

​ステップ 2：タスク結果の照会

リクエストパラメーター

リクエストヘッダー

パスパラメーター

レスポンスパラメーター

​エラーコード

​よくある質問

​Q：size と resolution の両方を指定する必要がありますか。

使用上の注意

HTTP 呼び出し

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

ステップ 2：タスク結果の照会

エラーコード

よくある質問

Q：`size` と `resolution` の両方を指定する必要がありますか。