ModelFold Docs

简体中文

English

简体中文

English

Appearance

Wan 2.7 - 参考生视频 ​

本页由 ModelFold 文档站根据上游官方 OpenAPI 文档同步生成。接口路径、参数、示例与官方保持一致；品牌与 API 域名已替换为 ModelFold。

接口 ​

POST /jobs/createTask

完整 URL: https://ai.modelfold.online/v1/jobs/createTask

鉴权：所有请求都需要 Authorization: Bearer <API_KEY> 请求头。

创建任务 ​

调用该接口可创建一个新的参考驱动视频生成任务。

  • 查询任务详情 — 提交任务后，可通过统一查询接口查看任务进度并获取生成结果

TIP

生产环境建议优先使用 callBackUrl 参数接收任务完成通知，而不是持续轮询任务状态接口。

相关资源 ​

请求参数 ​

请求体 (application/json) ​

参数类型必填说明
modelstring是用于生成任务的模型名称。该字段为必填项。此接口必须使用 wan/2-7-r2v 模型。 默认值："wan/2-7-r2v"。 可选值：wan/2-7-r2v。 示例：wan/2-7-r2v。
callBackUrlstring否任务完成通知的回调 URL。该参数为可选项。如果提供，当任务完成时，无论成功或失败，系统都会向该 URL 发送 POST 请求。如果未提供，则不会发送回调通知。 示例：https://your-domain.com/api/callback。
inputobject是参考驱动视频生成任务的输入参数。
  input.promptstring是文本提示词。必填，用来描述生成视频中期望包含的元素和视觉特点。支持中英文，最大长度 5000 字符。 示例：图1在吃饭，视频1和图2在旁边唱歌。。
  input.negative_promptstring否反向提示词，用来描述不希望在视频画面中出现的内容。支持中英文，最大长度 500 字符。 示例：低分辨率、错误、最差质量、低质量、残缺、多余的手指、比例不良等。。
  input.reference_imagearray&lt;string&gt;否参考图像 URL 数组。参考图像与参考视频至少传入一种；图像数 + 视频数总和不能超过 5。
  input.reference_videoarray&lt;string&gt;否参考视频 URL 数组。参考图像与参考视频至少传入一种；图像数 + 视频数总和不能超过 5。
  input.first_framestring否首帧图像 URL，最多传入 1 张。传入后会自动忽略 aspect_ratio，以首帧图像宽高比生成近似比例视频。 示例：https://example.com/demo/first-frame.png。
  input.reference_voicestring否音频 URL。用于指定参考素材主体角色的音色。
规则：
- 若 reference_video 本身有音频但未传 reference_voice，默认使用视频原声
- 若同时传入 reference_video 和 reference_voice，则优先使用 reference_voice
音频限制：
- 格式：wav、mp3
- 时长：1 到 10 秒
- 文件大小：不超过 30MB 示例：https://example.com/demo/reference-voice.mp3。
  input.resolutionstring否输出视频分辨率档位。可选值：720p、1080p。默认值为 1080p。 默认值："1080p"。 可选值：720p / 1080p。 示例：1080p。
  input.aspect_ratiostring否输出视频宽高比。
生效逻辑：
- 未传入 first_frame：按指定的 aspect_ratio 生成视频
- 已传入 first_frame：自动忽略 aspect_ratio，以首帧图像宽高比生成近似比例视频 默认值："16:9"。 可选值：16:9 / 9:16 / 1:1 / 4:3 / 3:4。 示例：16:9。
  input.durationinteger否输出视频时长，单位秒。取值范围为 2-10 的整数，默认值为 5。 默认值：5。 示例：5。
  input.prompt_extendboolean否是否开启 prompt 智能改写。开启后使用大模型对输入 prompt 进行扩写，短 prompt 场景下效果更好，但会增加耗时。 默认值：true。 示例：true。
  input.watermarkboolean否是否添加水印。水印位于视频右下角，文案固定为“AI生成”。 默认值：false。 示例：false。
  input.seedinteger否随机种子，范围 0-2147483647。未传时系统自动生成。 示例：0。
  input.nsfw_checkerboolean否默认 false。为 false 时不额外进行内容过滤，结果由模型直接返回。

请求示例 ​

bash
curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "wan/2-7-r2v",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "图1在吃饭，视频1和图2在旁边唱歌。",
    "negative_prompt": "低分辨率、错误、最差质量、低质量、残缺、多余的手指、比例不良等。",
    "reference_image": [
      "https://example.com/demo/ref-image-1.png",
      "https://example.com/demo/ref-image-2.png"
    ],
    "reference_video": [
      "https://example.com/demo/ref-video-1.mp4"
    ],
    "first_frame": "https://example.com/demo/first-frame.png",
    "reference_voice": "https://example.com/demo/reference-voice.mp3",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 5,
    "prompt_extend": true,
    "watermark": false,
    "seed": 0
  }
}'
json
{
  "model": "wan/2-7-r2v",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "图1在吃饭，视频1和图2在旁边唱歌。",
    "negative_prompt": "低分辨率、错误、最差质量、低质量、残缺、多余的手指、比例不良等。",
    "reference_image": [
      "https://example.com/demo/ref-image-1.png",
      "https://example.com/demo/ref-image-2.png"
    ],
    "reference_video": [
      "https://example.com/demo/ref-video-1.mp4"
    ],
    "first_frame": "https://example.com/demo/first-frame.png",
    "reference_voice": "https://example.com/demo/reference-voice.mp3",
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "duration": 5,
    "prompt_extend": true,
    "watermark": false,
    "seed": 0
  }
}

响应 ​

200 — 请求成功 ​

参数类型必填说明
codeinteger是请求状态码。请求失败时 HTTP 状态仍为 200，请始终以本字段判断：200 表示成功，其他值均表示失败，原因见 msg。常见值：401 API key 无效或缺失；402 积分不足；429 超出频率限制；422 或 500 请求未能处理（请先查看 msg、检查参数，再决定是否重试）。 可选值：200 / 401 / 402 / 404 / 422 / 429 / 433 / 455 / 500 / 501 / 505。 示例：200。
msgstring是响应消息，失败时的错误描述
dataobject是—
  data.taskIdstring是可以使用任务 ID 与“获取任务详细信息”端点一起查询任务状态。
json
{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_wan_1765180586443"
  }
}

回调 ​

videoTaskCompleted ​

回调地址：{request.body#/callBackUrl}（即请求体里的 callBackUrl）。

当 wan/2-7-r2v 任务成功或失败时，系统会发送此回调。

回调体参数

参数类型必填说明
codeinteger是统一回调状态码：成功为 200，失败为 501。 可选值：200 / 501。 示例：200。
msgstring是统一回调消息。 可选值：Playground task completed successfully. / Playground task failed.。 示例：Playground task completed successfully.。
dataobject是—
  data.taskIdstring是任务唯一标识符。
  data.modelstring是任务使用的模型。 可选值：wan/2-7-r2v。 示例：wan/2-7-r2v。
  data.statestring是任务最终状态。 可选值：success / fail。 示例：success。
  data.paramstring是包含已提交任务参数的 JSON 字符串。
  data.resultJsonstring否任务成功时，包含 resultUrls、firstFrameUrl、lastFrameUrl 或 resultObject 的 JSON 字符串。仅在 state 为 success 时出现。
  data.failCodestring否失败码，数字字符串，如 "400"、"500"。仅在 state 为 fail 时出现。
  data.failMsgstring否失败原因，仅在 state 为 fail 时出现。
  data.costTimeinteger否处理耗时（秒），成功和失败回调都会返回。
  data.completeTimeinteger否任务完成时间戳。
  data.createTimeinteger否任务创建时间戳。
  data.updateTimeinteger否完成时间请以 completeTime 为准；updateTime 可能与 createTime 相同。
  data.creditsConsumednumber否本任务消耗的积分；失败任务为 0。

任务成功完成

json
{
  "code": 200,
  "msg": "Playground task completed successfully.",
  "data": {
    "taskId": "task_example_video_webhook_001",
    "model": "wan/2-7-r2v",
    "state": "success",
    "param": "{\"input\":\"{\\\"prompt\\\":\\\"Image 1 is eating, while video 1 and image 2 are singing beside it.\\\",\\\"negative_prompt\\\":\\\"low resolution, errors, worst quality, low quality, malformed, extra fingers, bad proportions\\\",\\\"reference_image\\\":[\\\"https://example.com/input-image.jpg\\\"],\\\"reference_video\\\":[\\\"https://example.com/input-video.mp4\\\"],\\\"first_frame\\\":\\\"https://example.com/input-image.jpg\\\",\\\"reference_voice\\\":\\\"https://example.com/input-audio.mp3\\\",\\\"resolution\\\":\\\"1080p\\\",\\\"aspect_ratio\\\":\\\"16:9\\\",\\\"duration\\\":5,\\\"prompt_extend\\\":true,\\\"watermark\\\":false,\\\"seed\\\":0}\",\"callBackUrl\":\"https://example.com/callback\",\"model\":\"wan/2-7-r2v\"}",
    "resultJson": "{\"resultUrls\":[\"https://example.com/generated-video.mp4\"]}",
    "costTime": 12,
    "completeTime": 1234567890,
    "createTime": 1234560000,
    "updateTime": 1234567890,
    "creditsConsumed": 1.23
  }
}

任务失败

json
{
  "code": 501,
  "msg": "Playground task failed.",
  "data": {
    "taskId": "task_example_video_webhook_001",
    "model": "wan/2-7-r2v",
    "state": "fail",
    "param": "{\"input\":\"{\\\"prompt\\\":\\\"Image 1 is eating, while video 1 and image 2 are singing beside it.\\\",\\\"negative_prompt\\\":\\\"low resolution, errors, worst quality, low quality, malformed, extra fingers, bad proportions\\\",\\\"reference_image\\\":[\\\"https://example.com/input-image.jpg\\\"],\\\"reference_video\\\":[\\\"https://example.com/input-video.mp4\\\"],\\\"first_frame\\\":\\\"https://example.com/input-image.jpg\\\",\\\"reference_voice\\\":\\\"https://example.com/input-audio.mp3\\\",\\\"resolution\\\":\\\"1080p\\\",\\\"aspect_ratio\\\":\\\"16:9\\\",\\\"duration\\\":5,\\\"prompt_extend\\\":true,\\\"watermark\\\":false,\\\"seed\\\":0}\",\"callBackUrl\":\"https://example.com/callback\",\"model\":\"wan/2-7-r2v\"}",
    "failCode": "400",
    "failMsg": "<error detail>",
    "costTime": 12,
    "creditsConsumed": 0
  }
}

ModelFold — 一个 API，接入所有主流 AI 模型。

© 2026 ModelFold