Wan 2.7 Video

Wan 2.7 Video 用于创建异步视频生成任务。你可以使用文本提示词生成视频，也可以传入图片作为图生视频输入、首帧、尾帧或参考图。

创建任务后，接口会立即返回任务 ID。客户端需要使用查询接口轮询任务状态；任务完成后，可从查询结果的 metadata.url 读取视频地址，也可以通过内容接口下载视频。

接口地址

能力	方法	路径
创建视频任务	POST	/v1/videos
查询视频任务	GET	/v1/videos/{task_id}
获取视频内容	GET	/v1/videos/{task_id}/content
统一创建视频任务	POST	/v1/video/generations
统一查询视频任务	GET	/v1/video/generations/{task_id}

/v1/videos 和 /v1/video/generations 使用同一套请求字段。推荐新接入优先使用 /v1/videos。

请求需要携带 API Key：

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

支持模型

模型	说明
wan2.7	Wan 2.7 视频生成模型

实际可用模型以账号权限和平台配置为准。

支持模式

模式	输入方式
文生视频	prompt
图生视频	image、images 或 input_reference
首尾帧视频	images 中传 2 张图片
参考图视频	images 中传多张参考图
统一视频接口	同一套字段也可提交到 /v1/video/generations

请求参数

POST /v1/videos

参数	必填	说明
model	是	Wan 模型名称，使用 wan2.7
prompt	是	视频生成提示词，描述主体、动作、场景、镜头语言和风格
duration	否	视频时长，单位秒；也可以使用字符串字段 seconds
seconds	否	视频时长字符串，例如 "5"；与 duration 二选一即可
size	否	输出规格。可传分辨率如 720p、1080p，也可传比例如 16:9、9:16、1:1
image	否	单张图片 URL，等价于只传一项 images
images	否	图片 URL 数组。1 张图通常作为图生视频输入；2 张图可作为首尾帧；多张图可作为参考图
input_reference	否	单个参考图片 URL，等价于单张图片输入
metadata	否	Wan 扩展参数对象，会透传给任务创建逻辑

常用 metadata 字段：

字段	说明
resolution	输出清晰度，例如 720p、1080p；仅在所选模型支持时传入
aspect_ratio	输出画面比例，例如 16:9、9:16、1:1
ratio	画面比例别名；如果同时传 aspect_ratio，以平台实际处理为准
negative_prompt	负向提示词
seed	随机种子
prompt_extend	是否启用提示词扩写；实际效果以所选模型支持为准
watermark	是否添加水印；实际效果以渠道配置为准
payload	自定义透传字符串，会在任务结果中原样返回

图片 URL 需要可被公网访问。常见图片格式包括 jpg、jpeg、png、webp。

调用示例

文生视频

curl -X POST https://cubicspaces.cloud/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "wan2.7",
    "prompt": "A cinematic shot of a glass cube floating above a quiet lake at sunrise, soft reflections, slow camera push in",
    "duration": 5,
    "size": "16:9",
    "metadata": {
      "resolution": "720p",
      "negative_prompt": "blur, distortion, low quality",
      "prompt_extend": true
    }
  }'

图生视频

curl -X POST https://cubicspaces.cloud/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "wan2.7",
    "prompt": "Keep the product shape consistent. The camera slowly rotates around the product on a clean studio background.",
    "image": "https://example.com/product.png",
    "duration": 5,
    "size": "1:1",
    "metadata": {
      "resolution": "720p",
      "negative_prompt": "deformation, flicker"
    }
  }'

首尾帧视频

传入两张图片时，系统会按首帧和尾帧理解输入，适合做过渡动画。

curl -X POST https://cubicspaces.cloud/v1/videos \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "wan2.7",
    "prompt": "Create a smooth transition from image 1 to image 2, keep lighting natural and motion fluid.",
    "images": [
      "https://example.com/start.png",
      "https://example.com/end.png"
    ],
    "duration": 5,
    "size": "16:9",
    "metadata": {
      "resolution": "720p"
    }
  }'

统一视频接口

如果你的客户端已经接入统一视频接口，也可以使用 /v1/video/generations 创建 Wan 2.7 任务。

curl -X POST https://cubicspaces.cloud/v1/video/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "model": "wan2.7",
    "prompt": "A futuristic cubic city at night, neon reflections, cinematic camera movement",
    "seconds": "5",
    "image": "https://example.com/reference.png",
    "metadata": {
      "aspect_ratio": "16:9",
      "resolution": "720p"
    }
  }'

返回和查询

创建成功后会返回视频任务对象：

{
  "id": "task_xxx",
  "task_id": "task_xxx",
  "object": "video",
  "model": "wan2.7",
  "status": "queued",
  "progress": 0,
  "created_at": 1770000000
}

请保存 id，后续用它查询任务状态和获取视频内容。

查询任务：

curl https://cubicspaces.cloud/v1/videos/task_xxx \
  -H "Authorization: Bearer YOUR_API_KEY"

生成中通常返回：

{
  "id": "task_xxx",
  "object": "video",
  "model": "wan2.7",
  "status": "running",
  "progress": 45,
  "metadata": {}
}

完成后通常返回：

{
  "id": "task_xxx",
  "object": "video",
  "model": "wan2.7",
  "status": "succeeded",
  "progress": 100,
  "metadata": {
    "url": "https://example.com/generated-video.mp4"
  }
}

不同渠道可能会返回额外字段；客户端应优先使用 status 判断任务状态，并从 metadata.url 读取最终视频地址。

获取视频内容

curl -L https://cubicspaces.cloud/v1/videos/task_xxx/content \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output wan2.7-video.mp4

内容接口会在任务完成后返回视频文件或重定向到视频地址。若任务尚未完成，请继续轮询查询接口。

状态值

状态	说明
queued	任务已创建，等待执行
running	任务生成中
succeeded	任务完成，可读取视频地址
failed	任务失败，查看响应中的错误信息
cancelled	任务已取消