生成AI视频

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

接口

POST /jobs/createTask

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

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

WARNING

当前为新版本接口文档；老版本接口请查看 [https://ai.modelfold.online/docs/)。

从文本提示或图像参考创建动态AI生成的视频。

使用指南

• 使用AI可视化创建短视频（5-10秒）
• 基于文本描述或参考图像生成视频
• 适用于社交媒体内容、数字艺术或概念可视化

参数详情

• prompt 描述您想要在视频中呈现的内容
• image_url 为AI提供视觉参考
• aspect_ratio 确定视频方向（垂直或水平）
• duration 控制视频时长（5或10秒），其中如果选择了10秒的视频，则无法选择1080p的分辨率
• quality 视频分辨率（720p或1080p），其中如果选择了1080p，则无法生成10秒的视频
• watermark 视频水印文本内容，空字符串表示不添加水印

开发者注意事项

• 生成的视频存储14天后自动删除
• 仅文本生成时，必须明确指定宽高比

请求参数

请求体 (application/json)

参数	类型	必填	说明
model	string	是	模型名称 默认值："runway"。 示例：runway。
callBackUrl	string	否	用于接收AI视频生成任务完成更新的URL地址。所有视频生成请求都需要此参数。 - 系统将在AI视频生成完成时向此URL发送POST请求，包含任务状态和结果 - 回调包含生成的视频URL、封面图片和任务信息 - 您的回调端点应能接受包含视频结果的JSON载荷的POST请求 - 详细的回调格式和实现指南，请参见 视频生成回调 - 也可轮询获取任务详情（/cn/market/common/get-task-detail）。 - 为确保回调安全性，请参阅 Webhook 校验指南 了解签名验证实现方法 示例：https://api.example.com/callback。
input	object	是	—
input.prompt	string	是	指导AI视频生成的描述性文本。具体说明主题、动作、风格和场景。当与图像一起使用时，描述如何为图像内容添加动画或修改。最大长度为1800个字符。 示例：一只蓬松的橙色猫在有迪斯科灯光的彩色房间里精力充沛地跳舞。
input.image_url	string	否	可选的参考图像URL，作为视频的基础。提供后，AI将创建一个为此图像添加动画或扩展的视频。 示例：https://example.com/cat-image.jpg。
input.duration	number	是	视频时长，可选值为5或10。如果选10秒视频，则无法使用1080p分辨率 示例：5。
input.quality	string	是	视频分辨率，可选值为720p或1080p。如果选择了1080p，则无法生成10秒的视频 示例：720p。
input.aspect_ratio	string	否	视频宽高比参数。文本生成视频请求的必填参数。当传递image_url时该参数无效，宽高比最终将由传递的图片决定。 可选值：16:9 / 4:3 / 1:1 / 3:4 / 9:16。 示例：9:16。
input.watermark	string	否	视频水印文本内容。空字符串表示不添加水印，非空字符串将在视频右下角显示指定的水印文本。 示例：ai.modelfold.online。

请求示例

curl -X POST "https://ai.modelfold.online/v1/jobs/createTask" \
  -H "Authorization: Bearer $MODELFOLD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "model": "runway",
  "callBackUrl": "https://api.example.com/callback",
  "input": {
    "prompt": "一只蓬松的橙色猫在有迪斯科灯光的彩色房间里精力充沛地跳舞",
    "image_url": "https://example.com/cat-image.jpg",
    "duration": 5,
    "quality": "720p",
    "aspect_ratio": "9:16",
    "watermark": "ai.modelfold.online"
  }
}'

{
  "model": "runway",
  "callBackUrl": "https://api.example.com/callback",
  "input": {
    "prompt": "一只蓬松的橙色猫在有迪斯科灯光的彩色房间里精力充沛地跳舞",
    "image_url": "https://example.com/cat-image.jpg",
    "duration": 5,
    "quality": "720p",
    "aspect_ratio": "9:16",
    "watermark": "ai.modelfold.online"
  }
}

响应

200 — 请求成功

参数	类型	必填	说明
code	integer	否	请求状态码。请求失败时 HTTP 状态仍为 200，请始终以本字段判断：200 表示成功，其他值均表示失败，原因见 msg。常见值：401 API key 无效或缺失；402 积分不足；429 超出频率限制；422 或 500 请求未能处理（请先查看 msg、检查参数，再决定是否重试）。 可选值：200 / 401 / 404 / 422 / 451 / 455 / 500。 示例：200。
msg	string	否	当 code != 200 时的错误信息 示例：success。
data	object	否	—
data.taskId	string	否	生成任务的唯一标识符，可使用 获取AI视频详情 查询任务状态 示例：ee603959-debb-48d1-98c4-a6d1c717eba6。

{
  "code": 200,
  "msg": "success",
  "data": {
    "taskId": "ee603959-debb-48d1-98c4-a6d1c717eba6"
  }
}

500 — 服务器错误

回调

onVideoGenerated

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

当视频生成完成后，系统会向提供的回调 URL 发送 POST 请求通知结果

回调体参数

参数	类型	必填	说明
code	integer	否	状态码 - 200：成功，任务已完成 - 501：失败，任务执行失败，原因见 data.failCode 与 data.failMsg 可选值：200 / 501。 示例：200。
msg	string	否	状态消息 示例：Playground task completed successfully.。
data	object	否	—
data.taskId	string	否	任务 ID 示例：94bbfeaa1383c296cd61ba5dfcbfe30e。
data.model	string	否	任务使用的模型 示例：runway。
data.state	string	否	任务状态 可选值：success / fail。 示例：success。
data.param	string	否	创建任务时提交的参数，JSON 字符串格式 示例：{"input":"{\"prompt\":\"A cartoon fox paints a rainbow on a wooden fence, colorful 3D animation\",\"duration\":5,\"quality\":\"720p\",\"aspect_ratio\":\"16:9\"}","callBackUrl":"https://your-domain.com/api/callback","model":"runway"}。
data.resultJson	string	否	结果，JSON 字符串格式（state 为 success 时返回）。resultUrls 为生成视频的 URL 列表 示例：{"resultUrls":["https://tempfile.aiquickdraw.com/p/c03630ba7484476a905fc14625b7304a_1_1791218754_8541.mp4"]}。
data.failCode	string	否	失败码（state 为 fail 时返回）
data.failMsg	string	否	失败原因（state 为 fail 时返回）
data.costTime	integer	否	任务耗时，单位为秒 示例：68。
data.creditsConsumed	number	否	任务消耗的积分数量 示例：12。
data.createTime	integer	否	任务创建时间，Unix 毫秒时间戳 示例：1791218688000。
data.completeTime	integer	否	任务完成时间，Unix 毫秒时间戳 示例：1791218756020。
data.updateTime	integer	否	任务最后更新时间，Unix 毫秒时间戳 示例：1791218756020。

{
  "code": 200,
  "msg": "Playground task completed successfully.",
  "data": {
    "taskId": "94bbfeaa1383c296cd61ba5dfcbfe30e",
    "model": "runway",
    "state": "success",
    "param": "{\"input\":\"{\\\"prompt\\\":\\\"A cartoon fox paints a rainbow on a wooden fence, colorful 3D animation\\\",\\\"duration\\\":5,\\\"quality\\\":\\\"720p\\\",\\\"aspect_ratio\\\":\\\"16:9\\\"}\",\"callBackUrl\":\"https://your-domain.com/api/callback\",\"model\":\"runway\"}",
    "resultJson": "{\"resultUrls\":[\"https://tempfile.aiquickdraw.com/p/c03630ba7484476a905fc14625b7304a_1_1791218754_8541.mp4\"]}",
    "failCode": "",
    "failMsg": "",
    "costTime": 68,
    "creditsConsumed": 12,
    "createTime": 1791218688000,
    "completeTime": 1791218756020,
    "updateTime": 1791218756020
  }
}