> For the complete documentation index, see [llms.txt](https://docs.avis.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avis.net/vi/tai-lieu-api/endpoints/video-generation.md).

# Tạo video

Ước tính chi phí (chạy thử):

`POST /api/v1/video/estimate`

Tạo task:

`POST /api/v1/video/generations`

Đọc task:

`GET /api/v1/video/tasks/:taskId`

Quá trình tạo video hoạt động theo cơ chế task. Endpoint tạo trả về task đã được lưu ban đầu. Hãy kiểm tra endpoint task định kỳ cho đến khi `status` chuyển sang trạng thái kết thúc.

Các trạng thái kết thúc: `succeeded`, `failed`, `cancelled`.

### Các trường request

| Trường        | Kiểu      | Bắt buộc | Ràng buộc                     | Mô tả                                                                                                                                                                                                                                                                     |
| ------------- | --------- | -------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`       | string    | Có       | Độ dài tối thiểu `1`          | Mã định danh mô hình dành cho người dùng, lấy từ `/ai/models`.                                                                                                                                                                                                            |
| `content`     | object\[] | Có       | Mảng không rỗng               | Các đầu vào văn bản, hình ảnh và video theo thứ tự. Với tạo video từ khung hình đầu/cuối, thứ tự và `role` của hình ảnh rất quan trọng.                                                                                                                                   |
| `duration`    | integer   | Không    | Số nguyên dương               | Thời lượng mong muốn tính bằng giây. Khoảng/bước cho phép khác nhau theo từng mô hình — hãy đọc `capabilities.video.params.duration` từ `GET /ai/models` cho mô hình được chọn trước khi gửi; xem Cấu trúc giá trị của `capabilities.params`.                             |
| `resolution`  | string    | Không    | `480p`, `720p`, `1080p`, `4k` | Token độ phân giải. Giá trị cho phép khác nhau theo từng mô hình — hãy đọc `capabilities.video.params.resolution` từ `GET /ai/models` cho mô hình được chọn.                                                                                                              |
| `ratio`       | string    | Không    | Chuỗi                         | Token tỷ lệ khung hình, ví dụ `16:9`, `9:16` hoặc `adaptive`. Chuỗi mở; giá trị cho phép khác nhau theo từng mô hình — hãy đọc `capabilities.video.params.ratio` từ `GET /ai/models` cho mô hình được chọn. Được chuyển tiếp tới cả adapter video BytePlus và OpenRouter. |
| `seed`        | integer   | Không    | Số nguyên, tối thiểu `-1`     | Seed để tái tạo kết quả. Cùng một seed cho ra kết quả tương tự - không đảm bảo giống hệt. Mức hỗ trợ và phạm vi khác nhau theo mô hình.                                                                                                                                   |
| `watermark`   | boolean   | Không    | Boolean                       | Thêm watermark "AI Generated" ở góc dưới bên phải khi mô hình hỗ trợ.                                                                                                                                                                                                     |
| `cameraFixed` | boolean   | Không    | Boolean                       | Thêm chỉ dẫn cố định camera vào prompt. Mức hỗ trợ khác nhau theo mô hình; gửi trường này tới mô hình không hỗ trợ sẽ trả về mã lỗi Bad request `400`.                                                                                                                    |
| `maxTokens`   | integer   | Không    | Số nguyên dương               | DTO chấp nhận trường này, nhưng các adapter video BytePlus và OpenRouter hiện tại sẽ từ chối với lỗi `400` vì tạo video không hỗ trợ `maxTokens`.                                                                                                                         |

### Các content part của video

| Loại          | Trường                                                | Mô tả                                                                                  |
| ------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `text`        | `text: string`                                        | Văn bản prompt.                                                                        |
| `imageUrl`    | `url: string`, `role?: string`                        | URL hình ảnh công khai. `role` tùy chọn quy định cách hình ảnh được sử dụng.           |
| `imageBase64` | `data: string`, `mediaType?: string`, `role?: string` | Dữ liệu hình ảnh base64 thô hoặc data URL. `mediaType` là bắt buộc với base64 thô.     |
| `videoUrl`    | `url: string`                                         | URL video công khai. DTO chấp nhận; mức hỗ trợ của nhà cung cấp có thể khác nhau.      |
| `videoBase64` | `data: string`, `mediaType?: string`                  | Dữ liệu video base64 thô hoặc data URL đầy đủ. `mediaType` là bắt buộc với base64 thô. |

> **Không hỗ trợ tải tệp lên.** Hãy cung cấp media dưới dạng URL công khai (`imageUrl`, `videoUrl`) hoặc base64 nội tuyến (`imageBase64`, `videoBase64`). Không có cách nào để tải tệp lên một lần rồi dùng lại sau — mọi request đều phải chứa đầy đủ URL hoặc dữ liệu base64.

Các giá trị `role` của hình ảnh:

| Giá trị          | Mô tả                                                                        |
| ---------------- | ---------------------------------------------------------------------------- |
| `firstFrame`     | Dùng hình ảnh làm khung hình đầu/keyframe.                                   |
| `lastFrame`      | Dùng hình ảnh làm khung hình cuối/keyframe.                                  |
| `referenceImage` | Dùng hình ảnh làm tham chiếu hình ảnh. Đây là giá trị mặc định khi bỏ trống. |

### Ước tính chi phí

Gửi đúng body dự định dùng cho endpoint tạo video đến `POST /api/v1/video/estimate` để xem trước chi phí. Request ước tính không trừ credit và không lưu dữ liệu.

> **Lưu ý:** Chi phí trả về chỉ là ước tính. Số tiền thực tế có thể khác và chỉ được xác định sau khi quá trình tạo hoàn tất.

#### Ví dụ request

```
POST /api/v1/video/estimate
```

```json
{
  "model": "wan-2-6",
  "content": [
    { "type": "text", "text": "Smooth interpolation between the two frames" },
    {
      "type": "imageUrl",
      "url": "https://example.com/first.jpeg",
      "role": "firstFrame"
    },
    {
      "type": "imageUrl",
      "url": "https://example.com/last.jpeg",
      "role": "lastFrame"
    }
  ],
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9"
}
```

#### Các trường response

| Trường              | Kiểu   | Mô tả                                                                                      |
| ------------------- | ------ | ------------------------------------------------------------------------------------------ |
| `estimatedUserCost` | number | Chi phí ước tính bằng USD. Khớp với số tiền sẽ được tạm giữ bởi `POST /video/generations`. |
| `currency`          | string | Luôn là `"USD"`.                                                                           |

#### Ví dụ response

```json
{
  "data": {
    "estimatedUserCost": 0.51,
    "currency": "USD"
  },
  "success": true,
  "status": 200
}
```

Nếu mức chi phí ước tính phù hợp, hãy gửi cùng body đó đến `POST /api/v1/video/generations` để tạo task.

### Ví dụ request tạo video

```
POST /api/v1/video/generations
```

```json
{
  "model": "wan-2-6",
  "content": [
    { "type": "text", "text": "Smooth interpolation between the two frames" },
    {
      "type": "imageUrl",
      "url": "https://example.com/first.jpeg",
      "role": "firstFrame"
    },
    {
      "type": "imageUrl",
      "url": "https://example.com/last.jpeg",
      "role": "lastFrame"
    }
  ],
  "duration": 5,
  "resolution": "720p",
  "ratio": "16:9",
  "seed": 42
}
```

### Các trường của VideoTask

| Trường                   | Kiểu      | Bắt buộc | Mô tả                                                                                                             |
| ------------------------ | --------- | -------- | ----------------------------------------------------------------------------------------------------------------- |
| `taskId`                 | string    | Có       | ID task do nhà cung cấp cấp. Dùng với `GET /video/tasks/:taskId`.                                                 |
| `generationId`           | string    | Có       | ID bản ghi generation liên kết với task này.                                                                      |
| `providerId`             | string    | Có       | ID ổn định của nhà cung cấp mà task thuộc về.                                                                     |
| `status`                 | string    | Có       | Trạng thái hiện tại của task: `queued`, `running`, `succeeded`, `failed` hoặc `cancelled`.                        |
| `model`                  | string    | Có       | Mã định danh mô hình dành cho người dùng được dùng trong request.                                                 |
| `content`                | object\[] | Có       | Nội dung request gốc theo thứ tự, được lưu cùng task. Giá trị base64 bị cắt ngắn trước khi lưu vào cơ sở dữ liệu. |
| `videoUrl`               | string    | Không    | URL của video được tạo. Với một số nhà cung cấp, đây có thể là URL proxy của API hoặc URL đã ký của bản lưu trữ.  |
| `downloadUrl`            | string    | Không    | Link tải xuống R2 đã ký sẵn cho đầu ra được lưu trữ. URL này có thời hạn; hãy lấy lại thay vì lưu vĩnh viễn.      |
| `assetId`                | string    | Không    | ID tài nguyên của đầu ra được lưu trữ. Dùng lại qua `videoAssetId` trong các request sau.                         |
| `usage`                  | object    | Không    | Mức sử dụng do nhà cung cấp báo cáo.                                                                              |
| `usage.completionTokens` | number    | Không    | Số token được tạo ra trong completion, nếu được báo cáo.                                                          |
| `usage.totalTokens`      | number    | Không    | Tổng số token đã tiêu thụ, nếu được báo cáo.                                                                      |
| `usage.usdCost`          | number    | Không    | Chi phí USD do nhà cung cấp báo cáo, khi nhà cung cấp có báo cáo số liệu thanh toán.                              |
| `usage.durationSeconds`  | number    | Không    | Thời lượng video đầu ra tính bằng giây, với các nhà cung cấp tính phí theo giây.                                  |
| `usage.providerUsage`    | object    | Không    | Toàn bộ payload mức sử dụng của nhà cung cấp (cấu trúc riêng theo nhà cung cấp/mô hình).                          |
| `error`                  | string    | Không    | Thông báo lỗi khi `status` là `failed`.                                                                           |
| `createdAt`              | string    | Không    | Thời điểm tạo task.                                                                                               |
| `updatedAt`              | string    | Không    | Thời điểm cập nhật task gần nhất.                                                                                 |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.avis.net/vi/tai-lieu-api/endpoints/video-generation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.