Skip to main content

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

PixVerse の参照画像から動画を生成するモデルは、複数の参照画像を受け付けます。テキストプロンプトでシーンを説明し、素材内の被写体キャラクターを融合して滑らかな動画を生成します。

このドキュメントはシンガポールリージョンにのみ適用されます。このリージョンの API キーを使用する必要があります。

サービスの有効化

  1. Model Studio コンソールに移動し、PixVerse を検索して PixVerse のモデルカードを見つけ、今すぐ有効化をクリックします。
  2. ポップアップウィンドウで、有効化と権限付与を確認します。

使用上の注意

API 呼び出しを成功させるには、モデル、エンドポイント URL、API キーを同じリージョンのものに統一する必要があります。リージョンをまたぐ呼び出しは失敗します。
  • モデルの選択: モデルのリージョンを確認します。
  • URL の選択: 対応するリージョンのエンドポイント URL を選択します。HTTP と DashScope SDK の両方の URL に対応しています。
  • API キーの設定: リージョンを選択し、API キーを取得してから、API キーを環境変数に設定します。
このページのサンプルコードはシンガポールリージョンに適用されます。

HTTP 呼び出し

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

ステップ 1:タスクを作成してタスク ID を取得する

シンガポールリージョン: POST https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/services/aigc/video-generation/video-synthesis {WorkspaceId} を実際のワークスペース ID に置き換えてください。
  • タスクの作成後、返された 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 (必須)モデル名です。モデルの出力仕様については、モデル一覧を参照してください。有効な値:
  • pixverse/pixverse-v6-r2v
input object (必須)参照画像とプロンプトを含む基本入力情報です。

プロパティ

prompt string (必須)テキストプロンプトです。生成する動画に含めたい要素や視覚的な特徴を説明します。中国語と英語に対応しています。中国語の文字と英字はいずれも 1 文字として数えます。文字エンコーディングは UTF-8 です。上限を超える文字は自動的に切り詰められます。
  • pixverse/pixverse-v6-r2v: 最大 2,048 文字です。
画像の参照方法:media パラメーターで参照画像を渡した場合、プロンプト内で @ref_name を使用してその画像を直接参照できます。
  • media で設定する ref_name は、同一リクエスト内でグローバルに一意である必要があり、プロンプト内の参照と 1 対 1 で対応している必要があります。
  • 書式ルール:@ref_name の後には区切りとして半角スペースを入れる必要があります。
例:
  • 通常のプロンプト:窓際の椅子に座った男性がギターを持ち、コーヒーショップの横で心安らぐアメリカのカントリーフォーク曲を演奏している。
  • 参照付きのプロンプト:@man が窓際の椅子に座り、@guitar を持って、@coffeeshop の横で心安らぐアメリカのカントリーフォーク曲を演奏している。
media array (必須)動画生成に必要な参照画像を指定するメディア素材のリストです。配列の各要素は、type フィールドと url フィールドを含むメディアオブジェクトです。

要素のプロパティ

type string (必須)メディア素材の種類です。固定値:
  • image_url: 画像の URL。
素材の数の制限:最大 7 枚の画像。url string (必須)参照画像の URL です。パブリックにアクセスできる必要があります。画像の制限:
  • 形式:JPG、PNG、WEBP。
  • 解像度:画像の幅と高さはいずれも 10,000 ピクセルを超えることはできません。
  • ファイルサイズ:最大 20 MB。
ref_name string (任意)参照画像内の被写体の名前識別子です。プロンプト内で @ref_name として画像を参照するために使用します。最大 30 文字です。
parameters object (必須)動画の解像度、長さ、音声を生成するかどうかなど、動画生成のパラメーターです。

プロパティ

size string (必須)生成する動画の解像度です。width*height の形式でピクセル単位で指定します。次の表に、解像度区分ごとの有効な値を示します。

pixverse/pixverse-v6-r2v モデル

解像度区分

アスペクト比

size の値(width*height)

360P

16:9

640*360

4:3

640*480

1:1

640*640

3:4

480*640

9:16

360*640

3:2

640*432

2:3

432*640

21:9

640*288

540P

16:9

1024*576

4:3

1024*768

1:1

1024*1024

3:4

768*1024

9:16

576*1024

3:2

1024*688

2:3

688*1024

21:9

1024*448

720P

16:9

1280*720

4:3

1108*832

1:1

960*960

3:4

832*1108

9:16

720*1280

3:2

1200*800

2:3

800*1200

21:9

1280*560

1080P

16:9

1920*1080

4:3

1664*1248

1:1

1440*1440

3:4

1248*1664

9:16

1080*1920

3:2

1776*1184

2:3

1184*1776

21:9

1920*832

例:1280*720。duration integer (必須)
duration パラメーターは料金に直接影響します。呼び出し前に PixVerse - 参照画像から動画生成の料金を確認してください。
生成する動画の長さ(秒)です。
  • pixverse/pixverse-v6-r2v: [1, 15] の範囲の整数です。
例:5。audio boolean (任意)
audio パラメーターは料金に直接影響します。呼び出し前に PixVerse - 参照画像から動画生成の料金を確認してください。
音声付き動画を生成するかどうかを指定します。有効にすると、モデルは動画の内容に合った BGM や効果音を自動的に生成します。
  • false: デフォルト値。無音動画を出力します。
  • true: 音声付き動画を出力します。
例:false。watermark boolean (任意)ウォーターマークを追加するかどうかを指定します。動画の右下に、固定テキスト「AI Generated」のウォーターマークが表示されます。
  • false: デフォルト値。ウォーターマークを追加しません。
  • true: ウォーターマークを追加します。
例:false。seed integer (任意)乱数シードは [0, 2147483647] の範囲の整数である必要があります。省略するとランダムなシードが生成されます。固定シードを使用すると再現性が向上します。モデルの生成は確率的であるため、同じシードでも同一の結果は保証されません。
  • 参照画像から動画生成
  • Python SDK
  • 参照画像から動画生成(ref_name を使用)
media で参照画像を渡し、size と duration を設定して動画の解像度と長さを制御します。
# {WorkspaceId} を実際のワークスペース ID に置き換えてください。
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": "pixverse/pixverse-v6-r2v",
    "input": {
        "media": [
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260320/knsple/wan-r2v-role-frame.jpg"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png"
            },
            {
                "type": "image_url",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png"
            }
        ],
        "prompt": "A man sits on a chair by the window, holding a guitar, playing a soothing American country folk song next to a coffee shop"
    },
    "parameters": {
        "size": "1280*720",
        "duration": 5,
        "audio": false,
        "watermark": true
    }
}'

レスポンスパラメーター

output objectタスクの出力情報です。

プロパティ

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

列挙値

  • PENDING:タスクは待機中です。
  • RUNNING:タスクは処理中です。
  • SUCCEEDED:タスクは成功しました。
  • FAILED:タスクは失敗しました。
  • CANCELED:タスクはキャンセルされました。
  • UNKNOWN:タスクが存在しないか、状態が不明です。
request_id string追跡とトラブルシューティングに使用する一意のリクエスト識別子です。code stringエラーコードです。リクエストが失敗した場合のみ返されます。エラーコードを参照してください。message string詳細なエラーメッセージです。リクエストが失敗した場合のみ返されます。エラーコードを参照してください。
  • 成功レスポンス
  • エラーレスポンス
タスクの状態と結果を照会できるよう、task_id を保存してください。
{
    "output": {
        "task_status": "PENDING",
        "task_id": "0385dc79-5ff8-4d82-bcb6-xxxxxx"
    },
    "request_id": "4909100c-7b5a-9f92-bfe5-xxxxxx"
}

ステップ 2:タスク ID で結果を照会する

シンガポールリージョン: GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id}
  • ポーリングの推奨事項: 動画の生成には数分かかる場合があります。ポーリング方式を使用し、15 秒ごとなど適切な間隔で結果をポーリングしてください。
  • タスク状態の遷移: PENDING(待機中)→ RUNNING(処理中)→ SUCCEEDED(成功)/ FAILED(失敗)。
  • タスク ID の有効期間: task_id は24 時間有効です。有効期限が切れると照会は失敗し、API はタスク状態 UNKNOWN を返します。
  • RPS 制限: 照会エンドポイントのデフォルトの制限は 20 RPS です。高頻度の照会やイベント通知には、非同期タスクのコールバックを設定してください。
  • その他の操作: 一括照会、タスクのキャンセルなどの操作については、非同期タスクの管理を参照してください。

リクエストパラメーター

リクエストヘッダー
Authorization string (必須)Model Studio の API キーでリクエストを認証します。例:Bearer sk-xxxx。
パスパラメーター
task_id string (必須)タスクの ID です。
  • タスク結果の照会
{task_id} を前の API 呼び出しで返された task_id の値に置き換えます。task_id は 24 時間以内の照会に使用できます。{WorkspaceId} を実際のワークスペース ID に置き換えてください。
curl -X GET https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1/tasks/{task_id} \
--header "Authorization: Bearer $DASHSCOPE_API_KEY"

レスポンスパラメーター

output objectタスクの出力情報です。

プロパティ

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

列挙値

  • PENDING:タスクは待機中です。
  • RUNNING:タスクは処理中です。
  • SUCCEEDED:タスクは成功しました。
  • FAILED:タスクは失敗しました。
  • CANCELED:タスクはキャンセルされました。
  • UNKNOWN:タスクが存在しないか、状態が不明です。
ポーリング中の状態遷移:
  • PENDING(待機中)→ RUNNING(処理中)→ SUCCEEDED(成功)/ FAILED(失敗)。
  • 最初の照会時の状態は通常 PENDING(待機中)または RUNNING(処理中)です。
  • 状態が SUCCEEDED になると、レスポンスに生成された動画の URL が含まれます。
  • 状態が FAILED の場合は、エラーメッセージを確認して再試行してください。
  • 状態が CANCELED の場合、タスクはキャンセルされています。続行するには、タスクを再送信してください。
  • 状態が UNKNOWN の場合、タスクが存在しないか、状態が不明です。task_id が存在しない場合や、24 時間の有効期間を過ぎた場合に発生することがあります。
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_url string動画の URL です。task_status が SUCCEEDED の場合のみ返されます。動画の形式は MP4(H.264 エンコーディング)です。動画リンクは現在のところ有効期限がありませんが、長期保存には利用しないでください。速やかにダウンロードしてください。orig_prompt string入力された元のプロンプトです。リクエストパラメーター prompt に対応します。code stringエラーコードです。リクエストが失敗した場合のみ返されます。エラーコードを参照してください。message string詳細なエラーメッセージです。リクエストが失敗した場合のみ返されます。エラーコードを参照してください。
usage object出力の使用量統計です。成功したタスクのみが集計対象です。

プロパティ

duration integer生成された動画の合計時間です。課金に使用されます。size string生成された動画の解像度です。fps integer生成された動画のフレームレートです。SR string生成された動画の解像度区分です。audio boolean生成された動画に音声が含まれるかどうかを示します。video_count integer生成された動画の数です。1 に固定されています。
request_id string追跡とトラブルシューティングに使用する一意のリクエスト識別子です。
  • タスク成功
  • タスク失敗
  • タスク照会の有効期限切れ
{
    "request_id": "35137489-2862-96cb-b6f2-xxxxxx",
    "output": {
        "task_id": "1469cfc3-3004-4d9e-ab10-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2026-03-10 15:03:25.848",
        "scheduled_time": "2026-03-10 15:03:25.884",
        "end_time": "2026-03-10 15:04:05.882",
        "orig_prompt": "A man sits on a chair by the window, holding a guitar, playing a soothing American country folk song next to a coffee shop",
        "video_url": "https://media.pixverseai.cn/xxxx.mp4"
    },
    "usage": {
        "duration": 5,
        "size": "1280*720",
        "fps": 24,
        "video_count": 1,
        "audio": false,
        "SR": "720"
    }
}

エラーコード

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

よくある質問

Q:プロンプトの効果が良くない場合、どのように結果を最適化できますか。

A:代替手段として @ref_name を使用してみてください。
  • デフォルトの方法:プロンプトをそのまま使用します。モデルが参照画像の内容をグローバルに自動解析するため、一般的なシナリオのほとんどに対応できます。
  • 代替の方法:生成結果が期待と異なる場合は、プロンプト内で @ref_name を使用して参照画像を指定し、結果を改善します。

Q:ref_name はどのように使用しますか。

A:ref_name は、参照画像とプロンプトを関連付けます。media 配列内の画像に ref_name を設定すると、プロンプト内で @ref_name 構文を使用して、その参照画像の対応する被写体を参照できます。
  • たとえば、media で "ref_name": "kitten" を設定した場合は、プロンプト内で @kitten を使用してその被写体を参照します。注意:@kitten の後には半角スペースを入れる必要があります。
  • 例:@kitten と @puppy が芝生の上で遊んでいる。