Skip to main content
萬相

萬相2.7-圖生視頻API參考

萬相2.7-圖生視頻模型全新升級,支援 多模態輸入 (文本/映像/音頻/視頻),可完成 首幀生視頻、首尾幀生視頻、視頻續寫 三大任務。

相關文檔使用指南
全新推出的圖生視頻 API(wan2.7模型)支援上述三大任務,推薦優先選用圖生視頻-基於首幀(wan2.6及早期模型)僅支援首幀生視頻。

適用範圍

為確保調用成功,請務必保證模型、endpoint URL 和 API Key 均屬於同一地區。跨地區調用將會失敗。
本文的範例程式碼適用於新加坡地區
阿里雲百鍊為華北2(北京)、新加坡地區推出了業務空間專屬網域名稱,能夠為推理請求提供卓越的效能和更高的穩定性,建議遷移至新網域名稱:
  • 華北2(北京)地區:從 https://dashscope.aliyuncs.com 遷移至 https://{WorkspaceId}.cn-beijing.maas.aliyuncs.com
  • 新加坡地區:從 https://dashscope-intl.aliyuncs.com 遷移至 https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com
其中 {WorkspaceId} 為您的業務空間 ID,可在阿里雲百鍊控制台的業務空間詳情頁面查看。現有網域名稱仍可正常使用。

HTTP調用

此介面為圖生視頻新版協議,僅支援wan2.7模型
圖生視頻任務耗時較長(通常為1-5分鐘),API採用非同步呼叫的方式。整個流程包含 “建立任務 -> 輪詢擷取” 兩個核心步驟,具體如下:

步驟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

請求參數

Content-Typestring(必選)請求內容類型。此參數必須設定為application/jsonAuthorizationstring(必選)請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值:Bearer sk-xxxx。X-DashScope-Asyncstring(必選)非同步處理配置參數。HTTP請求只支援非同步,必須設定為enable
缺少此要求標頭將報錯:“current user api does not support synchronous calls”。
請求體(Request Body)
model string (必選)模型名稱。模型列表與價格詳見模型價格樣本值:wan2.7-i2v-2026-04-25。input object (必選)輸入的基本資料,如提示詞等。

屬性

prompt string (可選)文本提示詞。用來描述產生視頻中期望包含的元素和視覺特點。支援中英文,長度不超過5000個字元。每個漢字/字母佔一個字元,超過部分會自動截斷。樣本值:一隻小貓在草地上奔跑。提示詞提示詳見文生視頻/圖生視頻Prompt指南negative_prompt string (可選)反向提示詞,用來描述不希望在視頻畫面中看到的內容,可以對視頻畫面進行限制。支援中英文,長度不超過500個字元,超過部分會自動截斷。樣本值:低解析度、錯誤、最差品質、低品質、殘缺、多餘的手指、比例不良等。media array (必選)媒體素材列表,用於指定視頻產生所需的參考素材(映像、音頻和視頻)。數組的每個元素為一個媒體對象,包含 typeurl 欄位。

素材組合

僅支援以下特定的素材組合,非法組合將報錯。
  • 首幀生視頻
    • 首幀:first_frame
    • 首幀+音頻:first_frame+driving_audio
  • 首尾幀生視頻
    • 首幀+尾幀:first_frame+last_frame
    • 首幀+尾幀+音頻:first_frame+last_frame+driving_audio
  • 視頻續寫
    • 首段視頻續寫:first_clip
    • 首段視頻+尾幀續寫:first_clip+last_frame

屬性

type string (必選)媒體素材類型。可選值為:
  • first_frame:首幀。
  • last_frame:尾幀。
  • driving_audio:驅動音頻。
  • first_clip:首視頻片段。
使用限制:每種 typemedia 數組中最多出現一次(例如:不可同時傳入兩個 first_frame)。url string (必選)媒體素材URL。素材包括映像、音頻和視頻。

傳入映像(type=first_frame或last_frame)

首幀或尾幀URL,或 Base 64 編碼資料。目前支援首幀生視頻、首尾幀生視頻。映像限制:
  • 格式:JPEG、JPG、PNG(不支援透明通道)、BMP、WEBP。
  • 解析度:寬和高的範圍為[240, 8000]像素。
  • 寬高比:1:8~8:1。
  • 檔案大小:不超過20MB。
支援輸入的格式:
  1. 公網URL:
  2. Base 64 編碼映像後的字串:
    • 資料格式:data:{MIME_type};base64,{base64_data}
    • 樣本值:data:image/png;base64,GDU7MtCZzEbTbmRZ......(樣本已截斷,僅做示範)。
      格式: data:{MIME_type};base64,{base64_data} 。
      • {base64_data}:影像檔經過 Base 64 編碼後的字串。
      • {MIME_type}:映像的媒體類型,需與檔案格式對應。

      映像格式

      MIME Type

      JPEG

      image/jpeg

      JPG

      image/jpeg

      PNG

      image/png

      BMP

      image/bmp

      WEBP

      image/webp

傳入音頻(type=driving_audio)

音頻檔案的 URL。
  • 傳入音頻:模型將以該音頻為驅動源產生視頻(如口型同步、動作卡點等)。
  • 未傳入音頻:模型將根據視頻畫面內容,自動產生匹配的背景音樂或音效。
音頻限制:
  • 格式:wav、mp3。
  • 時間長度:2~30s。
  • 檔案大小:不超過15MB。
  • 截斷處理:若音頻長度超過 duration 值(如5秒),自動截取前5秒,其餘部分丟棄。若音頻長度不足視頻時間長度,超出音頻長度部分為無聲視頻。例如,音頻為3秒,視頻時間長度為5秒,輸出視頻前3秒有聲,後2秒無聲。
支援輸入的格式:
  1. 公網URL:

傳入的視訊(type=first_clip)

視頻檔案的 URL。模型將基於該視頻內容進行續寫產生,續寫時間長度的上限由 duration 參數控制。
例如:當duration=15時,輸入視頻 3 秒,則模型續寫產生 12 秒,最終輸出視頻總時間長度 15 秒, 按 15 秒計費。
視頻限制:
  • 格式:mp4、mov。
  • 時間長度:2~10s。
  • 解析度:寬和高的範圍為[240, 4096]像素。
  • 寬高比:1:8~8:1。
  • 檔案大小:不超過100MB。
支援輸入的格式:
  1. 公網URL:
parameters object (可選)視頻處理參數,如設定視頻解析度、設定視頻時間長度、開啟prompt智能改寫、添加浮水印等。

屬性

resolution string (可選)
resolution直接影響費用,請在調用前確認模型價格
指定產生的視頻解析度檔位,用於控制視頻的清晰度(總像素)。模型根據選擇的解析度檔位,自動縮放至相近總像素。視頻寬高比盡量與輸入素材(首幀或首段視頻)保持一致,詳見常見問題可選值:
  • 720P
  • 1080P(預設值)
duration integer (可選)
duration直接影響費用,按秒計費,請在調用前確認模型價格
產生視頻的時間長度,單位為秒。取值為[2, 15]之間的整數。預設值為5。prompt_extendboolean (可選)是否開啟prompt智能改寫。開啟後使用大模型對輸入prompt進行智能改寫。對於較短的prompt產生效果提升明顯,但會增加耗時。
  • true:預設值,開啟智能改寫。
  • false:不開啟智能改寫。
watermark boolean (可選)是否添加浮水印標識,浮水印位於視頻右下角,文案固定為“AI產生”。
  • false:預設值,不添加浮水印。
  • true:添加浮水印。
seedinteger(可選)隨機數種子,取值範圍為[0, 2147483647]未指定時,系統自動產生隨機種子。若需提升產生結果的可複現性,建議固定seed值。請注意,由於模型產生具有機率性,即使使用相同 seed,也不能保證每次產生結果完全一致。
  • 首幀生視頻
  • 首尾幀生視頻
  • 視頻續寫
基於首幀映像和音頻產生視頻。

# 以下為新加坡地區URL,調用時請將 {WorkspaceId} 替換為真實的業務空間ID,各地區的URL不同。
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": "wan2.7-i2v-2026-04-25",
    "input": {
        "prompt": "一幅都市奇幻藝術的情境。一個充滿動感的塗鴉藝術角色。一個由噴漆所畫成的少年,正從一面混凝土牆上活過來。他一邊用極快的語速演唱一首英文rap,一邊擺著一個經典的、充滿活力的饒舌歌手姿勢。情境設定在夜晚一個充滿都市感的鐵路橋下。燈光來自一盞孤零零的街燈,營造齣電影般的氛圍,充滿高能量和驚人的細節。視頻的音頻部分完全由rap構成,沒有其他對話或雜音。",
        "media": [
            {
                "type": "first_frame",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
            },
            {
                "type": "driving_audio",
                "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/ozwpvi/rap.mp3"

            }
        ]
    },
    "parameters": {
        "resolution": "720P",
        "duration": 10,
        "prompt_extend": true,
        "watermark": true
    }
}'

響應參數

output object任務輸出資訊。

屬性

task_id string任務ID。查詢有效期間24小時。task_status string任務狀態。

枚舉值

  • PENDING:任務排隊中
  • RUNNING:任務處理中
  • SUCCEEDED:任務執行成功
  • FAILED:任務執行失敗
  • CANCELED:任務已取消
  • UNKNOWN:任務不存在或狀態未知
request_idstring請求唯一標識。可用於請求明細溯源和問題排查。codestring請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤碼messagestring請求失敗的詳細資料。請求成功時不會返回此參數,詳情請參見錯誤碼
  • 成功響應
  • 異常響應
請儲存 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}
調用時請將{WorkspaceId}替換為真實的業務空間ID
  • 輪詢建議:視頻產生過程約需數分鐘,建議採用輪詢機制,並設定合理的查詢間隔(如 15 秒)來擷取結果。
  • 任務狀態流轉:PENDING(排隊中)→ RUNNING(處理中)→ SUCCEEDED(成功)/ FAILED(失敗)。
  • 結果連結:任務成功後返回視頻連結,有效期間為 24 小時。建議在擷取連結後立即下載並轉存至永久儲存(如阿里雲 OSS)。
  • task_id 有效期間24小時,逾時後將無法查詢結果,介面將返回任務狀態為UNKNOWN

請求參數

要求標頭(Headers)
Authorizationstring(必選)請求身份認證。介面使用阿里雲百鍊API Key進行身份認證。樣本值:Bearer sk-xxxx。
URL路徑參數(Path parameters)
task_id string(必選)任務ID。
  • 查詢任務結果
{task_id}完整替換為上一步介面返回的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"

響應參數

outputobject任務輸出資訊。

屬性

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任務提交時間。時區為UTC+8,格式為 YYYY-MM-DD HH:mm:ss.SSS。scheduled_time string任務執行時間。時區為UTC+8,格式為 YYYY-MM-DD HH:mm:ss.SSS。end_time string任務完成時間。時區為UTC+8,格式為 YYYY-MM-DD HH:mm:ss.SSS。video_urlstring視頻URL。僅在 task_status 為 SUCCEEDED 時返回。連結有效期間24小時,可通過此URL下載視頻。視頻格式為MP4(H.264 編碼)。orig_prompt string原始輸入的prompt,對應請求參數promptcodestring請求失敗的錯誤碼。請求成功時不會返回此參數,詳情請參見錯誤碼messagestring請求失敗的詳細資料。請求成功時不會返回此參數,詳情請參見錯誤碼
usage object輸出資訊統計,只對成功的結果計數。

屬性

input_video_duration integer輸入的視頻的時間長度,單位秒。output_video_duration integer輸出視頻的時間長度,單位秒。duration integer總的視頻時間長度,用於計費。SR integer輸出視頻的解析度檔位。樣本值:720。video_count integer輸出視頻的數量。固定為1。
request_idstring請求唯一標識。可用於請求明細溯源和問題排查。
  • 任務執行成功
  • 任務執行失敗
  • 任務查詢到期
視頻URL僅保留24小時,逾時後會被自動清除,請及時儲存產生的視頻。
{
    "request_id": "2ca1c497-f9e0-449d-9a3f-xxxxxx",
    "output": {
        "task_id": "af6efbc0-4bef-4194-8246-xxxxxx",
        "task_status": "SUCCEEDED",
        "submit_time": "2025-09-25 11:07:28.590",
        "scheduled_time": "2025-09-25 11:07:35.349",
        "end_time": "2025-09-25 11:17:11.650",
        "orig_prompt": "一幅都市奇幻藝術的情境。一個充滿動感的塗鴉藝術角色。一個由噴漆所畫成的少年,正從一面混凝土牆上活過來。他一邊用極快的語速演唱一首英文rap,一邊擺著一個經典的、充滿活力的饒舌歌手姿勢。情境設定在夜晚一個充滿都市感的鐵路橋下。燈光來自一盞孤零零的街燈,營造齣電影般的氛圍,充滿高能量和驚人的細節。視頻的音頻部分完全由他的rap構成,沒有其他對話或雜音。",
        "video_url": "https://dashscope-result-sh.oss-cn-shanghai.aliyuncs.com/xxx.mp4?Expires=xxx"
    },
    "usage": {
        "duration": 15,
        "input_video_duration": 0,
        "output_video_duration": 15,
        "video_count": 1,
        "SR": 720
    }
}

DashScope SDK調用

SDK 的參數命名與HTTP介面基本一致,參數結構根據語言特性進行封裝。 由於圖生視頻任務耗時較長(通常為1-5分鐘),SDK 在底層封裝了 HTTP 非同步呼叫流程,支援同步、非同步兩種調用方式。
具體耗時受限於排隊任務數和服務執行情況,請在擷取結果時耐心等待。

Python SDK調用

請確保 DashScope Python SDK 版本不低於1.25.16,再運行以下代碼。若版本過低,可能會觸發 "url error, please check url!" 等錯誤。請參考安裝SDK進行更新。
根據模型所在地區設定 dashscope.base_http_api_url:
  • 新加坡
  • 北京
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'
調用時請將{WorkspaceId}替換為真實的業務空間ID
  • 同步調用
  • 非同步呼叫
請求樣本
# -*- coding: utf-8 -*-
from http import HTTPStatus
from dashscope import VideoSynthesis
import dashscope
import os

# 以下為新加坡地區URL,調用時請將 {WorkspaceId} 替換為真實的業務空間ID,各地區的URL不同。
dashscope.base_http_api_url = 'https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1'

# 若沒有配置環境變數,請用百鍊API Key將下行替換為:api_key="sk-xxx"
# 各地區的API Key不同。擷取API Key:https://www.alibabacloud.com/help/en/model-studio/get-api-key
api_key = os.getenv("DASHSCOPE_API_KEY")

media = [
    {
        "type": "first_frame",
        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/wpimhv/rap.png"
    },
    {
        "type": "driving_audio",
        "url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250925/ozwpvi/rap.mp3"
    }
]

def sample_sync_call():
    print('----sync call, please wait a moment----')
    rsp = VideoSynthesis.call(
        api_key=api_key,
        model="wan2.7-i2v-2026-04-25",
        media=media,
        resolution="720P",
        duration=10,
        watermark=True,
        prompt="一幅都市奇幻藝術的情境。一個充滿動感的塗鴉藝術角色。一個由噴漆所畫成的少年,正從一面混凝土牆上活過來。他一邊用極快的語速演唱一首英文rap,一邊擺著一個經典的、充滿活力的饒舌歌手姿勢。情境設定在夜晚一個充滿都市感的鐵路橋下。燈光來自一盞孤零零的街燈,營造齣電影般的氛圍,充滿高能量和驚人的細節。視頻的音頻部分完全由rap構成,沒有其他對話或雜音。",
    )
    if rsp.status_code == HTTPStatus.OK:
        print(rsp.output.video_url)
    else:
        print('Failed, status_code: %s, code: %s, message: %s' %
              (rsp.status_code, rsp.code, rsp.message))

if __name__ == '__main__':
    sample_sync_call()
響應樣本
video_url 有效期間24小時,請及時下載視頻。
{
    "status_code": 200,
    "request_id": "ac5faf37-ddfa-9720-a0c5-xxxxxx",
    "code": null,
    "message": "",
    "output": {
        "task_id": "b97c6d86-ad73-4bb7-80ff-xxxxxx",
        "task_status": "SUCCEEDED",
        "video_url": "https://dashscope-a717.oss-accelerate.aliyuncs.com/xxx.mp4?Expires=xxx",
        "submit_time": "2026-04-13 10:45:47.597",
        "scheduled_time": "2026-04-13 10:45:56.342",
        "end_time": "2026-04-13 10:47:26.273",
        "orig_prompt": "一幅都市奇幻藝術的情境。一個充滿動感的塗鴉藝術角色。一個由噴漆所畫成的少年,正從一面混凝土牆上活過來。他一邊用極快的語速演唱一首英文rap,一邊擺著一個經典的、充滿活力的饒舌歌手姿勢。情境設定在夜晚一個充滿都市感的鐵路橋下。燈光來自一盞孤零零的街燈,營造齣電影般的氛圍,充滿高能量和驚人的細節。視頻的音頻部分完全由rap構成,沒有其他對話或雜音。"
    },
    "usage": {
        "video_count": 1,
        "video_duration": 0,
        "video_ratio": "",
        "duration": 10,
        "input_video_duration": 0,
        "output_video_duration": 10,
        "SR": 720
    }
}

Java SDK調用

請確保 DashScope Java SDK 版本不低於2.22.14,再運行以下代碼。若版本過低,可能會觸發 "url error, please check url!" 等錯誤。請參考安裝SDK進行更新。
根據模型所在地區設定 Constants.baseHttpApiUrl:
  • 新加坡
  • 北京
Constants.baseHttpApiUrl = "https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/api/v1"
調用時請將{WorkspaceId}替換為真實的業務空間ID
  • 同步調用
  • 非同步呼叫
同步調用會阻塞等待,直到視頻產生完成並返回結果。
請求樣本

錯誤碼

如果模型調用失敗並返回報錯資訊,請參見錯誤碼進行解決。

常見問題

Q:如何產生特定寬高比(如3:4)的視頻?

A: 輸出視頻的寬高比由 輸入素材(首幀映像或首視頻片段)決定,但無法保證嚴格等於輸入比例(如精確 3:4),實際輸出會存在微小偏差。 下面以“輸入首幀映像”為例說明具體邏輯:
  • 為什麼會有偏差?
    • 執行邏輯:以輸入映像的比例為基準比例參考,結合 resolution 檔位的目標總像素,且視頻長寬必須為 16 的倍數(視頻編碼規範),系統會自動微調至最接近的合法解析度。
    • 計算樣本:輸入首幀映像750×1000(寬高比 3:4 = 0.75),並設定 resolution = "720P"(目標總像素約 92 萬),實際輸出視頻的解析度為816×1104(寬高比 ≈ 0.739,總像素約90萬)。
  • 實踐建議
    • 輸入控制:盡量使用與目標比例一致的首幀或首視頻片段作為輸入。
    • 後期處理:如果您對比例有嚴格要求,建議在視頻產生後,使用編輯工具進行簡單的裁剪或黑邊填充。

Q:如何擷取視頻儲存的訪問網域名稱白名單?

A: 模型產生的視頻儲存於阿里雲OSS,API將返回一個臨時的公網URL。若需要對該下載地址進行防火牆白名單配置,請注意:由於底層儲存會根據業務情況進行動態變更,為避免到期資訊影響訪問,文檔不提供固定的OSS網域名稱白名單。如有安全管控需求,請聯絡客戶經理擷取最新OSS網域名稱列表。