# Wan2.7 Reference-to-Video Task Status

> Video Generation

Query asynchronous task status. When the task is complete, the response will include result URLs, usage information, or error messages.

## Endpoint

`GET https://api.modelverse.cn/v1/tasks/status`

## Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| task_id | query | string | Yes | Asynchronous task ID returned by `/v1/tasks/submit`. |

## Responses

- **200** — Task status query successful.
- **400** — Invalid request parameters.
- **default** — Error response.

## OpenAPI Definition

```json
{
  "openapi": "3.1.0",
  "x-language": "en-US",
  "info": {
    "title": "ModelVerse Wan2.7-R2V Reference-to-Video API",
    "version": "1.0.0",
    "description": "This is the reference-to-video API documentation for `wan2.7-r2v` on ModelVerse, describing how to submit generation tasks, query task status, retrieve video results, and handle errors.\nAPI paths include `POST /v1/tasks/submit` and `GET /v1/tasks/status`.\n"
  },
  "servers": [
    {
      "url": "https://api.modelverse.cn",
      "description": "ModelVerse API endpoint documented for this model."
    }
  ],
  "tags": [
    {
      "name": "wan2.7-r2v",
      "description": "Reference-to-video asynchronous task operations."
    }
  ],
  "paths": {
    "/v1/tasks/submit": {
      "post": {
        "tags": [
          "wan2.7-r2v"
        ],
        "operationId": "submitWan27R2VTask",
        "summary": "Wan2.7 Reference-to-Video",
        "description": "Submit an asynchronous task. The model and parameters in the request body should be filled according to this API documentation, and the response will return a task ID.\nWan2.7-R2V supports generating high-quality videos from reference images and videos, preserving character appearance and sound consistency.\nVideo generation tasks take 1-5 minutes, and the API uses asynchronous calls.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Wan27R2VSubmitRequest"
              },
              "examples": {
                "multiSubjectReference": {
                  "summary": "Multi-subject reference (Image+Video+Audio)",
                  "value": {
                    "model": "wan2.7-r2v",
                    "input": {
                      "prompt": "Video 1 holds Image 3 and plays a soothing country folk song...",
                      "media": [
                        {
                          "type": "reference_image",
                          "url": "https://example.com/girl.jpg",
                          "reference_voice": "https://example.com/girl-voice.mp3"
                        },
                        {
                          "type": "reference_video",
                          "url": "https://example.com/boy.mp4",
                          "reference_voice": "https://example.com/boy-voice.mp3"
                        },
                        {
                          "type": "reference_image",
                          "url": "https://example.com/object3.png"
                        },
                        {
                          "type": "reference_image",
                          "url": "https://example.com/background5.png"
                        }
                      ]
                    },
                    "parameters": {
                      "resolution": "720P",
                      "ratio": "16:9",
                      "duration": 10,
                      "prompt_extend": false,
                      "watermark": true
                    }
                  }
                },
                "multiPanelStoryboard": {
                  "summary": "Multi-panel storyboard reference",
                  "value": {
                    "model": "wan2.7-r2v",
                    "input": {
                      "prompt": "Based on the reference image, in the style of a 3D cartoon adventure movie...",
                      "media": [
                        {
                          "type": "reference_image",
                          "url": "https://example.com/storyboard.png"
                        }
                      ]
                    },
                    "parameters": {
                      "resolution": "720P",
                      "ratio": "16:9",
                      "duration": 10,
                      "prompt_extend": false,
                      "watermark": true
                    }
                  }
                },
                "withFirstFrame": {
                  "summary": "First-frame control + reference image",
                  "value": {
                    "model": "wan2.7-r2v",
                    "input": {
                      "prompt": "The cat from Image 1 is playing in the garden...",
                      "media": [
                        {
                          "type": "first_frame",
                          "url": "https://example.com/first-frame.png"
                        },
                        {
                          "type": "reference_image",
                          "url": "https://example.com/cat.jpg"
                        }
                      ]
                    },
                    "parameters": {
                      "resolution": "1080P",
                      "ratio": "16:9",
                      "duration": 5,
                      "prompt_extend": true,
                      "watermark": false
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Task submitted successfully.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Wan27R2VSubmitResponse"
                },
                "examples": {
                  "submitted": {
                    "summary": "Submitted task",
                    "value": {
                      "output": {
                        "task_id": "task_xxxxxxxxxxxxx",
                        "task_status": "PENDING"
                      },
                      "request_id": "req_xxxxxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Wan27R2VErrorResponse"
                },
                "examples": {
                  "paramError": {
                    "$ref": "#/components/examples/Wan27R2VParamError"
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Wan27R2VErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/Wan27R2VParamError"
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/tasks/status": {
      "get": {
        "tags": [
          "wan2.7-r2v"
        ],
        "operationId": "getWan27R2VTaskStatus",
        "summary": "Wan2.7 Reference-to-Video Task Status",
        "description": "Query asynchronous task status. When the task is complete, the response will include result URLs, usage information, or error messages.\n",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "parameters": [
          {
            "name": "task_id",
            "in": "query",
            "required": true,
            "description": "Asynchronous task ID returned by `/v1/tasks/submit`.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Task status query successful.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Wan27R2VStatusResponse"
                },
                "examples": {
                  "succeeded": {
                    "summary": "Task succeeded",
                    "value": {
                      "output": {
                        "task_id": "task_xxxxxxxxxxxxx",
                        "task_status": "SUCCEEDED",
                        "urls": [
                          "https://example.com/video.mp4"
                        ],
                        "submit_time": 1756959000,
                        "finish_time": 1756959050
                      },
                      "usage": {
                        "duration": 5
                      },
                      "request_id": "req_xxxxxxxxxxxxx"
                    }
                  },
                  "failed": {
                    "summary": "Task failed",
                    "value": {
                      "output": {
                        "task_id": "task_xxxxxxxxxxxxx",
                        "task_status": "FAILED",
                        "error_message": "Invalid parameter: input.media"
                      },
                      "usage": {
                        "duration": 0
                      },
                      "request_id": "req_xxxxxxxxxxxxx"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Wan27R2VErrorResponse"
                },
                "examples": {
                  "paramError": {
                    "$ref": "#/components/examples/Wan27R2VParamError"
                  }
                }
              }
            }
          },
          "default": {
            "description": "Error response.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Wan27R2VErrorResponse"
                },
                "examples": {
                  "error": {
                    "$ref": "#/components/examples/Wan27R2VParamError"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Wan27R2VSubmitRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "model",
          "input"
        ],
        "properties": {
          "model": {
            "type": "string",
            "description": "Model name, fixed as `wan2.7-r2v`.",
            "enum": [
              "wan2.7-r2v"
            ]
          },
          "input": {
            "$ref": "#/components/schemas/Wan27R2VInput"
          },
          "parameters": {
            "$ref": "#/components/schemas/Wan27R2VParameters"
          }
        }
      },
      "Wan27R2VInput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "prompt"
        ],
        "properties": {
          "prompt": {
            "type": "string",
            "description": "Text description of the video to be generated. Supports natural language or multi-shot script format.\nSupports referencing subjects in the media list using Image N, Video N format.\n"
          },
          "media": {
            "type": "array",
            "description": "Reference media list (optional). Supports images and videos for character and style reference.\n",
            "items": {
              "$ref": "#/components/schemas/Wan27R2VMediaItem"
            }
          }
        }
      },
      "Wan27R2VMediaItem": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "type",
          "url"
        ],
        "properties": {
          "type": {
            "type": "string",
            "description": "Media type. Supported types:\n- `reference_image`: Reference image, used for character/style reference\n- `reference_video`: Reference video, used for character/video reference\n- `first_frame`: First frame control, used to specify the first frame of the video\n",
            "enum": [
              "reference_image",
              "reference_video",
              "first_frame"
            ]
          },
          "url": {
            "type": "string",
            "format": "uri",
            "description": "Media file URL. Supported formats: JPG, PNG, MP4.\nFor video type, maximum 10 seconds.\n"
          },
          "reference_voice": {
            "type": "string",
            "format": "uri",
            "description": "Reference voice file URL (optional). Used when type is `reference_image` or `reference_video`.\nSupports audio-driven generation, where the generated character's mouth movements will sync with this audio.\nSupports MP3, WAV formats, maximum 10 seconds.\n"
          }
        }
      },
      "Wan27R2VParameters": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "resolution": {
            "type": "string",
            "description": "Output video resolution. Supported values: 480P, 720P, 1080P.\nNote: The higher the resolution, the longer the generation time and the higher the cost.\n",
            "enum": [
              "480P",
              "720P",
              "1080P"
            ],
            "default": "720P"
          },
          "ratio": {
            "type": "string",
            "description": "Output video aspect ratio. Supported values: 16:9, 9:16, 1:1, 4:3, 3:4.\n",
            "enum": [
              "16:9",
              "9:16",
              "1:1",
              "4:3",
              "3:4"
            ],
            "default": "16:9"
          },
          "duration": {
            "type": "integer",
            "description": "Generated video duration, in seconds. Supported range: 5-15 seconds.\nSupports integer values only.\n",
            "minimum": 5,
            "maximum": 15,
            "default": 5
          },
          "audio_setting": {
            "type": "string",
            "description": "Audio setting. Supported values:\n- `origin`: Keep original audio (for video editing tasks)\n- `generated`: Use AI-generated audio\n",
            "enum": [
              "origin",
              "generated"
            ]
          },
          "prompt_extend": {
            "type": "boolean",
            "description": "Whether to enable prompt extension. When enabled, the system will automatically optimize and expand the prompt for better results.\nRecommended for complex scenes.\n",
            "default": false
          },
          "watermark": {
            "type": "boolean",
            "description": "Whether to add watermark. Defaults to true.\n",
            "default": true
          }
        }
      },
      "Wan27R2VSubmitResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "output",
          "request_id"
        ],
        "properties": {
          "output": {
            "$ref": "#/components/schemas/Wan27R2VSubmitOutput"
          },
          "request_id": {
            "type": "string",
            "description": "Unique request identifier."
          }
        }
      },
      "Wan27R2VSubmitOutput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "task_id",
          "task_status"
        ],
        "properties": {
          "task_id": {
            "type": "string",
            "description": "Unique identifier of the asynchronous task. Valid for 24 hours."
          },
          "task_status": {
            "type": "string",
            "description": "Task status.",
            "enum": [
              "PENDING",
              "RUNNING",
              "SUCCEEDED",
              "FAILED",
              "CANCELED",
              "UNKNOWN"
            ]
          },
          "request_id": {
            "type": "string",
            "description": "Unique request identifier."
          }
        }
      },
      "Wan27R2VStatusResponse": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "output",
          "request_id"
        ],
        "properties": {
          "output": {
            "$ref": "#/components/schemas/Wan27R2VStatusOutput"
          },
          "usage": {
            "$ref": "#/components/schemas/Wan27R2VUsage"
          },
          "request_id": {
            "type": "string",
            "description": "Unique request identifier."
          }
        }
      },
      "Wan27R2VStatusOutput": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "task_id",
          "task_status"
        ],
        "properties": {
          "task_id": {
            "type": "string",
            "description": "Unique identifier of the asynchronous task. Valid for 24 hours."
          },
          "task_status": {
            "$ref": "#/components/schemas/Wan27R2VTaskStatus"
          },
          "urls": {
            "type": "array",
            "description": "List of video result URLs.",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "submit_time": {
            "type": "integer",
            "format": "int64",
            "description": "Unix timestamp of task submission time in seconds."
          },
          "finish_time": {
            "type": "integer",
            "format": "int64",
            "description": "Unix timestamp of task completion time in seconds."
          },
          "error_message": {
            "type": "string",
            "description": "Error message returned when task fails."
          }
        }
      },
      "Wan27R2VTaskStatus": {
        "type": "string",
        "description": "Asynchronous task status.\n- PENDING: Waiting for processing\n- RUNNING: Processing\n- SUCCEEDED: Task completed successfully\n- FAILED: Task failed\n- CANCELED: Task canceled\n- UNKNOWN: Task does not exist or status unknown\nStatus flow: PENDING -> RUNNING -> SUCCEEDED or FAILED\n",
        "enum": [
          "PENDING",
          "RUNNING",
          "SUCCEEDED",
          "FAILED",
          "CANCELED",
          "UNKNOWN"
        ]
      },
      "Wan27R2VUsage": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "duration": {
            "type": "integer",
            "description": "Task execution duration, in seconds."
          }
        }
      },
      "Wan27R2VErrorResponse": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/Wan27R2VErrorObject"
          },
          "request_id": {
            "type": "string",
            "description": "Unique request identifier, if available."
          }
        }
      },
      "Wan27R2VErrorObject": {
        "type": "object",
        "additionalProperties": true,
        "required": [
          "message",
          "type"
        ],
        "properties": {
          "message": {
            "type": "string",
            "description": "Error message."
          },
          "type": {
            "type": "string",
            "description": "Error type.",
            "examples": [
              "invalid_request_error"
            ]
          },
          "code": {
            "type": [
              "string",
              "null"
            ],
            "description": "Error code.",
            "examples": [
              "InvalidApiKey",
              "InvalidParameter"
            ]
          },
          "param": {
            "type": [
              "string",
              "null"
            ],
            "description": "Related request parameter, if any."
          }
        }
      }
    },
    "examples": {
      "Wan27R2VParamError": {
        "summary": "Invalid parameter error",
        "value": {
          "error": {
            "message": "Invalid param",
            "type": "invalid_request_error",
            "code": "InvalidParameter",
            "param": "input.media"
          },
          "request_id": "req_xxxxxxxxxxxxx"
        }
      }
    }
  }
}
```