Vidu Q4 参考生视频

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

接口

POST /jobs/createTask

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

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

查询任务状态

提交任务后，你可以通过统一查询接口查看任务进度并获取生成结果：

• 获取任务详情 — 了解如何查询任务状态并获取生成结果

TIP

在生产环境中，建议使用 "callBackUrl" 参数接收生成完成后的自动通知，而不是轮询状态接口。

相关资源

• 市场概览 — 查看所有可用模型
• 通用 API — 查看账户积分和用量

请求参数

请求体 (application/json)

参数	类型	必填	说明
model	string	是	用于生成的模型名称。此接口必须使用 vidu-q4/reference-to-video。 默认值："vidu-q4/reference-to-video"。 可选值：vidu-q4/reference-to-video。 示例：vidu-q4/reference-to-video。
callBackUrl	string	否	接收生成任务完成状态更新的回调地址。可选，但建议在生产环境中使用。生成完成后，系统会将任务状态和结果以 POST 方式发送到该地址。 示例：https://your-domain.com/api/callback。
input	object	是	生成任务的输入参数。
input.prompt	string	是	视频的文字描述。可按顺序引用输入素材，例如 "参考图 2 中的男人说……，使用参考音频 1"。最多 20000 个字符。
input.duration	integer	否	视频时长（秒）。整数，范围 3 到 16。 默认值：5。 示例：5。
input.resolution	string	否	输出分辨率。 默认值："720p"。 可选值：540p / 720p / 1080p / 2k / 4k。 示例：720p。
input.audio	boolean	否	生成同步音频（对白和音效）。设为 false 则生成无声视频。 默认值：true。 示例：true。
input.reference_image_urls	array<string>	是	参考图片地址（http/https），1 到 15 张。支持 JPG、JPEG、PNG、WEBP 格式。
input.reference_audio_urls	array<string>	否	可选的参考音频地址（http/https），最多 3 个。仅支持 MP3 格式，每个时长 3 到 12 秒，最大 50 MB。
input.aspect_ratio	string	否	输出宽高比。 默认值："16:9"。 可选值：16:9 / 9:16 / 1:1 / 4:3 / 3:4。 示例：16:9。

请求示例

curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "vidu-q4/reference-to-video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "在参考图像1的场景中，参考图像2中的人物转向参考图像3中的人物并说道：“你在做什么？”\"",
    "reference_image_urls": [
      "https://static.aiquickdraw.com/tools/example/vidu-q4-ref-1.png",
      "https://static.aiquickdraw.com/tools/example/vidu-q4-ref-2.png",
      "https://static.aiquickdraw.com/tools/example/vidu-q4-ref-3.png"
    ],
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "audio": true
  }
}'

{
  "model": "vidu-q4/reference-to-video",
  "callBackUrl": "https://your-domain.com/api/callback",
  "input": {
    "prompt": "在参考图像1的场景中，参考图像2中的人物转向参考图像3中的人物并说道：“你在做什么？”\"",
    "reference_image_urls": [
      "https://static.aiquickdraw.com/tools/example/vidu-q4-ref-1.png",
      "https://static.aiquickdraw.com/tools/example/vidu-q4-ref-2.png",
      "https://static.aiquickdraw.com/tools/example/vidu-q4-ref-3.png"
    ],
    "duration": 5,
    "resolution": "1080p",
    "aspect_ratio": "16:9",
    "audio": true
  }
}

响应

200 — 请求成功

参数	类型	必填	说明
code	integer	否	请求状态码。请求失败时 HTTP 状态仍为 200，请始终以本字段判断：200 表示成功，其他值均表示失败，原因见 msg。常见值：401 API key 无效或缺失；402 积分不足；429 超出频率限制；422 或 500 请求未能处理（请先查看 msg、检查参数，再决定是否重试）。 可选值：200 / 400 / 401 / 402 / 404 / 422 / 429 / 455 / 500 / 501 / 505。 示例：200。
msg	string	否	响应消息 示例：success。
data	object	否	—
data.taskId	string	否	任务 ID，可用于获取任务详情接口查询任务状态 示例：task_abcdef123456。

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "task_abcdef123456"
  }
}

500 — 服务器错误

回调

videoTaskCompleted

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

系统在 vidu-q4/reference-to-video 任务成功或失败时发送此回调。

回调体参数

参数	类型	必填	说明
code	integer	是	统一回调状态码：200 表示成功，501 表示失败。 可选值：200 / 501。 示例：200。
msg	string	是	统一回调消息。
data	object	是	—
data.taskId	string	是	任务的唯一标识符。
data.model	string	是	任务所使用的模型。 可选值：vidu-q4/reference-to-video。 示例：vidu-q4/reference-to-video。
data.state	string	是	任务的最终状态。 可选值：success / fail。 示例：success。
data.param	string	是	包含提交任务参数的 JSON 字符串。
data.resultJson	string,null	否	任务成功时包含 resultUrls 的 JSON 字符串。仅在 state 为 success 时存在。
data.failCode	string,null	否	失败代码。仅在 state 为 fail 时存在。
data.failMsg	string,null	否	失败原因。仅在 state 为 fail 时存在。
data.costTime	integer	否	处理耗时（秒）。
data.completeTime	integer	否	任务完成时间戳。
data.createTime	integer	否	任务创建时间戳。

{
  "code": 200,
  "msg": "",
  "data": {
    "taskId": "",
    "model": "vidu-q4/reference-to-video",
    "state": "success",
    "param": "",
    "costTime": 0,
    "completeTime": 0,
    "createTime": 0
  }
}