# Submit Video Generation Task

> Video Generation

Submit a video generation task. The task runs asynchronously. After successful submission, a task_id is returned, which needs to be polled through the status query interface.

## Endpoint

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

## Request Body

## Responses

- **200** — Task submitted successfully
- **400** — Invalid request parameters
- **401** — Authentication failed

## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "x-language": "en-US",
  "info": {
    "title": "Wan3.0 Video Generation API Documentation",
    "version": "3.0",
    "description": "Wan3.0 unified video generation model, supporting text-to-video, image-to-video,\nreference-to-video and other functions. Task types are automatically recognized through the media array.\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API Endpoint"
    }
  ],
  "tags": [
    {
      "name": "wan3.0",
      "description": "Wan3.0 video generation model, supporting text-to-video, image-to-video, reference-to-video and other functions"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/v1/tasks/submit": {
      "post": {
        "summary": "Submit Video Generation Task",
        "description": "Submit a video generation task. The task runs asynchronously. After successful submission, a task_id is returned, which needs to be polled through the status query interface.\n",
        "operationId": "submitWan30Task",
        "tags": [
          "wan3.0"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Wan30SubmitRequest"
              },
              "examples": {
                "textToVideo": {
                  "summary": "Text-to-Video",
                  "value": {
                    "model": "wan3.0-video",
                    "input": {
                      "prompt": "A cute orange cat running on the grass, sunny day, high quality"
                    },
                    "parameters": {
                      "resolution": "720P",
                      "duration": 10,
                      "ratio": "16:9",
                      "audio": false,
                      "seed": 42
                    }
                  }
                },
                "imageToVideo": {
                  "summary": "Image-to-Video",
                  "value": {
                    "model": "wan3.0-video",
                    "input": {
                      "prompt": "Cat running on the grass",
                      "media": [
                        {
                          "type": "first_frame",
                          "url": "https://example.com/cat.jpg"
                        }
                      ]
                    },
                    "parameters": {
                      "resolution": "720P",
                      "duration": 8,
                      "ratio": "9:16",
                      "audio": false
                    }
                  }
                },
                "referenceToVideo": {
                  "summary": "Reference-to-Video",
                  "value": {
                    "model": "wan3.0-video",
                    "input": {
                      "prompt": "A cat running on the grass, reference image style",
                      "media": [
                        {
                          "type": "reference_image",
                          "url": "https://example.com/style.jpg"
                        }
                      ]
                    },
                    "parameters": {
                      "resolution": "1080P",
                      "duration": 10
                    }
                  }
                },
                "startEndFrame": {
                  "summary": "Start-End Frame Generation",
                  "value": {
                    "model": "wan3.0-video",
                    "input": {
                      "prompt": "Cat running from left to right on the grass",
                      "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": "Task submitted successfully",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Wan30SubmitResponse"
                },
                "examples": {
                  "success": {
                    "summary": "Submission successful",
                    "value": {
                      "output": {
                        "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
                      },
                      "request_id": "req-1234567890abcdef"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "Authentication failed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/status": {
      "get": {
        "summary": "Query Task Status",
        "description": "Query the status of a video generation task. After task submission, poll this interface to get the latest status.\nRecommended polling interval: 3-5 seconds.\nTypical completion time: 2-5 minutes.\n",
        "operationId": "getWan30TaskStatus",
        "tags": [
          "wan3.0"
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Task ID (returned when submitting the task)",
            "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
          }
        ],
        "responses": {
          "200": {
            "description": "Query successful",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Wan30StatusResponse"
                },
                "examples": {
                  "pending": {
                    "summary": "Task pending",
                    "value": {
                      "output": {
                        "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                        "task_status": "PENDING"
                      },
                      "request_id": ""
                    }
                  },
                  "running": {
                    "summary": "Task running",
                    "value": {
                      "output": {
                        "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                        "task_status": "RUNNING"
                      },
                      "request_id": ""
                    }
                  },
                  "success": {
                    "summary": "Task successful",
                    "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": "Task failed",
                    "value": {
                      "output": {
                        "task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
                        "task_status": "FAILED",
                        "code": "InvalidParameter",
                        "message": "Invalid parameter: unsupported resolution"
                      },
                      "request_id": ""
                    }
                  },
                  "cancelled": {
                    "summary": "Task cancelled",
                    "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": "Pass the ModelVerse API Key in the request Header (`Authorization: Bearer <api_key>`).\n"
      }
    },
    "schemas": {
      "Wan30SubmitRequest": {
        "type": "object",
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "Model name",
            "enum": [
              "wan3.0-video",
              "wan3.0-video-prime"
            ],
            "example": "wan3.0-video"
          },
          "input": {
            "type": "object",
            "required": [
              "prompt"
            ],
            "properties": {
              "prompt": {
                "type": "string",
                "description": "Text prompt describing the desired video content. Supports Chinese and English. Each character/letter counts as one character, up to 20000 characters. Excess will be automatically truncated.\nIn full reference mode, you can use \"image1\", \"video1\", etc. in the prompt to refer to corresponding media assets in the media array.\n",
                "maxLength": 20000,
                "example": "A cute orange cat running on the grass, sunny day, high quality"
              },
              "media": {
                "type": "array",
                "description": "Media resource array. Task types are automatically recognized through the type field:\n- Text-to-video: Leave empty or use empty array\n- Image-to-video: [{type: \"first_frame\", url: \"...\"}]\n- End-frame generation: [{type: \"first_frame\", url: \"...\"}, {type: \"last_frame\", url: \"...\"}]\n- Reference-to-video: [{type: \"reference_image\", url: \"...\"}]\n- Audio-driven: [{type: \"first_frame\", url: \"...\"}, {type: \"reference_audio\", url: \"...\"}]\n- Web link: [{type: \"link\", url: \"...\"}]\n\n**Important**: reference_xx/file/link types and first_frame/last_frame types are mutually exclusive and cannot be mixed in the same request.\n",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string",
                      "enum": [
                        "first_frame",
                        "last_frame",
                        "reference_image",
                        "reference_video",
                        "reference_audio",
                        "file",
                        "link"
                      ],
                      "description": "Media type:\n- first_frame: First frame image, max 1, strictly used as the first frame of the video\n- last_frame: Last frame image, max 1, strictly used as the last frame of the video\n- reference_image: Reference image, max 10\n- reference_video: Reference video, max 5 segments, total duration not exceeding 15 seconds\n- reference_audio: Reference audio, max 5 segments, total duration not exceeding 15 seconds\n- file: File, max 1, cannot be used with link\n- link: Web link, max 1, cannot be used with file\n"
                    },
                    "url": {
                      "type": "string",
                      "description": "Media material URL or Base64 encoded data.\n\n**For images** (type=first_frame / last_frame / reference_image)\n- Format: JPEG, JPG, PNG (no transparency), BMP, WEBP\n- Resolution:单边 [240, 8000] pixels\n- Aspect ratio: Not exceeding 8:1\n- File size: Not exceeding 20MB\n- Supported formats: Public URL (http/https), temporary URL (oss://), Base64 encoded (data:image/png;base64,...)\n\n**For videos** (type=reference_video)\n- Format: mp4, mov\n- Duration:单个 [1, 15] seconds, total duration not exceeding 15 seconds\n- Resolution:单边 [240, 4096] pixels\n- Aspect ratio: Not exceeding 8:1\n- Single file size: Not exceeding 100MB\n- Supported formats: Public URL (http/https), temporary URL (oss://)\n\n**For audio** (type=reference_audio)\n- Format: wav, mp3\n- Duration:单个 [1, 15] seconds, total duration not exceeding 15 seconds\n- File size: Not exceeding 15MB\n- Supported formats: Public URL (http/https), temporary URL (oss://)\n\n**For files** (type=file)\n- Format: docx, doc, xlsx, xls, pptx, ppt, pdf, txt, key, pages, numbers, md\n- File size: Not exceeding 100MB\n- Page limit: Not exceeding 50 pages (for pdf, docx, doc, pptx, ppt, key, pages)\n- Supported formats: Public URL (http/https), temporary URL (oss://)\n\n**For web links** (type=link)\n- Public web page URL, only supports parsing public pages that don't require login (such as news, blogs, public accounts, etc.)\n- Supported formats: Public URL (http/https)\n"
                    }
                  }
                }
              }
            }
          },
          "parameters": {
            "type": "object",
            "properties": {
              "resolution": {
                "type": "string",
                "description": "Output video resolution level",
                "enum": [
                  "480P",
                  "720P",
                  "1080P"
                ],
                "default": "1080P",
                "example": "720P"
              },
              "ratio": {
                "type": "string",
                "description": "Video aspect ratio",
                "enum": [
                  "adaptive",
                  "16:9",
                  "9:16",
                  "1:1",
                  "4:3",
                  "3:4"
                ],
                "default": "adaptive",
                "example": "16:9"
              },
              "duration": {
                "type": "integer",
                "description": "Generated video duration in seconds. Default is 5.\n- Without video input: Integer in range [2, 30]\n- With video input: Input video total duration + output video duration not exceeding 30 seconds\n",
                "default": 5,
                "example": 10
              },
              "audio": {
                "type": "boolean",
                "description": "Whether the output video includes audio.\n- true: Output video includes sound\n- false: Default, output video without audio track\nSame price for enabling/disabling sound\n",
                "default": false,
                "example": false
              },
              "seed": {
                "type": "integer",
                "description": "Random seed for reproducible generation results",
                "minimum": 0,
                "maximum": 2147483647,
                "example": 42
              },
              "prompt_extend": {
                "type": "boolean",
                "description": "Whether to enable prompt intelligent rewriting. When enabled, the large model will intelligently rewrite the input prompt.\nSignificant improvement for shorter prompts, but increases processing time.\n- true: Default, enable intelligent rewriting\n- false: Do not enable intelligent rewriting\n",
                "default": true,
                "example": true
              },
              "watermark": {
                "type": "boolean",
                "description": "Whether to add watermark.\n- false: Default, no watermark\n- true: Add watermark\n",
                "default": false,
                "example": false
              }
            }
          }
        }
      },
      "Wan30SubmitResponse": {
        "type": "object",
        "properties": {
          "output": {
            "type": "object",
            "properties": {
              "task_id": {
                "type": "string",
                "description": "Task ID for subsequent queries",
                "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "Request ID for issue tracking",
            "example": "req-1234567890abcdef"
          }
        }
      },
      "Wan30StatusResponse": {
        "type": "object",
        "properties": {
          "output": {
            "type": "object",
            "properties": {
              "task_id": {
                "type": "string",
                "description": "Task ID",
                "example": "f0024590-b898-4418-9468-d4ddb076f9e8"
              },
              "task_status": {
                "type": "string",
                "enum": [
                  "PENDING",
                  "RUNNING",
                  "Success",
                  "FAILED",
                  "CANCELLED"
                ],
                "description": "Task status (Note: Success status is \"Success\" not \"SUCCEEDED\")"
              },
              "urls": {
                "type": "array",
                "description": "List of generated video URLs (returned when task is successful)",
                "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": "Submission timestamp (Unix timestamp)",
                "example": 1787558473
              },
              "finish_time": {
                "type": "integer",
                "description": "Completion timestamp (Unix timestamp)",
                "example": 1787558593
              },
              "code": {
                "type": "string",
                "description": "Error code (returned when task fails)",
                "example": "InvalidParameter"
              },
              "message": {
                "type": "string",
                "description": "Error message (returned when task fails)",
                "example": "Invalid parameter: unsupported resolution"
              }
            }
          },
          "usage": {
            "type": "object",
            "description": "Usage information (for billing)",
            "properties": {
              "prompt_tokens": {
                "type": "integer",
                "example": 0
              },
              "completion_tokens": {
                "type": "integer",
                "example": 0
              },
              "total_tokens": {
                "type": "integer",
                "example": 0
              },
              "duration": {
                "type": "integer",
                "description": "Video duration (seconds)",
                "example": 10
              },
              "input_video_duration": {
                "type": "integer",
                "description": "Input video duration (seconds)",
                "example": 5
              },
              "output_video_duration": {
                "type": "integer",
                "description": "Output video duration (seconds)",
                "example": 5
              },
              "video_count": {
                "type": "integer",
                "example": 1
              },
              "SR": {
                "type": "integer",
                "description": "Resolution level (for billing)",
                "example": 720
              },
              "ratio": {
                "type": "string",
                "example": "415:554"
              }
            }
          },
          "request_id": {
            "type": "string",
            "description": "Request ID",
            "example": ""
          }
        }
      },
      "Error": {
        "type": "object",
        "description": "Error response",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "message",
              "type"
            ],
            "properties": {
              "message": {
                "type": "string",
                "description": "Error message"
              },
              "type": {
                "type": "string",
                "description": "Error type"
              },
              "param": {
                "type": "string",
                "description": "Related parameter"
              },
              "code": {
                "type": "string",
                "description": "Error code"
              }
            }
          }
        }
      }
    }
  }
}
```