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.
Xóa nền khỏi một ảnh và trả về một bản cắt ghép nền trong suốt. Bất đồng bộ — gửi, rồi thăm dò hoặc chờ webhook.
Bảng giá
Một khoản phí cố định mỗi ảnh. Gọi endpoint /cost để lấy số tiền chính xác.
Tham số
Tham số
Kiểu
Bắt buộc
Mô tả
imageUrl
string
Có
http(s) URL công khai của ảnh cần xử lý. Đây là đầu vào duy nhất mà dịch vụ nhận — nó không chấp nhận base64 hoặc một source_type.
width
number
Không
Tùy chọn. Chỉ dùng làm dự phòng diện tích tính phí khi không thể phát hiện độ phân giải nguồn; nó không thay đổi đầu ra.
height
number
Không
Tùy chọn. Chỉ dùng làm dự phòng diện tích tính phí khi không thể phát hiện độ phân giải nguồn; nó không thay đổi đầu ra.
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 ảnh cắt ghép nền trong suốt.
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.