# Vidu / One-Click MV

One-click MV generation

## Submit Async Task

### Endpoint

`https://api-us-ca.umodelverse.ai/v1/tasks/submit`

### Input

| Parameter | Type | Required | Description |
| :-------- | :---- | :-------- | :----------- |
| model | string | Yes | Model name.<br>For domestic users: `vidu-mv`<br>For international users: `vidu-one-click-mv` |
| input.images | Array[String] | Yes | Model or style images used for MV generation<br>Note 1: Supports Base64 or image URL (must be accessible)<br>Note 2: Supports 1–7 images<br>Note 3: Formats: png, jpeg, jpg, webp<br>Note 4: Aspect ratio must be within 1:4 to 4:1<br>Note 5: Max size per image ≤ 50MB<br>Note 6: HTTP POST body ≤ 20MB, must include proper content type, e.g.:<br>`data:image/png;base64,{base64_encode}` |
| input.audio_url | string | Yes | Audio for MV generation<br>Note 1: Supports Base64 or URL (must be accessible)<br>Note 2: Only one audio input supported<br>Note 3: Formats: mp3, wav, aac, m4a<br>Note 4: Duration: 10–180 seconds<br>Note 5: HTTP POST body ≤ 20MB, must include proper content type, e.g.:<br>`data:audio/mp3;base64,{base64_encode}` |
| input.prompt | string | No | Prompt text describing the MV content<br>Note: Max length ≤ 3000 characters |
| parameters.vidu_type | string | Yes | Vidu API type, must be `one-click/mv` |
| parameters.aspect_ratio | string | No | Output aspect ratio, default 16:9<br>Options: 1:1, 16:9, 9:16, 4:3, 3:4 |
| parameters.resolution | string | No | Resolution, default 720p<br>Options: 540p, 720p, 1080p |
| parameters.add_subtitle | bool | No | Whether to add subtitles, default false<br>true: add subtitles<br>false: no subtitles |
| parameters.language | string | No | Audio language, default auto<br>Options: en, zh |
| parameters.srt_url | string | No | Subtitle file URL |

### Request Example

⚠️ If you are using Windows, it is recommended to use Postman or another API client tool.

```shell
curl --location --globoff 'https://api-us-ca.umodelverse.ai/v1/tasks/submit' \
--header 'Authorization: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "model": "vidu-mv",
    "input": {
        "images": ["https://xxxxxxxxx/image2video.png"],
        "prompt": "The person in the image is wandering on the road.",
        "audio_url": "https://xxxxxxxxx/49ab8a8f-f564-4b96-80a2-b38cca527475.mp3"
    },
    "parameters": {
      "vidu_type": "one-click/mv",
      "aspect_ratio": "16:9",
      "resolution": "540p",
      "add_subtitle": true,
      "language": "en",
      "srt_url": "https://xxxxxxxxx/mv_subtitle.srt"
    }
  }'
```

### Output

| Parameter      | Type   | Description                         |
| :------------- | :----- | :---------------------------------- |
| output.task_id | string | Unique identifier of the async task |
| request_id     | string | Unique request identifier           |

### Response Example

```json
{
  "output": {
    "task_id": "task_id"
  },
  "request_id": "request_id"
}
```

## Query Task Status

### Endpoint

`https://api-us-ca.umodelverse.ai/v1/tasks/status?task_id=<task_id>`

### Request Example

```shell
curl --location 'https://api-us-ca.umodelverse.ai/v1/tasks/status?task_id=<task_id>' \
--header 'Authorization: <YOUR_API_KEY>'
```

### Output

| Parameter            | Type    | Description                                             |
| :------------------- | :------ | :------------------------------------------------------ |
| output.task_id       | string  | Unique identifier of the async task                     |
| output.task_status   | string  | Task status: `Pending`, `Running`, `Success`, `Failure` |
| output.urls          | array   | List of video result URLs                               |
| output.submit_time   | integer | Task submission timestamp                               |
| output.finish_time   | integer | Task completion timestamp                               |
| output.error_message | string  | Error message when failed                               |
| usage.duration       | integer | Video duration (seconds)                                |
| request_id           | string  | Unique request identifier                               |

### Response Example (Success)

```json
{
  "output": {
    "task_id": "task_id",
    "task_status": "Success",
    "urls": ["https://xxxxx/xxxx-mv.mp4"],
    "submit_time": 1756959000,
    "finish_time": 1756959050
  },
  "usage": {
    "duration": 30
  },
  "request_id": ""
}
```

### Response Example (Failure)

```json
{
  "output": {
    "task_id": "task_id",
    "task_status": "Failure",
    "submit_time": 1756959000,
    "finish_time": 1756959019,
    "error_message": "error_message"
  },
  "usage": {
    "duration": 5
  },
  "request_id": ""
}
```