# 提交视频生成任务

> 视频生成

提交视频生成任务，任务为异步执行，提交成功后返回 task_id，需通过状态查询接口轮询结果。

## 请求地址

`POST https://api.modelverse.cn/v1/tasks/submit`

## 请求体

## 响应

- **200** — 任务提交成功
- **400** — 请求参数错误
- **401** — 认证失败

## OpenAPI 定义

```json
{
  "openapi": "3.1.0",
  "x-language": "zh-CN",
  "info": {
    "title": "Wan3.0 视频生成 API 文档",
    "version": "3.0",
    "description": "Wan3.0 统一视频生成模型，支持文生视频、图生视频、\n参考生视频等多种功能，通过 media 数组自动识别任务类型。\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API 端点"
    }
  ],
  "tags": [
    {
      "name": "wan3.0",
      "description": "Wan3.0 视频生成模型，支持文生视频、图生视频、参考生视频等功能"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/tasks/submit": {
      "post": {
        "summary": "提交视频生成任务",
        "description": "提交视频生成任务，任务为异步执行，提交成功后返回 task_id，需通过状态查询接口轮询结果。\n",
        "operationId": "submitWan30Task",
        "tags": [
          "wan3.0"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Wan30SubmitRequest"
              },
              "examples": {
                "textToVideo": {
                  "summary": "文生视频",
                  "value": {
                    "model": "wan3.0-video",
                    "input": {
                      "prompt": "一只可爱的橘猫在草地上奔跑，阳光明媚，高清画质"
                    },
                    "parameters": {
                      "resolution": "720P",
                      "duration": 10,
                      "ratio": "16:9",
                      "audio": true,
                      "seed": 42
                    }
                  }
                },
                "imageToVideo": {
                  "summary": "图生视频",
                  "value": {
                    "model": "wan3.0-video",
                    "input": {
                      "prompt": "猫咪在草地上奔跑",
                      "media": [
                        {
                          "type": "first_frame",
                          "url": "https://example.com/cat.jpg"
                        }
                      ]
                    },
                    "parameters": {
                      "resolution": "720P",
                      "duration": 8,
                      "ratio": "9:16",
                      "audio": true
                    }
                  }
                },
                "referenceToVideo": {
                  "summary": "参考生视频",
                  "value": {
                    "model": "wan3.0-video",
                    "input": {
                      "prompt": "一只猫在草地上奔跑，参考图片风格",
                      "media": [
                        {
                          "type": "reference_image",
                          "url": "https://example.com/style.jpg"
                        }
                      ]
                    },
                    "parameters": {
                      "resolution": "1080P",
                      "duration": 10
                    }
                  }
                },
                "startEndFrame": {
                  "summary": "首尾帧生成",
                  "value": {
                    "model": "wan3.0-video",
                    "input": {
                      "prompt": "猫咪从草地左边跑到右边",
                      "media": [
                        {
                          "type": "first_frame",
                          "url": "https://example.com/start.jpg"
                        },
                        {
                          "type": "last_frame",
                          "url": "https://example.com/end.jpg"
                        }
                      ]
                    },
                    "parameters": {
                      "resolution": "720P",
                      "duration": 15
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "任务提交成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Wan30SubmitResponse"
                },
                "examples": {
                  "success": {
                    "summary": "提交成功",
                    "value": {
                      "output": {
                        "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                      },
                      "request_id": "req-1234567890abcdef"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "认证失败",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/status": {
      "get": {
        "summary": "查询任务状态",
        "description": "查询视频生成任务状态。任务提交后需要轮询此接口获取最新状态。\n建议轮询间隔：3-5 秒。\n任务完成时间：通常为 2-5 分钟。\n",
        "operationId": "getWan30TaskStatus",
        "tags": [
          "wan3.0"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "任务 ID（提交任务时返回）",
            "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          }
        ],
        "responses": {
          "200": {
            "description": "查询成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Wan30StatusResponse"
                },
                "examples": {
                  "pending": {
                    "summary": "任务等待中",
                    "value": {
                      "output": {
                        "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                        "task_status": "PENDING"
                      },
                      "request_id": ""
                    }
                  },
                  "running": {
                    "summary": "任务执行中",
                    "value": {
                      "output": {
                        "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                        "task_status": "RUNNING"
                      },
                      "request_id": ""
                    }
                  },
                  "success": {
                    "summary": "任务成功",
                    "value": {
                      "output": {
                        "task_id": "f0024590-b898-4418-9468-d4ddb076f9e8",
                        "task_status": "Success",
                        "urls": [
                          "https://dashscope-a717.oss-accelerate.aliyuncs.com/1d/21/20260824/f27c48a3/f0024590-b898-4418-9468-d4ddb076f9e8.mp4?Expires=1787644967&OSSAccessKeyId=LTAI5tPxpiCM2hjmWrFXrym1&Signature=..."
                        ],
                        "submit_time": 1787558473,
                        "finish_time": 1787558593
                      },
                      "usage": {
                        "prompt_tokens": 0,
                        "completion_tokens": 0,
                        "total_tokens": 0,
                        "duration": 10,
                        "input_video_duration": 5,
                        "output_video_duration": 5,
                        "video_count": 1,
                        "SR": 720,
                        "ratio": "415:554"
                      },
                      "request_id": ""
                    }
                  },
                  "failed": {
                    "summary": "任务失败",
                    "value": {
                      "output": {
                        "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                        "task_status": "FAILED",
                        "code": "InvalidParameter",
                        "message": "参数错误：不支持的分辨率"
                      },
                      "request_id": ""
                    }
                  },
                  "cancelled": {
                    "summary": "任务已取消",
                    "value": {
                      "output": {
                        "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                        "task_status": "CANCELLED"
                      },
                      "request_id": ""
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "API key",
        "description": "在请求 Header 中传入 ModelVerse API Key（`Authorization: Bearer <api_key>`）。\n"
      }
    },
    "schemas": {
      "Wan30SubmitRequest": {
        "type": "object",
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "模型名称",
            "enum": [
              "wan3.0-video",
              "wan3.0-video-prime"
            ],
            "example": "wan3.0-video"
          },
          "input": {
            "type": "object",
            "required": [
              "prompt"
            ],
            "properties": {
              "prompt": {
                "type": "string",
                "description": "文本提示词，描述希望生成的视频内容。支持中英文，每个汉字/字母占一个字符，不超过20000个字符，超过部分会自动截断。\n在全能参考模式下，prompt中可以用\"图1\"\"视频1\"等指代 media 数组中对应顺序的媒体素材。\n",
                "maxLength": 20000,
                "example": "一只可爱的橘猫在草地上奔跑，阳光明媚，高清画质"
              },
              "media": {
                "type": "array",
                "description": "媒体资源数组，通过 type 字段区分功能类型：\n- 文生视频: 不填或空数组\n- 图生视频: [{type: \"first_frame\", url: \"...\"}]\n- 尾帧生成: [{type: \"first_frame\", url: \"...\"}, {type: \"last_frame\", url: \"...\"}]\n- 参考生视频: [{type: \"reference_image\", url: \"...\"}]\n- 音频驱动: [{type: \"first_frame\", url: \"...\"}, {type: \"reference_audio\", url: \"...\"}]\n- 网页链接: [{type: \"link\", url: \"...\"}]\n\n**重要提示**：reference_xx/file/link 类型和 first_frame/last_frame 类型互斥，不能在同一请求中混用。\n",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "first_frame",
                        "last_frame",
                        "reference_image",
                        "reference_video",
                        "reference_audio",
                        "file",
                        "link"
                      ],
                      "description": "媒体类型：\n- first_frame: 首帧图像，最多1张，严格作为视频第一帧\n- last_frame: 尾帧图像，最多1张，严格作为视频最后一帧\n- reference_image: 参考图像，最多10张\n- reference_video: 参考视频，最多5段，总时长不大于15秒\n- reference_audio: 参考音频，最多5段，总时长不大于15秒\n- file: 文件，最多1个，不可与 link 同时输入\n- link: 网页链接，最多1个，不可与 file 同时输入\n"
                    },
                    "url": {
                      "type": "string",
                      "description": "媒体素材 URL 或 Base64 编码数据。\n\n**传入图像**（type=first_frame / last_frame / reference_image）\n- 格式：JPEG、JPG、PNG（不支持透明通道）、BMP、WEBP\n- 分辨率：单边 [240, 8000] 像素\n- 长宽比：不超过 8:1\n- 文件大小：不超过 20MB\n- 支持格式：公网 URL（http/https）、临时 URL（oss://）、Base64 编码（data:image/png;base64,...）\n\n**传入视频**（type=reference_video）\n- 格式：mp4、mov\n- 时长：单个 [1, 15] 秒，总时长不大于 15 秒\n- 分辨率：单边 [240, 4096] 像素\n- 长宽比：不超过 8:1\n- 单文件大小：不超过 100MB\n- 支持格式：公网 URL（http/https）、临时 URL（oss://）\n\n**传入音频**（type=reference_audio）\n- 格式：wav、mp3\n- 时长：单个 [1, 15] 秒，总时长不大于 15 秒\n- 文件大小：不超过 15MB\n- 支持格式：公网 URL（http/https）、临时 URL（oss://）\n\n**传入文件**（type=file）\n- 格式：docx、doc、xlsx、xls、pptx、ppt、pdf、txt、key、pages、numbers、md\n- 文件大小：不超过 100MB\n- 页数限制：不超过 50 页（对 pdf、docx、doc、pptx、ppt、key、pages 格式校验）\n- 支持格式：公网 URL（http/https）、临时 URL（oss://）\n\n**传入网页链接**（type=link）\n- 公开网页的 URL 地址，仅支持解析无需登录的公开网页（如新闻、博客、公众号等）\n- 支持格式：公网 URL（http/https）\n"
                    }
                  }
                }
              }
            }
          },
          "parameters": {
            "type": "object",
            "properties": {
              "resolution": {
                "type": "string",
                "description": "输出视频分辨率档位",
                "enum": [
                  "480P",
                  "720P",
                  "1080P"
                ],
                "default": "1080P",
                "example": "720P"
              },
              "ratio": {
                "type": "string",
                "description": "视频长宽比",
                "enum": [
                  "adaptive",
                  "16:9",
                  "9:16",
                  "1:1",
                  "4:3",
                  "3:4"
                ],
                "default": "adaptive",
                "example": "16:9"
              },
              "duration": {
                "type": "integer",
                "description": "生成视频的时长，单位为秒。默认值为 5。\n- 无视频输入时：取值范围为 [2, 30] 的整数\n- 有视频输入时：输入视频总时长 + 输出视频时长不超过 30 秒\n",
                "default": 5,
                "example": 10
              },
              "audio": {
                "type": "boolean",
                "description": "输出视频是否包含音频。\n- true：输出视频包含声音\n- false：默认值，输出视频不包含音轨\n开关声音价格相同\n",
                "default": false,
                "example": false
              },
              "seed": {
                "type": "integer",
                "description": "随机种子，用于复现生成结果",
                "minimum": 0,
                "maximum": 2147483647,
                "example": 42
              },
              "prompt_extend": {
                "type": "boolean",
                "description": "是否开启 prompt 智能改写。开启后使用大模型对输入 prompt 进行智能改写。\n对于较短的 prompt 生成效果提升明显，但会增加耗时。\n- true：默认值，开启智能改写\n- false：不开启智能改写\n",
                "default": true,
                "example": true
              },
              "watermark": {
                "type": "boolean",
                "description": "是否添加水印标识。\n- false：默认值，不添加水印\n- true：添加水印\n",
                "default": false,
                "example": false
              }
            }
          }
        }
      },
      "Wan30SubmitResponse": {
        "type": "object",
        "properties": {
          "output": {
            "type": "object",
            "properties": {
              "task_id": {
                "type": "string",
                "description": "任务 ID，用于后续查询",
                "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "请求 ID，用于问题追踪",
            "example": "req-1234567890abcdef"
          }
        }
      },
      "Wan30StatusResponse": {
        "type": "object",
        "properties": {
          "output": {
            "type": "object",
            "properties": {
              "task_id": {
                "type": "string",
                "description": "任务 ID",
                "example": "f0024590-b898-4418-9468-d4ddb076f9e8"
              },
              "task_status": {
                "type": "string",
                "enum": [
                  "PENDING",
                  "RUNNING",
                  "Success",
                  "FAILED",
                  "CANCELLED"
                ],
                "description": "任务状态（注意：成功状态为 \"Success\" 不是 \"SUCCEEDED\"）"
              },
              "urls": {
                "type": "array",
                "description": "生成的视频 URL 列表（任务成功时返回）",
                "items": {
                  "type": "string"
                },
                "example": [
                  "https://dashscope-a717.oss-accelerate.aliyuncs.com/1d/21/20260824/f27c48a3/f0024590-b898-4418-9468-d4ddb076f9e8.mp4?Expires=1787644967&OSSAccessKeyId=LTAI5tPxpiCM2hjmWrFXrym1&Signature=..."
                ]
              },
              "submit_time": {
                "type": "integer",
                "description": "提交时间戳（Unix 时间戳）",
                "example": 1787558473
              },
              "finish_time": {
                "type": "integer",
                "description": "完成时间戳（Unix 时间戳）",
                "example": 1787558593
              },
              "code": {
                "type": "string",
                "description": "错误码（任务失败时返回）",
                "example": "InvalidParameter"
              },
              "message": {
                "type": "string",
                "description": "错误信息（任务失败时返回）",
                "example": "参数错误：不支持的分辨率"
              }
            }
          },
          "usage": {
            "type": "object",
            "description": "用量信息（用于计费）",
            "properties": {
              "prompt_tokens": {
                "type": "integer",
                "example": 0
              },
              "completion_tokens": {
                "type": "integer",
                "example": 0
              },
              "total_tokens": {
                "type": "integer",
                "example": 0
              },
              "duration": {
                "type": "integer",
                "description": "视频时长（秒）",
                "example": 10
              },
              "input_video_duration": {
                "type": "integer",
                "description": "输入视频时长（秒）",
                "example": 5
              },
              "output_video_duration": {
                "type": "integer",
                "description": "输出视频时长（秒）",
                "example": 5
              },
              "video_count": {
                "type": "integer",
                "example": 1
              },
              "SR": {
                "type": "integer",
                "description": "分辨率档位（用于计费）",
                "example": 720
              },
              "ratio": {
                "type": "string",
                "example": "415:554"
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "请求 ID",
            "example": ""
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "错误响应",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "message",
              "type"
            ],
            "properties": {
              "message": {
                "type": "string",
                "description": "错误消息"
              },
              "type": {
                "type": "string",
                "description": "错误类型"
              },
              "param": {
                "type": "string",
                "description": "相关参数"
              },
              "code": {
                "type": "string",
                "description": "错误代码"
              }
            }
          }
        }
      }
    }
  }
}
```