# API Happy Horse 1.1 Tài liệu tham chiếu API đầy đủ cho các mô hình tạo video Happy Horse 1.1 của Alibaba. ## Biến Thể Mô Hình API này hỗ trợ ba biến thể mô hình: | Mô hình | ID | Mô tả | | --------------------------------------- | ------------------------------------ | ---------------------------------------------------- | | **Happy Horse 1.1 Text to Video** | `happyhorse-1.1-text-to-video` | Tạo video trực tiếp từ prompt văn bản | | **Happy Horse 1.1 Image to Video** | `happyhorse-1.1-image-to-video` | Tạo chuyển động cho một ảnh khung đầu tiên với hướng dẫn từ prompt | | **Happy Horse 1.1 Reference to Video** | `happyhorse-1.1-reference-to-video` | Tạo video được hướng dẫn bởi tối đa 9 ảnh tham chiếu | ## So Sánh Nhanh | Tính năng | Văn bản thành Video | Ảnh thành Video | Tham chiếu thành Video | | -------------- | ------------------------- | ------------------------- | ------------------------- | | Đầu vào | Prompt văn bản | Ảnh khung đầu tiên + prompt | Ảnh tham chiếu + prompt | | Khoảng thời lượng | 3-15 giây | 3-15 giây | 3-15 giây | | Độ phân giải | 720p, 1080p (mặc định 1080p) | 720p, 1080p (mặc định 1080p) | 720p, 1080p (mặc định 1080p) | | Tỷ lệ khung hình | 9 tỷ lệ được hỗ trợ (mặc định 16:9) | Không hỗ trợ (theo ảnh đầu vào) | 9 tỷ lệ được hỗ trợ (mặc định 16:9) | | Seed | Tùy chọn | Tùy chọn | Tùy chọn | ### Tỷ Lệ Khung Hình Được Hỗ Trợ (Văn bản thành Video & Tham chiếu thành Video) | Tỷ lệ | Mô tả | | ------ | ---------------------- | | `16:9` | Ngang (màn hình rộng) | | `9:16` | Dọc (vertical) | | `3:4` | Dọc tiêu chuẩn | | `4:3` | Ngang tiêu chuẩn | | `4:5` | Dọc | | `5:4` | Ngang | | `1:1` | Vuông | | `9:21` | Dọc siêu cao | | `21:9` | Ngang siêu rộng | ## Happy Horse 1.1 Text to Video ### Điểm cuối ``` POST /api/v1/video/task ``` ### Tham Số Yêu Cầu #### Bắt buộc | Tham số | Kiểu | Mô tả | | -------------- | ------ | ------------------------------------------------------------------ | | `model_name` | string | Phải là `"happyhorse-1.1-text-to-video"` | | `prompt` | string | Prompt tạo video | | `duration` | number | Thời lượng video tính bằng giây (3-15) | | `resolution` | string | Độ phân giải đầu ra: `"720p"` hoặc `"1080p"` (mặc định `"1080p"`) | | `aspect_ratio` | string | Tỷ lệ khung hình video (xem bảng ở trên; mặc định `"16:9"`) | #### Tùy chọn | Tham số | Kiểu | Mô tả | | --------- | ------ | ---------------------------------------------------------------------------------- | | `seed` | number | Seed ngẫu nhiên cho các lần tạo có thể tái lập, số nguyên trong khoảng từ `0` đến `2147483647` | ### Ví Dụ Yêu Cầu ```javascript const response = await fetch('https://api.flaq.ai/api/v1/video/task', { method: 'POST', headers: { Authorization: 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ model_name: 'happyhorse-1.1-text-to-video', prompt: 'A cat playing with a ball of yarn on a sunny windowsill', duration: 5, resolution: '1080p', aspect_ratio: '16:9', seed: 42, }), }); const { data } = await response.json(); const taskId = data.task_id; ``` ## Happy Horse 1.1 Image to Video ### Tham Số Yêu Cầu #### Bắt buộc | Tham số | Kiểu | Mô tả | | ------------ | ------ | ------------------------------------------------------------------ | | `model_name` | string | Phải là `"happyhorse-1.1-image-to-video"` | | `prompt` | string | Prompt tạo video | | `duration` | number | Thời lượng video tính bằng giây (3-15) | | `resolution` | string | Độ phân giải đầu ra: `"720p"` hoặc `"1080p"` (mặc định `"1080p"`) | | `image_url` | string | URL ảnh khung đầu tiên (chỉ khung đầu tiên) | #### Tùy chọn | Tham số | Kiểu | Mô tả | | --------- | ------ | ---------------------------------------------------------------------------------- | | `seed` | number | Seed ngẫu nhiên cho các lần tạo có thể tái lập, số nguyên trong khoảng từ `0` đến `2147483647` | > **Lưu ý:** `aspect_ratio` không được hỗ trợ cho image-to-video. Khung hình đầu ra tuân theo ảnh khung đầu tiên đã tải lên. ### Ví Dụ Yêu Cầu ```javascript const response = await fetch('https://api.flaq.ai/api/v1/video/task', { method: 'POST', headers: { Authorization: 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ model_name: 'happyhorse-1.1-image-to-video', image_url: 'https://example.com/first-frame.jpg', prompt: 'Gentle motion; cinematic lighting', duration: 5, resolution: '1080p', seed: 42, }), }); const { data } = await response.json(); const taskId = data.task_id; ``` ## Happy Horse 1.1 Reference to Video ### Tham Số Yêu Cầu #### Bắt buộc | Tham số | Kiểu | Mô tả | | -------------- | -------- | ------------------------------------------------------------------ | | `model_name` | string | Phải là `"happyhorse-1.1-reference-to-video"` | | `prompt` | string | Prompt tạo video. Viết prompt tiêu chuẩn không có placeholder, hoặc tùy chọn dùng tính năng tham chiếu @ (AT) với `<<>>` để tham chiếu rõ ràng các phần tử trong mảng `images` | | `duration` | number | Thời lượng video tính bằng giây (3-15) | | `resolution` | string | Độ phân giải đầu ra: `"720p"` hoặc `"1080p"` (mặc định `"1080p"`) | | `aspect_ratio` | string | Tỷ lệ khung hình video (xem bảng ở trên; mặc định `"16:9"`) | | `images` | string[] | URL ảnh tham chiếu (1-9 ảnh) | #### Placeholder Tham Chiếu @ (AT) Tính năng tham chiếu @ (AT) liên kết hình ảnh tham chiếu với prompt thông qua các placeholder `<<>>` được đánh số. Số thứ tự bắt đầu từ `1` và tuân theo thứ tự của mảng `images`. | Placeholder | Giá trị được tham chiếu | |-------------|------------------| | `<<>>` | `images[0]` | | `<<>>` | `images[1]` | | `<<>>` | `images[2]` | #### Tùy chọn | Tham số | Kiểu | Mô tả | | --------- | ------ | ---------------------------------------------------------------------------------- | | `seed` | number | Seed ngẫu nhiên cho các lần tạo có thể tái lập, số nguyên trong khoảng từ `0` đến `2147483647` | ### Yêu Cầu Về Ảnh Tham Chiếu - Định dạng được hỗ trợ: `JPEG`, `JPG`, `PNG`, `WEBP` - Kích thước tệp tối đa: 20 MB mỗi ảnh - Cạnh ngắn tối thiểu: 400 px - Số lượng: ít nhất 1, tối đa 9 ảnh ### Ví Dụ Yêu Cầu ```javascript const response = await fetch('https://api.flaq.ai/api/v1/video/task', { method: 'POST', headers: { Authorization: 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ model_name: 'happyhorse-1.1-reference-to-video', prompt: 'Subject moves naturally while preserving reference style and appearance', duration: 5, resolution: '1080p', aspect_ratio: '16:9', images: [ 'https://example.com/ref-1.jpg', 'https://example.com/ref-2.jpg', ], seed: 42, }), }); const { data } = await response.json(); const taskId = data.task_id; ``` ### Ví Dụ Yêu Cầu Reference-to-Video @ (AT) ```javascript const response = await fetch('https://api.flaq.ai/api/v1/video/task', { method: 'POST', headers: { Authorization: 'Bearer YOUR_API_KEY', 'Content-Type': 'application/json', }, body: JSON.stringify({ model_name: 'happyhorse-1.1-reference-to-video', prompt: 'Show the person from <<>> walking beside the bicycle from <<>> through the street in <<>>, preserving all reference details', duration: 5, resolution: '1080p', aspect_ratio: '16:9', images: [ 'https://example.com/person-reference.jpg', 'https://example.com/bicycle-reference.jpg', 'https://example.com/street-reference.jpg', ], seed: 42, }), }); const { data } = await response.json(); const taskId = data.task_id; ``` ## Định Dạng Phản Hồi ### Phản Hồi Ban Đầu ```json { "code": 0, "message": "success", "data": { "task_id": "{task_id}", "response_url": "https://api.flaq.ai/api/v1/video/{task_id}", "task_status": "submitted" } } ``` ### Phản Hồi Polling Gọi polling `GET /api/v1/video/{taskId}` để kiểm tra trạng thái: ```json { "code": 0, "message": "success", "data": { "task_id": "{task_id}", "response_url": "https://api.flaq.ai/api/v1/video/{task_id}", "task_status": "succeed", "task_status_msg": null, "task_result": { "credit": 0.2, "videos": [ { "url": "https://example.com/generated-video.mp4" } ] } } } ``` ### Giá Trị Trạng Thái - `submitted`: Tác vụ đã được chấp nhận và đang chờ xử lý - `processing`: Quá trình tạo video đang diễn ra - `succeed`: Quá trình tạo video đã hoàn tất - `failed`: Quá trình tạo video thất bại ## Thời Gian Xử Lý Thời gian xử lý thường gặp: 2-5 phút tùy thuộc vào thời lượng và tải hàng đợi. ## Phương Pháp Tốt Nhất 1. **Mô Tả Chuyển Động Rõ Ràng**: Thêm chuyển động của chủ thể, chuyển động camera và diễn tiến cảnh để cải thiện động lực video. 2. **Dùng Các Lần Lặp Ngắn Trước**: Bắt đầu với các lần tạo 3-5 giây để xác thực hướng prompt trước khi chạy các clip dài hơn. 3. **Chọn Ảnh Đầu Vào Phù Hợp**: Với image-to-video, hãy dùng ảnh khung đầu tiên rõ ràng, đủ sáng và có chủ thể nổi bật. 4. **Tuyển Chọn Ảnh Tham Chiếu**: Với reference-to-video, cung cấp ảnh tham chiếu nhất quán, chất lượng cao, thể hiện rõ chủ thể hoặc phong cách bạn muốn giữ lại. 5. **Tái Sử Dụng Seed Cho Các Biến Thể**: Giữ nguyên `seed` khi kiểm thử các tinh chỉnh prompt để so sánh đầu ra nhất quán hơn. 6. **Khớp Tỷ Lệ Với Kênh Phân Phối**: Dùng `16:9` cho video ngang, `9:16` cho shorts và reels, và `1:1` cho vị trí hiển thị vuông.