# Tạo video Veo

Nguồn: https://docs.aicentos.com/vi/veo-video

Language: vi

> Gọi mô hình tạo video Google Veo qua aicentos — tạo video từ văn bản, từ ảnh, khung đầu - cuối, ảnh tham chiếu

Bài viết dành cho lập trình viên, hướng dẫn cách gọi mô hình tạo video Google Veo qua aicentos. API theo định dạng tương thích OpenAI Videos API; khi tích hợp phía hạ nguồn chỉ cần đặt loại channel là `openai`.

## Mô tả năng lực mô hình

Tính phí theo thời lượng tạo video (giây). Đơn giá cụ thể lấy theo Console aicentos; khoản trừ cuối cùng dựa trên bản ghi trừ phí thực tế của hệ thống.

### Năng lực chính thức và phạm vi aicentos mở

| Mô hình                         | Số giây hỗ trợ | Độ phân giải hỗ trợ | Tỷ lệ khung hình | Âm thanh        | Ghi chú                                                                                      |
| ------------------------------- | -------------- | ------------------- | ---------------- | --------------- | -------------------------------------------------------------------------------------------- |
| `veo-3.1-generate-preview`      | 4, 6, 8        | 720p, 1080p, 4k     | 16:9, 9:16       | Có sẵn âm thanh | 1080p và 4k chỉ hỗ trợ 8 giây; khi dùng ảnh tham chiếu, khung đầu - cuối... nên chọn 8 giây. |
| `veo-3.1-fast-generate-preview` | 4, 6, 8        | 720p, 1080p, 4k     | 16:9, 9:16       | Có sẵn âm thanh | 1080p và 4k chỉ hỗ trợ 8 giây; khi dùng ảnh tham chiếu, khung đầu - cuối... nên chọn 8 giây. |

Tài liệu tham khảo:

* [Google Gemini API — tạo video Veo](https://ai.google.dev/gemini-api/video)
* [Mô tả ảnh tham chiếu của Veo](https://ai.google.dev/gemini-api/video#reference_images)
* [Mô tả khung đầu - cuối của Veo](https://ai.google.dev/gemini-api/video#first_and_last_frame)
* [Mô tả tỷ lệ khung hình của Veo](https://ai.google.dev/gemini-api/video#aspect_ratio)

### Tỷ lệ khung hình

| Mô hình                         | 16:9 ngang | 9:16 dọc | Tỷ lệ mặc định | Khuyến nghị                                                |
| ------------------------------- | ---------- | -------- | -------------- | ---------------------------------------------------------- |
| `veo-3.1-generate-preview`      | Hỗ trợ     | Hỗ trợ   | 16:9           | 4K bắt buộc dùng 8 giây; video extension tạm thời chưa mở. |
| `veo-3.1-fast-generate-preview` | Hỗ trợ     | Hỗ trợ   | 16:9           | 4K bắt buộc dùng 8 giây; video extension tạm thời chưa mở. |

Trong request có thể chỉ định tỷ lệ qua `metadata.aspectRatio` hoặc trường form `aspectRatio`:

```bash
{
  "metadata": {
    "aspectRatio": "9:16"
  }
}
```

Nếu không truyền rõ `aspectRatio`, hệ thống sẽ ưu tiên suy ra tỷ lệ từ `size`, ví dụ `1280x720` suy ra 16:9, `720x1280` suy ra 9:16. Nếu cũng không truyền `size`, upstream mặc định dùng 16:9.

### Về âm thanh

| Mô hình                         | Năng lực âm thanh chính thức | Hỗ trợ generateAudio | Khuyến nghị                                                             |
| ------------------------------- | ---------------------------- | -------------------- | ----------------------------------------------------------------------- |
| `veo-3.1-generate-preview`      | Có sẵn âm thanh              | Không hỗ trợ         | Đừng truyền `generateAudio`; cần hiệu ứng âm thanh thì viết vào prompt. |
| `veo-3.1-fast-generate-preview` | Có sẵn âm thanh              | Không hỗ trợ         | Đừng truyền `generateAudio`; cần hiệu ứng âm thanh thì viết vào prompt. |

Dòng Veo 3.1 là mô hình video có sẵn âm thanh, nhưng bảng tham số Veo của Gemini API hiện chưa mở `generateAudio` làm tham số điều khiển được. Truyền trường này có thể bị upstream trả `INVALID_ARGUMENT`.

Nếu muốn kiểm soát nội dung âm thanh, có thể mô tả lời thoại, âm thanh môi trường, hiệu ứng âm thanh hoặc phong cách nhạc trong prompt, ví dụ:

```bash
Hải đăng bên bờ biển lúc hoàng hôn, sóng biển vỗ nhẹ vào đá ngầm, xa xa có tiếng gió trầm và tiếng chim biển, ánh sáng chuẩn điện ảnh, máy quay chuyển động ổn định
```

## Năng lực đầu vào ảnh

| Năng lực                             | Veo chính thức của Google                      | API aicentos hỗ trợ | Ghi chú                                                                                                                           |
| ------------------------------------ | ---------------------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| Tạo video từ một ảnh khởi đầu        | Hỗ trợ                                         | Hỗ trợ              | Dùng `input_reference` để tải lên 1 ảnh làm khung hình bắt đầu của video.                                                         |
| Tạo từ khung đầu - cuối / chèn khung | Dòng Veo 3.1 hỗ trợ image + lastFrame          | Hỗ trợ              | Khung đầu dùng `input_reference`, khung cuối dùng `last_frame` hoặc `lastFrame`. Khuyến nghị dòng Veo 3.1, 8 giây.                |
| Nhiều ảnh tham chiếu                 | Dòng Veo 3.1 hỗ trợ tối đa 3 referenceImages   | Hỗ trợ              | Tải lên qua `reference_image`, `reference_images` hoặc `referenceImages`; `referenceType` chỉ hỗ trợ `asset`. Khuyến nghị 8 giây. |
| Video extension                      | Veo 3.1 / Fast hỗ trợ kéo dài video Veo sẵn có | Tạm chưa hỗ trợ     | API aicentos hiện chưa mở đầu vào video chính thức.                                                                               |

* MIME type ảnh hỗ trợ `image/jpeg`, `image/png`, `image/webp`. Nên truyền tệp hoặc Base64, không nên truyền trực tiếp URL ảnh từ xa.
* Lưu ý chế độ ảnh tham chiếu: upstream hiện không hỗ trợ `negativePrompt` trong tình huống ảnh tham chiếu; nếu truyền có thể nhận về `Negative prompt is not supported in your use case`. Request dùng ảnh tham chiếu đừng truyền `negativePrompt`.
* Ghi chú triển khai: ảnh đầu vào của `predictLongRunning` cho Veo trong Gemini API dùng `bytesBase64Encoded` + `mimeType`, không phải `inlineData` của `generateContent` thông thường. aicentos sẽ chuyển ảnh upload dạng multipart sang định dạng upstream cần.

## Quy tắc tính phí

* Tính phí theo thời lượng tạo video, đơn vị là giây. Hãy dùng số giây mà mô hình hỗ trợ như bảng trên, không nên truyền số giây tùy ý.
* Nếu request không chỉ định thời lượng video, hệ thống mặc định tính phí 8 giây.
* Thứ tự ưu tiên nhận diện số giây: `metadata.durationSeconds` > `duration` > `seconds` > mặc định 8 giây.
* Thứ tự ưu tiên nhận diện độ phân giải: `metadata.resolution` > `size` > mặc định 720p.
* 720p / 1080p / 4K tính phí theo cùng một quy tắc, không phụ thu riêng theo độ phân giải.
* `aspectRatio` chỉ quyết định khung ngang hay dọc, không tính thêm phí.
* 4K chỉ hỗ trợ 8 giây.
* Đơn giá cụ thể lấy theo Console aicentos.

## Mô tả API

Hiện khuyến nghị dùng 3 endpoint sau:

| Mục đích            | Phương thức | Đường dẫn                      |
| ------------------- | ----------- | ------------------------------ |
| Tạo task            | POST        | `/v1/videos`                   |
| Truy vấn trạng thái | GET         | `/v1/videos/{task_id}`         |
| Tải kết quả         | GET         | `/v1/videos/{task_id}/content` |

Nếu muốn lấy luôn địa chỉ kết quả khi truy vấn, có thể dùng:

| Mục đích                               | Phương thức | Đường dẫn                         |
| -------------------------------------- | ----------- | --------------------------------- |
| Truy vấn trạng thái và địa chỉ kết quả | GET         | `/v1/video/generations/{task_id}` |

### Xác thực

```bash
export BASE_URL="https://aicentos.com"
export AICENTOS_API_KEY="sk-xxxxxx"
```

Mọi request đều kèm:

```bash
-H "Authorization: Bearer $AICENTOS_API_KEY"
```

### Tạo task video từ văn bản

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "veo-3.1-generate-preview",
    "prompt": "Hải đăng bên bờ biển lúc hoàng hôn, máy quay tiến chậm lại gần, sóng biển vỗ nhẹ vào đá ngầm, ánh sáng chuẩn điện ảnh, máy quay chuyển động ổn định",
    "seconds": "8",
    "size": "1280x720",
    "metadata": {
      "negativePrompt": "blurry, watermark, distorted, low quality",
      "resolution": "720p",
      "aspectRatio": "16:9",
      "seed": 20260401
    }
  }'
```

Kết quả trả về điển hình:

```bash
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "queued",
  "progress": 0,
  "created_at": 1775025000
}
```

### Tạo task video từ ảnh khung đầu

Hiện nay image-to-video khuyến nghị dùng `multipart/form-data`, tên trường ảnh khung đầu bắt buộc phải là `input_reference`.

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=Cô gái trong khung hình quay đầu nhìn vào ống kính, gió nhẹ thổi tung tóc, ánh đèn thành phố phía sau mờ nhẹ, máy quay tiến đều" \
  -F "input_reference=@./first-frame.png;type=image/png" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "negativePrompt=blurry, watermark, deformed hands" \
  -F "seed=20260401"
```

### Tạo task khung đầu - cuối

Task khung đầu - cuối cần cung cấp cả khung đầu và khung cuối. Khung đầu dùng `input_reference`, khung cuối dùng `last_frame` hoặc `lastFrame`.

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=Chuyển cảnh tự nhiên từ khung cô gái đầu tiên sang khung cậu bé cuối cùng, máy quay tiến đều, ánh đèn thành phố mờ nhẹ, tóc và quần áo khẽ lay theo gió, chuyển cảnh tự nhiên chân thực" \
  -F "input_reference=@./first-frame.png;type=image/png" \
  -F "last_frame=@./last-frame.png;type=image/png" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "negativePrompt=blurry, watermark, distorted face, deformed hands" \
  -F "seed=20260402"
```

### Tạo task với ảnh tham chiếu

Task ảnh tham chiếu chỉ hỗ trợ dòng Veo 3.1, tối đa 3 ảnh và `referenceType` chỉ hỗ trợ `asset`. Tên trường có thể là `reference_image`, `reference_images` hoặc `referenceImages`. Request ảnh tham chiếu đừng truyền `negativePrompt`.

```bash
curl -X POST "$BASE_URL/v1/videos" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -H "Accept: application/json" \
  -F "model=veo-3.1-generate-preview" \
  -F "prompt=Tham khảo ngoại hình nhân vật và không khí phố đêm trong hai ảnh, tạo một cú quay phố kiểu điện ảnh với hai người, máy quay tiến đều, ánh đèn nền mờ nhẹ, nhân vật tự nhiên nhìn vào ống kính" \
  -F "reference_image=@./ref-1.png;type=image/png" \
  -F "reference_image=@./ref-2.png;type=image/png" \
  -F "reference_type=asset" \
  -F "seconds=8" \
  -F "size=1280x720" \
  -F "resolution=720p" \
  -F "aspectRatio=16:9" \
  -F "seed=20260403"
```

JSON / Base64 cũng được hỗ trợ:

```bash
{
  "model": "veo-3.1-generate-preview",
  "prompt": "Tạo cảnh quảng cáo dựa trên ngoại hình sản phẩm trong ảnh tham chiếu",
  "duration": 8,
  "metadata": {
    "resolution": "720p",
    "aspectRatio": "16:9",
    "referenceImages": [
      {
        "image": {
          "bytesBase64Encoded": "BASE64_IMAGE",
          "mimeType": "image/png"
        },
        "referenceType": "asset"
      }
    ]
  }
}
```

### Truy vấn trạng thái task

Trước tiên hãy lưu lại `id` hoặc `task_id` mà API tạo task trả về:

```bash
export TASK_ID="task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

Sau đó truy vấn trạng thái:

```bash
curl -X GET "$BASE_URL/v1/videos/$TASK_ID" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

Khi đang xử lý, kết quả trả về điển hình:

```bash
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "in_progress",
  "progress": 50,
  "created_at": 1775025000
}
```

Khi hoàn thành, kết quả trả về điển hình:

```bash
{
  "id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "object": "video",
  "model": "veo-3.1-generate-preview",
  "status": "completed",
  "progress": 100,
  "created_at": 1775025000,
  "completed_at": 1775025068
}
```

### Truy vấn trạng thái và địa chỉ kết quả

Nếu muốn lấy luôn địa chỉ tải được khi truy vấn, có thể gọi:

```bash
curl -X GET "$BASE_URL/v1/video/generations/$TASK_ID" \
  -H "Authorization: Bearer $AICENTOS_API_KEY"
```

Kết quả trả về điển hình:

```bash
{
  "code": "success",
  "message": "",
  "data": {
    "error": null,
    "format": "mp4",
    "metadata": null,
    "status": "succeeded",
    "task_id": "task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "url": "https://aicentos.com/v1/videos/task_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx/content"
  }
}
```

### Tải video kết quả

Sau khi task hoàn thành, tải trực tiếp:

```bash
curl -L "$BASE_URL/v1/videos/$TASK_ID/content" \
  -H "Authorization: Bearer $AICENTOS_API_KEY" \
  -o veo-result.mp4
```

## Mô tả trạng thái

Các trạng thái chính mà `GET /v1/videos/{task_id}` trả về:

| Trạng thái    | Ý nghĩa       |
| ------------- | ------------- |
| `queued`      | Đã xếp hàng   |
| `in_progress` | Đang tạo      |
| `completed`   | Đã hoàn thành |
| `failed`      | Thất bại      |

Các trạng thái chính mà `GET /v1/video/generations/{task_id}` trả về:

| Trạng thái   | Ý nghĩa     |
| ------------ | ----------- |
| `queued`     | Đã xếp hàng |
| `processing` | Đang tạo    |
| `succeeded`  | Thành công  |
| `failed`     | Thất bại    |

## Lưu ý khi tích hợp

* `prompt` là bắt buộc.
* Với image-to-video, tên trường ảnh bắt buộc phải là `input_reference`.
* Task khung đầu - cuối phải cung cấp cả khung đầu và khung cuối; khung đầu dùng `input_reference`, khung cuối dùng `last_frame` hoặc `lastFrame`.
* Task ảnh tham chiếu chỉ hỗ trợ dòng Veo 3.1, tối đa 3 ảnh và bắt buộc 8 giây.
* Request ảnh tham chiếu đừng truyền `negativePrompt`.
* Hiện image-to-video Gemini không khuyến nghị truyền trực tiếp URL ảnh từ xa; nên truyền tệp hoặc Base64.
* Nên polling `GET /v1/videos/{task_id}`, đợi `status=completed` rồi mới tải về.
* Dòng Veo 3.1 nhận 4, 6, 8 giây; khi dùng 1080p hoặc 4k bắt buộc phải truyền 8 giây. - Ngang dùng `aspectRatio=16:9`, dọc dùng `aspectRatio=9:16`; nếu không truyền, mặc định xử lý theo 16:9.
* Đừng truyền tham số `generateAudio`. Dòng Veo 3.1 là mô hình video có sẵn âm thanh, nhưng Gemini API hiện không hỗ trợ bật/tắt âm thanh qua tham số `generateAudio`; truyền trường này có thể bị upstream trả `INVALID_ARGUMENT`.
* Nếu cần kiểm soát nội dung âm thanh, hãy mô tả lời thoại, âm thanh môi trường, hiệu ứng âm thanh hoặc phong cách nhạc trong prompt.
* Veo 3.1 chính thức hỗ trợ video extension, nhưng API aicentos hiện tạm chưa mở đầu vào video chính thức.