VberAI API — Tham chiếu RESTful cho lập trình viên
VberAI API là API HTTP theo chuẩn RESTful để nhúng các năng lực AI của VberAI (hiện tại: AI Super Matting) vào ứng dụng, game và pipeline tự động của bạn. Xác thực dùng khoá API với request ký chữ ký; các mã lỗi phổ biến được chuẩn hoá; tính phí theo lượt gọi bằng tín dụng VberAI.
API v1
Ổn định
Tài liệu API
Tạo ảnh, xóa nền và chạy các pipeline AI của VberAI trực tiếp qua HTTP — với khóa API cá nhân hoặc doanh nghiệp.
Cắt ghép chất lượng cao, tách chủ thể khỏi nền và trả về một kết quả matting sạch. Bất đồng bộ — gửi, rồi thăm dò hoặc chờ webhook.
Bảng giá
Tính giá theo cạnh đầu ra dài nhất (các mức theo kích thước — ví dụ 512 px là 2 tín dụng, 1024 px là 10). Gọi endpoint /cost để lấy số tiền chính xác trước khi chạy một tác vụ.
Tham số
Tham số
Kiểu
Bắt buộc
Mô tả
source_type
string
Có
Một trong "url" (input_value là một http(s) image URL công khai) hoặc "base64" (input_value là một chuỗi base64 hoặc data: URL).
input_value
string
Có
Ảnh nguồn: một http(s) URL khi source_type là "url", hoặc dữ liệu ảnh base64 khi source_type là "base64".
width
number
Có
Chiều rộng mục tiêu tính bằng pixel (64–2048).
height
number
Có
Chiều cao mục tiêu tính bằng pixel (64–2048).
seed
number
Không
Tùy chọn. Seed số nguyên cố định để tái tạo đầu ra; một seed ngẫu nhiên được dùng khi bỏ trống.
Thăm dò & kết quả
Các tác vụ bất đồng bộ trả về một taskId. Thăm dò tác vụ cho đến khi trạng thái đạt giá trị kết thúc, rồi đọc kết quả. Tuyến bạn thăm dò phụ thuộc vào loại khóa của bạn — đây là điều quan trọng nhất cần làm cho đúng.
Hành động
Khóa cá nhân
Khóa doanh nghiệp
Thăm dò trạng thái tác vụ
GET /ai/tasks/{taskId}
GET /ai/org-services/tasks/{taskId}
Ký lại các URL tải xuống mới
Đọc từ phản hồi trạng thái
GET /ai/org-services/tasks/{taskId}/outputs
Khóa doanh nghiệp phải thăm dò tuyến /ai/org-services
Một khóa doanh nghiệp (vber_org_sk_) gửi đến tuyến cá nhân /ai/tasks sẽ trả về 401 INVALID_API_KEY — các tuyến cá nhân chỉ chấp nhận khóa cá nhân. Luôn thăm dò các tác vụ doanh nghiệp tại /ai/org-services/tasks/{taskId}. Việc hủy và trạng thái theo lô chỉ dành cho khóa cá nhân.
Một tác vụ chuyển qua những giá trị này. Ngừng thăm dò khi đạt một trạng thái kết thúc: completed, failed, cancelled hoặc timeout.
Khi trạng thái là completed, result.assets chứa các ảnh đầu ra. Mỗi asset có một url (liên kết tải xuống đã ký trước, sẽ hết hạn), một mimeType và một index; width, height, size và expiresAt xuất hiện khi có sẵn. Hãy lấy các URL ngay — khóa doanh nghiệp có thể yêu cầu lại các liên kết mới từ endpoint /outputs.
Khi completed, result.assets chứa (các) ảnh đầu ra matting.
Truyền một webhookUrl HTTPS công khai (và một webhookSecret tùy chọn) khi bạn gửi tác vụ. Khóa doanh nghiệp đọc chúng từ cấp cao nhất của body; khóa cá nhân đọc chúng từ options.
Nếu bạn đặt một webhookSecret, mỗi lần gửi sẽ kèm một header X-Webhook-Signature — một HMAC-SHA256 của payload JSON thô, mã hóa hex. Hãy tính lại nó bằng secret của bạn và so sánh trước khi tin tưởng payload. Các lần gửi cũng mang một X-Idempotency-Key (taskId + status) để bạn có thể bỏ qua bản trùng.