# Vidu/Reference2Video

Reference-to-Video Model

## Asynchronous Task Submission

### API

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

### Input

| Parameter                    | Type     | Required | Description                                                                                          |
| :--------------------------- | :------- | :------- | :--------------------------------------------------------------------------------------------------- |
| model                        | string   | Yes      | Model name, options: `viduq2`                                                                        |
| input.images                 | []string | Yes      | Array of reference images, viduq2/viduq1 supports 1-7 images, vidu2.0/vidu1.5 supports 1-3 images, supports image URL or Base64 encoding   |
| input.prompt                 | string   | Yes      | Text prompt to guide video generation, up to 2000 characters                                          |
| parameters.vidu_type         | string   | Yes      | Vidu API type, here is `reference2video`                                                             |
| parameters.duration          | int      | No       | Video duration parameter, default value depends on the model: <br> viduq2: default 5 seconds, options: 1-10                                 |
| parameters.seed              | int      | No       | Random seed, default 0 indicates using random numbers                                                |
| parameters.aspect_ratio      | string   | No       | Aspect ratio, options: `16:9`,`9:16`,`4:3`,`3:4`,`1:1`, default `16:9`, note: 4:3, 3:4 only supported by q2                                |
| parameters.resolution        | string   | No       | Resolution parameter, default value depends on model and video length: <br> viduq2 (1-8 seconds): default 720p, options: 540p, 720p, 1080p |
| parameters.movement_amplitude| string   | No       | Movement amplitude, options: `auto`,`small`,`medium`,`large`, default `auto`, note: q2 model does not support this parameter              |
| parameters.bgm               | bool     | No       | Whether to add background music, default `false`                                                     |

**Note:** 
- viduq2/viduq1 models support 1-7 reference images
- vidu2.0/vidu1.5 models support 1-3 reference images
- The model will generate a video with a consistent main subject based on the theme in the reference images
- Images supported in png, jpeg, jpg, webp formats
- Image pixels must be no less than 128×128
- Image ratio needs to be less than 1:4 or 4:1
- Image size must not exceed 50 MB
- Base64 encoded format example: `data:image/png;base64,{base64_encode}`

### Request Example

⚠️ If you are using Windows, it is recommended to use Postman or other API calling tools.

```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": "viduq2",
    "input": {
      "images": [
        "https://umodelverse-inference.cn-wlcb.ufileos.com/ucloud-maxcot.jpg",
      ],
      "prompt": "make it dance."
    },
    "parameters": {
      "vidu_type": "reference2video",
      "duration": 5,
      "aspect_ratio": "16:9",
      "resolution": "720p",
      "movement_amplitude": "auto",
      "bgm": true
    }
  }'
```

### Output

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

### Response Example

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

## Task Status Check

### API

`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 asynchronous 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 returned upon failure                   |
| usage.duration          | integer | Video duration (seconds)                              |
| request_id              | string  | Unique identifier of the request                      |

### Response Example

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