Tài liệu API
motion-v2-video-bg-20s
Motion Control Nền Video V2 —Tối đa 20s — Thay nhân vật trong video gốc bằng nhân vật trong ảnh, giữ nguyên toàn bộ bối cảnh, ánh sáng & âm thanh của video gốc. 720p 30fps, tối đa 20 giây.
type: textoutput: videoTheo tham số — dùng POST /v1/generations/estimate để báo giá
Input — tham số đầu vào
POST
/v1/generationsGửi JSON gồm "model": "motion-v2-video-bg-20s" và các tham số dưới đây ở cùng cấp. Tham số không có trong bảng sẽ bị từ chối (400).
| Tham số | Kiểu | Giá trị hỗ trợ | Mô tả |
|---|---|---|---|
modelrequired | string | motion-v2-video-bg-20s | Mã model |
image_urlrequired | string (URL image) | Ảnh nhân vật thay thế — Ảnh nhân vật muốn ghép vào video (JPG, PNG, WEBP) | |
video_urlrequired | string (URL video) | Video gốc giữ nền (Tối đa 20 giây) — Video gốc cần thay nhân vật (MP4, MOV, WEBM) · giữ nguyên bối cảnh, ánh sáng & âm thanh · tối đa 20s |
- Tham số file (string URL) nhận link công khai http(s) — máy chủ tự tải về — hoặc URL trả về từ API tải file POST /account/ai/uploads.
- Bỏ trống tham số không bắt buộc thì dùng giá trị mặc định.
Ví dụ request
curl -X POST https://zova.io.vn/api/v1/generations \
-H "X-API-Key: $API_KEY" -H "Content-Type: application/json" \
-d '{
"model": "motion-v2-video-bg-20s",
"image_url": "https://example.com/image.jpg",
"video_url": "https://example.com/video.mp4"
}'Output — kết quả trả về
Tác vụ chạy bất đồng bộ. POST /v1/generations trả ngay đối tượng generation với status queued hoặc processing; hỏi lại GET /v1/generations/{id} mỗi 5–10 giây tới khi status là succeeded, failed hoặc cancelled.
GET
/v1/generations/{id}{
"id": "3f1c...-uuid",
"object": "generation",
"code": "T8KQ2M4X",
"model": "motion-v2-video-bg-20s",
"status": "succeeded", // queued | processing | succeeded | failed | cancelled
"progress": 100,
"cost": 2400, // số tiền đã trừ
"currency": "VND",
"refunded": false,
"output": {
"type": "video",
"files": [{ "url": "https://zova.io.vn/uploads/ai/outputs/....mp4", "type": "video", "name": "video.mp4" }],
"text": null
},
"error": null,
"created_at": "2026-10-30T08:00:00.000Z",
"completed_at": "2026-10-30T08:01:12.000Z"
}| Trường | Ý nghĩa |
|---|---|
| output.files[].url | Link file kết quả — nên tải về hệ thống của bạn, file trên máy chủ có thể được dọn sau một thời gian. |
| output.text | Nội dung văn bản (chỉ có với model trả văn bản). |
| cost | Số tiền VND đã trừ vào số dư; lỗi hoặc huỷ thì tự hoàn lại (refunded = true). |
| error | Lý do lỗi khi status = failed. |
Báo giá trước khi chạy
POST
/v1/generations/estimateCùng body với POST /v1/generations, không chạy và không trừ tiền.
# => { "object": "estimate", "model": "motion-v2-video-bg-20s", "cost": 2400, "currency": "VND" }