创建视频生成请求

快速开始

如需分析已有视频的画面和音轨，请参阅 Gemini 视频与音轨理解。视频生成是异步接口，一次完整调用分三步：

步骤	请求	说明
1. 创建任务	`POST https://api.nonelinear.com.cn/v1/videos`	以表单（multipart/form-data）提交，返回任务 `id`
2. 查询状态	`GET https://api.nonelinear.com.cn/v1/videos/{video_id}`	重复查询，直到 `status` 为 `succeeded` 或 `completed`
3. 获取视频	`GET https://api.nonelinear.com.cn/v1/videos/{video_id}/content`	响应 JSON 中的 `url` 即为视频下载地址

鉴权：请求头 Authorization: Bearer <你的 API Key>，在 API Key 页面获取。
切换模型：修改 model，并按模型参数调整 seconds、size 等参数。

本页示例从环境变量 NONELINEAR_API_KEY 读取 API Key，运行前先在终端设置：

export NONELINEAR_API_KEY="你的 API Key"

$env:NONELINEAR_API_KEY="你的 API Key"

cURL 示例使用 \ 换行，适用于 macOS / Linux 终端；Windows 用户可在 Git Bash 或 WSL 中运行，或直接使用 Python 示例。 Python 示例使用 OpenAI SDK（pip install openai），都使用以下方式创建客户端：

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.nonelinear.com.cn/v1",
    api_key=os.environ["NONELINEAR_API_KEY"],
)

1. 创建任务

curl -sS https://api.nonelinear.com.cn/v1/videos \
  -H "Authorization: Bearer $NONELINEAR_API_KEY" \
  -F "model=wan2.7-t2v-720p" \
  -F "prompt=A cat playing a piano on stage" \
  -F "seconds=5"

video = client.videos.create(
    model="wan2.7-t2v-720p",
    prompt="A cat playing a piano on stage",
    seconds="5",
    extra_headers={"Content-Type": "multipart/form-data"},
)
print(video.id)

记下响应中的 id，后两步都要用到。

2. 查询状态

将 VIDEO_ID 替换为创建任务时返回的完整 id，后续查询和获取视频都使用这个值。不要用查询响应里的 id 覆盖它：部分模型在查询时返回的 ID 不包含模型前缀。生成需要一段时间，请间隔一段时间重复查询。不同模型的状态值大小写可能不同；判断时先转为小写，再检查是否为 succeeded 或 completed。

curl -sS https://api.nonelinear.com.cn/v1/videos/VIDEO_ID \
  -H "Authorization: Bearer $NONELINEAR_API_KEY"

video = client.videos.retrieve("VIDEO_ID")
print(video.status)

3. 获取视频下载地址

任务完成后调用。响应 JSON 中的 url 即为视频下载地址。

curl -sS https://api.nonelinear.com.cn/v1/videos/VIDEO_ID/content \
  -H "Authorization: Bearer $NONELINEAR_API_KEY"

response = client.videos.download_content("VIDEO_ID")
print(response.json()["url"])

Python 完整示例：创建任务并等待完成

import os
import time
from openai import OpenAI

client = OpenAI(
    base_url="https://api.nonelinear.com.cn/v1",
    api_key=os.environ["NONELINEAR_API_KEY"],
)

video = client.videos.create(
    model="wan2.7-t2v-720p",
    prompt="A cat playing a piano on stage",
    seconds="5",
    extra_headers={"Content-Type": "multipart/form-data"},
)
task_id = video.id  # 保留创建时的完整 ID，不能用查询响应里的 ID 替换
print("任务 ID：", task_id)

for _ in range(90):  # 每 10 秒查询一次，最多等待约 15 分钟
    video = client.videos.retrieve(task_id)
    status = (video.status or "").lower()
    print("当前状态：", video.status)
    if video.error:
        raise RuntimeError(f"视频生成失败：{video.error}")
    if status in ("succeeded", "completed"):
        break
    time.sleep(10)
else:
    raise TimeoutError(f"等待超时，可稍后用任务 ID {task_id} 继续查询")

response = client.videos.download_content(task_id)
print("视频下载地址：", response.json()["url"])

返回结果

以下为 wan2.7-t2v-720p 的实际 HTTP 响应，任务 ID 已替换为示例值。创建任务与查询状态的响应字段不同，不应按同一个固定结构读取。 创建任务：本次请求只返回 id，不包含状态或进度。

{
  "id": "wan2.7-t2v-720p----00000000-0000-4000-8000-000000000000"
}

查询状态：生成中的响应如下。

{
  "err_code": null,
  "error": null,
  "id": "00000000-0000-4000-8000-000000000000",
  "model": "wan2.7-t2v-720p",
  "seconds": null,
  "size": null,
  "status": "RUNNING"
}

同一任务完成后，查询响应变为：

{
  "err_code": null,
  "error": null,
  "id": "00000000-0000-4000-8000-000000000000",
  "model": "wan2.7-t2v-720p",
  "seconds": 5,
  "size": 720,
  "status": "completed"
}

字段	说明
创建响应的 `id`	后续请求使用的完整任务 ID，需原样保存，包括模型前缀。
查询响应的 `id`	本例只返回任务标识部分，不能替换创建时的完整 ID。
`status`	本次任务生成中为 `RUNNING`，完成后为 `completed`，注意大小写不同。
`model`	本次任务使用的模型。
`err_code`、`error`	错误码与错误信息；本次成功任务的响应均为 `null`。
`seconds`	本例生成中为 `null`，完成后为整数 `5`，单位为秒。
`size`	本例生成中为 `null`，完成后为整数 `720`，不是宽高字符串。

用 status 判断任务是否完成。生成期间 seconds、size 为空时，继续等待即可。 获取下载地址：任务完成后，使用创建时保存的完整 ID 请求 /v1/videos/{video_id}/content，返回 JSON 中的 url。下方地址为占位示例，请使用实际响应中的地址。

{
  "url": "https://example.com/generated-video.mp4"
}

模型参数

先找到所用模型，再按表中的写法原样传值，注意大小写，以及宽高之间用 x 还是 *。

参考图：“必须”表示该模型只能图生视频，创建任务时必须传入图片；“不支持”表示只能文生视频。
首尾帧、自定义音频：用法见调用示例中对应小节。
表中“不支持”的参数，调用时省略即可。
可以通过右侧目录按系列跳转，或按 Ctrl+F / ⌘+F 搜索模型 ID。

Python SDK 参数放在哪里？ model、prompt、seconds、size、input_reference 直接作为关键字传入；aspect_ratio、last_image_url、audio_url 等其他参数放进 extra_body={...}。

OpenAI Sora

模型 ID	参考图	首尾帧	自定义音频	`seconds`	`size`	`aspect_ratio`
`sora-2`	支持	不支持	不支持	`4`（默认）、`8`、`12`	`720x1280`（默认）、`1280x720`、`1024x1792`、`1792x1024`	不支持

豆包 Seedance

模型 ID	参考图	首尾帧	自定义音频	`seconds`	`size`
`Doubao-Seedance-1.5-pro` `Doubao-Seedance-1.5-pro-noaudio`	支持	支持	不支持	4~12 的整数，默认 `5`	`480P`、`720P`、`1080P`
`Doubao-Seedance-1.0-pro-fast`	支持	不支持	不支持	2~12 的整数，默认 `5`	`480P`、`720P`、`1080P`
`Doubao-Seedance-1.0-pro`	支持	支持	不支持	2~12 的整数，默认 `5`	`480P`、`720P`、`1080P`
`Doubao-Seedance-1.0-lite-i2v`	必须	支持	不支持	2~12 的整数，默认 `5`	`480P`、`720P`、`1080P`
`Doubao-Seedance-1.0-lite-t2v`	不支持	不支持	不支持	2~12 的整数，默认 `5`	`480P`、`720P`、`1080P`

aspect_ratio 可选 16:9、4:3、1:1、3:4、9:16、21:9、adaptive，其中 adaptive 有以下限制：

Doubao-Seedance-1.0-pro-fast、Doubao-Seedance-1.0-pro：文生视频场景不支持 adaptive；
Doubao-Seedance-1.0-lite-i2v、Doubao-Seedance-1.0-lite-t2v：参考图和文生视频场景不支持 adaptive。

Google Veo

模型 ID	参考图	首尾帧	自定义音频	`seconds`	`size`
`veo-3.1-generate-preview` `veo-3.1-fast-generate-preview`	支持	支持	不支持	`4`、`6`、`8`，默认 `8`	`720p`（默认）、`1080p`
`veo-3.1-generate-preview-4k` `veo-3.1-fast-generate-preview-4k`	支持	支持	不支持	`8`	`4k`
`veo-3.0-generate-001` `veo-3.0-fast-generate-001`	支持	不支持	不支持	`4`、`6`、`8`，默认 `8`	`720p`（默认）、`1080p`、`4k`
`veo-2.0-generate-001`	支持	不支持	不支持	`5`、`6`、`8`，默认 `8`	不支持

aspect_ratio 可选 16:9（默认）、9:16。
Veo 3.1 / 3.0 使用扩展、参考图片，或使用 1080p、4k 分辨率时，seconds 必须为 8。

Vidu

模型 ID	参考图	首尾帧	自定义音频	`seconds`	`size`
`viduq3-pro-1080p` `viduq3-turbo-1080p`	支持	支持	不支持	1~16 的整数，默认 `5`	`1080p`
`viduq3-pro-720p` `viduq3-turbo-720p`	支持	支持	不支持	1~16 的整数，默认 `5`	`720p`
`viduq3-pro-540p` `viduq3-turbo-540p`	支持	支持	不支持	1~16 的整数，默认 `5`	`540p`

aspect_ratio 可选 16:9（默认）、9:16、3:4、4:3、1:1。

可灵 Kling

模型 ID	参考图	首尾帧	自定义音频	`seconds`
`Kling-v3-omni-std` `Kling-v3-omni-std-sound` `Kling-v3-omni-std-ref-video` `Kling-v3-omni-pro` `Kling-v3-omni-pro-sound` `Kling-v3-omni-pro-ref-video` `Kling-V3-std` `Kling-V3-std-sound` `Kling-V3-pro` `Kling-V3-pro-sound`	支持	支持	不支持	3~15 的整数，默认 `5`
`kling-video-o1-std` `kling-video-o1-std-ref-video` `kling-video-o1-pro` `kling-video-o1-pro-ref-video`	支持	支持	不支持	3~10 的整数，默认 `5`；不传图片时只支持 `5`、`10`
`Kling-V2-6-pro`	支持	支持	不支持	`5`（默认）、`10`
`Kling-V2-6-std` `Kling-V2-6-pro-sound` `Kling-V2-6-pro-sound-voiceid` `Kling-V2-6-std-actioncontrol` `Kling-V2-6-pro-actioncontrol`	支持	不支持	不支持	`5`（默认）、`10`

本系列不支持 size。
aspect_ratio 可选 16:9（默认）、9:16、1:1。

阿里万相 Wan

快速开始使用的 wan2.7-t2v-720p 已验证可用 seconds="5"、不传 size 创建任务。以下参数表仍按各型号分别列出，不应直接套用到新版本。下表型号不支持 aspect_ratio。按任务分为以下几类。 文生视频：不支持传入图片。

模型 ID	自定义音频	`seconds`	`size`
`wan2.6-t2v-720p`	支持	2~15 的整数，默认 `5`	`1280720`（默认）、`7201280`、`960960`、`1088832`、`832*1088`
`wan2.6-t2v-1080p`	支持	2~15 的整数，默认 `5`	`19201080`（默认）、`10801920`、`14401440`、`16321248`、`1248*1632`
`wan2.5-t2v-preview-480p`	支持	`5`（默认）、`10`	`832480`（默认）、`480832`、`624*624`
`wan2.5-t2v-preview-720p`	支持	`5`（默认）、`10`	`1280720`（默认）、`7201280`、`960960`、`1088832`、`832*1088`
`wan2.5-t2v-preview-1080p`	支持	`5`（默认）、`10`	`19201080`（默认）、`10801920`、`14401440`、`16321248`、`1248*1632`
`wan2.2-t2v-plus-480p`	不支持	固定为 `5`，不支持修改	`832480`（默认）、`480832`、`624*624`
`wan2.2-t2v-plus-1080p`	不支持	固定为 `5`，不支持修改	`19201080`（默认）、`10801920`、`14401440`、`16321248`、`1248*1632`

图生视频：必须传入图片。

模型 ID	自定义音频	`seconds`	`size`
`wan2.6-i2v-flash-720p` `wan2.6-i2v-flash-720p-noaudio` `wan2.6-i2v-720p`	支持	2~15 的整数，默认 `5`	`720P`
`wan2.6-i2v-flash-1080p` `wan2.6-i2v-flash-1080p-noaudio` `wan2.6-i2v-1080p`	支持	2~15 的整数，默认 `5`	`1080P`
`wan2.5-i2v-preview-480p`	支持	`5`（默认）、`10`	`480P`
`wan2.5-i2v-preview-720p`	支持	`5`（默认）、`10`	`720P`
`wan2.5-i2v-preview-1080p`	支持	`5`（默认）、`10`	`1080P`
`wan2.2-i2v-plus-480p`	不支持	固定为 `5`，不支持修改	`480P`
`wan2.2-i2v-plus-1080p`	不支持	固定为 `5`，不支持修改	`1080P`

首尾帧：必须传入首帧图片，不支持自定义音频。

模型 ID	`seconds`	`size`
`wan2.2-kf2v-flash-480p`	固定为 `5`，不支持修改	`480P`
`wan2.2-kf2v-flash-720p`	固定为 `5`，不支持修改	`720P`
`wan2.2-kf2v-flash-1080p`	固定为 `5`，不支持修改	`1080P`

图生动作、视频换人：必须传入图片，并通过 video_url 传入参考视频（见图生动作、视频换人示例）。不支持 seconds、size 和自定义音频。

任务	模型 ID
图生动作	`wan2.2-animate-move-std`、`wan2.2-animate-move-pro`
视频换人	`wan2.2-animate-mix-std`、`wan2.2-animate-mix-pro`

指定多角色：支持传入参考视频和图片，不支持自定义音频。

模型 ID	`seconds`	`size`
`wan2.6-r2v-flash-720p` `wan2.6-r2v-flash-720p-noaudio` `wan2.6-r2v-720p`	2~10 的整数，默认 `5`	`1280720`（默认）、`7201280`、`960960`、`1088832`、`832*1088`
`wan2.6-r2v-flash-1080p` `wan2.6-r2v-flash-1080p-noaudio` `wan2.6-r2v-1080p`	2~10 的整数，默认 `5`	`19201080`（默认）、`10801920`、`14401440`、`16321248`、`1248*1632`

调用示例

以下示例只展示创建任务这一步，每段代码只创建一个任务；client 的创建方式见快速开始。拿到任务 id 后，按查询状态和获取视频下载地址获取结果。示例中的本地图片路径（如 cat.jpg）请替换为你自己的图片。

文生视频

video = client.videos.create(
    model="wan2.7-t2v-720p",
    prompt="A cat playing a piano on stage",
    seconds="5",
    extra_headers={"Content-Type": "multipart/form-data"},
)
print(video)

图生视频

通过 input_reference 上传本地图片。

from pathlib import Path

video = client.videos.create(
    model="sora-2",
    prompt="A cat playing a piano on stage",
    input_reference=Path("cat.jpg"),  # 本地图片路径
    extra_headers={"Content-Type": "multipart/form-data"},
)
print(video)

首尾帧

支持首尾帧的模型：

Doubao-Seedance-1.5-pro、Doubao-Seedance-1.5-pro-noaudio、Doubao-Seedance-1.0-pro、Doubao-Seedance-1.0-lite-i2v
veo-3.1-generate-preview、veo-3.1-generate-preview-4k、veo-3.1-fast-generate-preview、veo-3.1-fast-generate-preview-4k
viduq3-pro-1080p、viduq3-pro-720p、viduq3-pro-540p、viduq3-turbo-1080p、viduq3-turbo-720p、viduq3-turbo-540p
Kling-v3-omni-std、Kling-v3-omni-std-sound、Kling-v3-omni-std-ref-video、Kling-v3-omni-pro、Kling-v3-omni-pro-sound、Kling-v3-omni-pro-ref-video、Kling-V3-std、Kling-V3-std-sound、Kling-V3-pro、Kling-V3-pro-sound、kling-video-o1-std、kling-video-o1-std-ref-video、kling-video-o1-pro、kling-video-o1-pro-ref-video、Kling-V2-6-pro
wan2.2-kf2v-flash-480p、wan2.2-kf2v-flash-720p、wan2.2-kf2v-flash-1080p

以 wan2.2-kf2v-flash-720p 为例：首帧通过 input_reference 上传本地图片，尾帧通过 extra_body 中的 last_image_url 传入图片地址。

from pathlib import Path

video = client.videos.create(
    model="wan2.2-kf2v-flash-720p",
    prompt="写实风格，一只黑色小猫好奇地看向天空，镜头从平视逐渐上升，最后俯拍它的好奇的眼神。",
    input_reference=Path("first_frame_wan.png"),  # 首帧：本地图片路径
    extra_headers={"Content-Type": "multipart/form-data"},
    extra_body={"last_image_url": "https://wanx.alicdn.com/material/20250318/last_frame.png"},
)
print(video)

图生动作

支持的模型：wan2.2-animate-move-std、wan2.2-animate-move-pro。上传人物图片，并通过 video_url 传入参考视频，无需 prompt。

from pathlib import Path

video = client.videos.create(
    model="wan2.2-animate-move-std",  # 或 wan2.2-animate-move-pro
    prompt=None,
    input_reference=Path("move_input_image.jpeg"),  # 本地图片路径
    extra_headers={"Content-Type": "multipart/form-data"},
    extra_body={"video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/kaakcn/move_input_video.mp4"},
)
print(video)

视频换人

支持的模型：wan2.2-animate-mix-std、wan2.2-animate-mix-pro。上传人物图片，并通过 video_url 传入参考视频，无需 prompt。

from pathlib import Path

video = client.videos.create(
    model="wan2.2-animate-mix-std",  # 或 wan2.2-animate-mix-pro
    prompt=None,
    input_reference=Path("mix_input_image.jpeg"),  # 本地图片路径
    extra_headers={"Content-Type": "multipart/form-data"},
    extra_body={"video_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250919/wqefue/mix_input_video.mp4"},
)
print(video)

输入自定义音频

通过 extra_body 中的 audio_url 传入音频地址。支持的模型：

文生视频：wan2.6-t2v-720p、wan2.6-t2v-1080p、wan2.5-t2v-preview-480p、wan2.5-t2v-preview-720p、wan2.5-t2v-preview-1080p
图生视频（需同时传入图片）：wan2.6-i2v-flash-720p、wan2.6-i2v-flash-1080p、wan2.6-i2v-flash-1080p-noaudio、wan2.6-i2v-flash-720p-noaudio、wan2.6-i2v-720p、wan2.6-i2v-1080p、wan2.5-i2v-preview-480p、wan2.5-i2v-preview-720p、wan2.5-i2v-preview-1080p

video = client.videos.create(
    model="wan2.6-t2v-720p",
    prompt="一幅史诗级可爱的场景。一只小巧可爱的卡通小猫将军，身穿细节精致的金色盔甲，头戴一个稍大的头盔，勇敢地站在悬崖上。他骑着一匹虽小但英勇的战马，说：”青海长云暗雪山，孤城遥望玉门关。黄沙百战穿金甲，不破楼兰终不还。“。悬崖下方，一支由老鼠组成的、数量庞大、无穷无尽的军队正带着临时制作的武器向前冲锋。这是一个戏剧性的、大规模的战斗场景，灵感来自中国古代的战争史诗。远处的雪山上空，天空乌云密布。整体氛围是“可爱”与“霸气”的搞笑和史诗般的融合。",
    extra_headers={"Content-Type": "multipart/form-data"},
    extra_body={"audio_url": "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20250923/hbiayh/%E4%BB%8E%E5%86%9B%E8%A1%8C.mp3"},
)
print(video)

指定多角色

支持的模型：wan2.6-r2v-flash-720p、wan2.6-r2v-flash-1080p、wan2.6-r2v-flash-1080p-noaudio、wan2.6-r2v-flash-720p-noaudio、wan2.6-r2v-720p、wan2.6-r2v-1080p。通过 extra_body 中的 reference_urls 传入多个参考视频或图片地址，模型会从中提取角色形象与音色。数组顺序即角色顺序：第 1 个地址对应 prompt 中的 character1，第 2 个对应 character2，以此类推。每个参考文件只包含一个主体角色，例如 character1 为小女孩，character2 为闹钟。

video = client.videos.create(
    model="wan2.6-r2v-720p",
    prompt="Character2 坐在靠窗的椅子上，手持 character3，在 character4 旁演奏一首舒缓的美国乡村民谣。Character1 对Character2开口说道：“听起来不错”",
    extra_headers={"Content-Type": "multipart/form-data"},
    extra_body={
        "reference_urls": [
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/hfugmr/wan-r2v-role1.mp4",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qigswt/wan-r2v-role2.mp4",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/qpzxps/wan-r2v-object4.png",
            "https://help-static-aliyun-doc.aliyuncs.com/file-manage-files/zh-CN/20260129/wfjikw/wan-r2v-backgroud5.png",
        ]
    },
)
print(video)

接入规范

模型接口

平台接口

快速开始

1. 创建任务

2. 查询状态

3. 获取视频下载地址

返回结果

模型参数

OpenAI Sora

豆包 Seedance

Google Veo

Vidu

可灵 Kling

阿里万相 Wan

调用示例

文生视频

图生视频

首尾帧

图生动作

视频换人

输入自定义音频

指定多角色

​快速开始

​1. 创建任务

​2. 查询状态

​3. 获取视频下载地址

​返回结果

​模型参数

​OpenAI Sora

​豆包 Seedance

​Google Veo

​Vidu

​可灵 Kling

​阿里万相 Wan

​调用示例

​文生视频

​图生视频

​首尾帧

​图生动作

​视频换人

​输入自定义音频

​指定多角色

快速开始

1. 创建任务

2. 查询状态

3. 获取视频下载地址

返回结果

模型参数

OpenAI Sora

豆包 Seedance

Google Veo

Vidu

可灵 Kling

阿里万相 Wan

调用示例

文生视频

图生视频

首尾帧

图生动作

视频换人

输入自定义音频

指定多角色