# HappyHorse-1.0-R2V

Reference-to-Video Model

## Submit Async Task

### Endpoint

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

### Input

| Parameter             | Type     | Required | Description |
| :-------------------- | :------- | :------- | :---------- |
| model                 | string   | Yes      | Model name, here it is `happyhorse-1.0-r2v` |
| input.prompt          | string   | Yes      | Text prompt. Use `character1`, `character2`, etc. to refer to the corresponding reference images in `input.images` by order |
| input.images          | string[] | Yes      | List of reference image URLs, supports 1 to 9 images |
| parameters.resolution | string   | No       | Resolution level of the generated video. Options: `720P`, `1080P`. Default: `1080P` |
| parameters.ratio      | string   | No       | Aspect ratio of the generated video. Options: `16:9`, `9:16`, `1:1`. Default: `16:9` |
| parameters.duration   | int      | No       | Video duration in seconds, range `3` to `15`. Default: `5` |
| parameters.watermark  | boolean  | No       | Whether to add a watermark. Default: `true` |
| parameters.seed       | int      | No       | Random seed, range `[0, 2147483647]` |

### Request Example

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

```shell
curl --location --globoff 'https://api-us-ca.umodelverse.ai/v1/tasks/submit' \
--header 'Authorization: Bearer <YOUR_API_KEY>' \
--header 'X-DashScope-Async: enable' \
--header 'Content-Type: application/json' \
--data '{
    "model": "happyhorse-1.0-r2v",
    "input": {
      "prompt": "character1 holds character2 and showcases the product details in front of the camera.",
      "images": [
        "https://example.com/person.jpg",
        "https://example.com/product.jpg"
      ]
    },
    "parameters": {
      "resolution": "720P",
      "ratio": "16:9",
      "duration": 5
    }
  }'
```

### Output

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

## 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: Bearer <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 returned upon failure                      |
| usage.duration              | integer | Billed video duration (seconds)                          |
| usage.output_video_duration | number  | Output video duration (seconds)                          |
| usage.video_count           | integer | Number of output videos                                  |
| usage.SR                    | integer | Output video resolution height, e.g. `720`, `1080`       |
| usage.ratio                 | string  | Output video aspect ratio                                |
| request_id                  | string  | Unique identifier of the request                         |