# Veo-3.1

Text & Image-to-Video Model

## Submit Task (Asynchronous)

### Endpoint

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

### Input

| Parameter                        | Type   | Required | Description |
| :------------------------------- | :----- | :------- | :---------- |
| model                            | string | Yes      | Model name, here it is `veo-3.1-generate-001` or `veo-3.1-fast-generate-001` |
| input.prompt                     | string | Yes      | Prompt used to guide video generation |
| input.negative_prompt            | string | No       | Negative prompt used to restrict undesired content |
| input.image                      | object | No       | Image object used to guide video generation. If `last_frame` is included, `image` represents the first frame |
| input.image.bytesBase64Encoded   | string | No       | Base64-encoded image bytes. Must be raw Base64 string without prefix like `data:image/jpeg;base64,` |
| input.image.mimeType             | string | No       | Image MIME type. Only accepts:<br>`image/jpeg`<br>`image/png`<br>`image/webp` |
| input.last_frame                 | object | No       | End frame image object used to guide video generation |
| input.last_frame.bytesBase64Encoded | string | No    | Base64-encoded image bytes. Must be raw Base64 string without prefix like `data:image/jpeg;base64,` |
| input.last_frame.mimeType        | string | No       | Image MIME type. Only accepts:<br>`image/jpeg`<br>`image/png`<br>`image/webp` |
| parameters.resolution            | string | No       | Output video resolution. Acceptable values: `720p` (default) or `1080p` |
| parameters.duration              | int    | No       | Video duration (seconds). Supported values: `4`, `6`, `8`. Default is `8` |
| parameters.aspect_ratio          | int    | No       | Output video aspect ratio. Acceptable values:<br>`16:9`<br>`9:16`<br>Default is `16:9` |
| parameters.generate_audio        | bool   | Yes      | Required parameter. Whether to generate audio. Acceptable values: `true` or `false` |
| parameters.person_generation     | string | No       | Safety control for generating people/faces. Options:<br>`allow_adult` (default): only allow adult generation<br>`dont_allow`: prohibit people/faces in the output |

### Request Example

⚠️ If you are using Windows, it is recommended to use Postman or other API 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": "veo-3.1-generate-001",
    "input": {
      "prompt": "make it run",
      "image": {
        "bytesBase64Encoded": "xxxxx",
        "mimeType": "image/jpeg"
      },
      "last_frame": {
        "bytesBase64Encoded": "xxxxx",
        "mimeType": "image/jpeg"
      }
    },
    "parameters": {
      "duration": 6,
      "aspect_ratio": "16:9",
      "resolution": "1080p",
      "generate_audio": true
    }
  }'
```

### Output

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

### 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. Retained for 24 hours by default, please download in time |
| output.submit_time   | integer | Task submission timestamp                                                            |
| output.finish_time   | integer | Task completion timestamp                                                            |
| output.error_message | string  | Error message returned when failed                                                   |
| usage.duration       | integer | Task execution duration (seconds)                                                    |
| request_id           | string  | Unique identifier of the request                                                     |

### Response Example (Success)

```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": ""
}
```

### 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": ""
}
```