Kling Video V3
Ba mô hình dùng chung API tác vụ video của PopGo nhưng khác số ảnh, ý nghĩa khung hình và định dạng đầu ra. Tích hợp này chưa cung cấp đầu vào video hoặc âm thanh tham chiếu. Cột “âm thanh” trong tài liệu dịch vụ không khai báo đầu vào âm thanh tham chiếu.
Khác biệt giữa các mô hình
| Mô hình | Ảnh | Âm thanh đầu ra (tài liệu dịch vụ) | Độ phân giải |
|---|---|---|---|
kling-video-v3 | Tối đa 2; ảnh thứ nhất là khung đầu, ảnh thứ hai là khung cuối | Có hỗ trợ | 720p / 1080p / 4K |
kling-video-v3-omni | Tối đa 7 ảnh tham chiếu | Có hỗ trợ | 720p / 1080p / 4K |
kling-video-v3-turbo | Chỉ một khung đầu | Không hỗ trợ âm thanh | 720p / 1080p |
Trường và giá trị mặc định
| Trường | Kiểu | Quy tắc |
|---|---|---|
model | string | Bắt buộc; dùng ID mô hình công khai ở trên |
prompt | string | Bắt buộc; mô tả chủ thể, chuyển động và máy quay |
seconds / duration | integer | Số nguyên 3–15 giây; nên chỉ định rõ; giao diện mặc định 5 giây |
resolution | string | Chọn 720p / 1080p / 4K theo mô hình; giao diện mặc định 720p, dịch vụ mặc định 4K; Turbo không có 4K |
aspect_ratio | string | 16:9 / 9:16 / 1:1; mặc định 16:9; xem hướng dẫn ảnh bên dưới |
reference_images | object[] | Mảng đối tượng; mỗi mục dùng url hoặc image_url với URL HTTP(S) công khai hoặc Data URL ảnh đầy đủ |
Dùng reference_images
Khi gọi API trực tiếp, dùng mảng đối tượng dưới đây. PopGo cũng chuẩn hóa tệp tải lên từ Canvas và trường khung hình, nhưng không gửi nhiều tên đồng nghĩa cùng lúc. URL công khai không bắt buộc: ảnh cục bộ có thể mã hóa thành Data URL đầy đủ. Trang chia sẻ, trang đăng nhập và đường dẫn tệp không phải URL ảnh.
curl -X POST https://api.popgo.site/v1/videos \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "YOUR_MODEL",
"prompt": "A person turns toward the camera",
"seconds": 5,
"resolution": "720p",
"reference_images": [
{"url": "YOUR_IMAGE_URL"}
]
}'
Văn bản thành video: bỏ reference_images. Nếu dùng ảnh, giữ thứ tự mảng. Với bản tiêu chuẩn, hai ảnh là khung đầu và khung cuối, không phải hai ảnh tham chiếu phong cách. Omni dùng nhiều ảnh tham chiếu chủ thể/phong cách; Turbo từ chối hơn một ảnh.
Tỷ lệ và đầu ra
Tài liệu ghi nhận khung đầu 1024×1536 tạo video 2352×3524 ở bản tiêu chuẩn: tỷ lệ theo ảnh đầu. Hãy cắt ảnh trước nếu cần bố cục cụ thể. Không giả định aspect_ratio sẽ ghi đè mọi chế độ ảnh. Canvas hiện ẩn tỷ lệ ở chế độ khung đầu.
Một mẫu Omni yêu cầu 5 giây, 4K cho kết quả 3840×2160, 24 fps, khoảng 5.042 giây, 8.9 Mbps và 5.6 MB. Đây là một kết quả quan sát, không bảo đảm bitrate hoặc dung lượng cố định.
Trường chưa hỗ trợ hoặc chưa xác nhận
Hiện cả ba mô hình đều không cung cấp reference_video, video_reference, reference_audio hoặc quy trình điều khiển chuyển động bằng tham chiếu. generate_audio chỉ điều khiển âm thanh đầu ra; không phải tham chiếu. Preset Canvas hiện không mở công tắc đầu ra này. Tên Omni không đồng nghĩa với hỗ trợ điều khiển chuyển động.
Trường không được công bố như quality có thể bị bỏ qua. HTTP 200 không chứng minh tham số có hiệu lực; đừng suy ra seed hoặc watermark từ quy ước chung. Cần kiểm tra hợp đồng hiện tại và kết quả trước khi mở trường mới.
Bốn lưu ý khi thăm dò
- Tiến độ có thể giữ 0 đến khi completed / 100. Điều này không tự chứng minh tác vụ bị treo; không tự tạo phần trăm trung gian.
- Trường model trong kết quả thăm dò có thể rỗng; hãy lưu ID mô hình đã gửi.
- Có thể không có usage; kiểm tra nhật ký sử dụng và thanh toán PopGo thay vì cho rằng miễn phí.
- Có thể thiếu độ phân giải, thời lượng và fps; hãy kiểm tra tệp tải về. Mốc thời gian trong phản hồi không luôn phản ánh thời gian xử lý thực tế.
Ba lần chạy được ghi nhận mất khoảng 140, 200 và 420 giây. Thăm dò mỗi 10 giây và cho phép chờ ít nhất 15 phút; đây không phải cam kết độ trễ. Sau khi hết thời gian chờ cục bộ, tiếp tục truy vấn tác vụ cũ thay vì gửi lại.
Lỗi và cách xử lý
| Hiện tượng | Hành động |
|---|---|
| 400 invalid parameters | Kiểm tra thời lượng, tỷ lệ, độ phân giải và số ảnh hợp lệ; không gửi lại yêu cầu chưa sửa |
| 404 model or task missing | Kiểm tra ID mô hình công khai, quyền token và ID tác vụ do PopGo trả về |
| 503 no available account / 502 temporary service failure | Thử lại có giới hạn với thời gian chờ tăng dần; sau khi tạo bị timeout, kiểm tra tác vụ đã tồn tại chưa |
| Video thành công nhưng không theo ảnh | Kiểm tra reference_images thực tế và khả năng truy cập ảnh, rồi so khung hình/chủ thể; ID tác vụ không chứng minh đã dùng ảnh |
| Turbo với 4K hoặc tham số âm thanh | Bỏ tham số không hỗ trợ; dùng 720p / 1080p |
Tải qua proxy /content của PopGo hoặc URL kết quả khả dụng trong phản hồi. Cho phép đủ thời gian tải tệp lớn và không gửi API Key PopGo đến máy chủ media bên thứ ba. Xem Quy trình tác vụ video để biết cách thăm dò, tải và thử lại. Giá theo Mô hình và giá.