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.
API của VberAI mở ra chính những pipeline AI đang vận hành studio — xóa nền, super matting, tạo ảnh và nhiều hơn nữa — dưới dạng các endpoint HTTP đơn giản. Xác thực bằng khóa API, gửi một tác vụ, rồi đọc kết quả trả về hoặc nhận qua webhook.
Một hình dạng yêu cầu duy nhất
Mọi dịch vụ đều nhận một body { input } và trả về một tác vụ mà bạn có thể thăm dò hoặc nhận qua webhook.
Hai loại khóa
Khóa cá nhân dành cho từng nhà phát triển, khóa doanh nghiệp dành cho sử dụng server-to-server ở cấp tổ chức.
Thanh toán có thể dự đoán
Tín dụng được giữ chỗ khi gửi và quyết toán khi thành công; các tác vụ thất bại được hoàn tiền tự động.
Cách hoạt động
1Xác thực bằng khóa API của bạn trong header X-API-Key.
2Gửi một tác vụ đến một dịch vụ bằng body JSON { input }.
3Đọc kết quả nội tuyến (dịch vụ đồng bộ) hoặc thăm dò tác vụ / nhận webhook (dịch vụ bất đồng bộ).
bash
# 1. Submit a jobcurl-X POST https://api.vberai.com/api/ai/services/ai-image-bg-remove/execute \
-H"X-API-Key: vber_sk_YOUR_KEY" \
-H"Content-Type: application/json" \
-d'{"input": {"imageUrl": "https://example.com/photo.png"}}'# => { "data": { "taskId": "...", "status": "queued" } }# 2. Poll until status is "completed"curl https://api.vberai.com/api/ai/tasks/{taskId} \
-H"X-API-Key: vber_sk_YOUR_KEY"
Xác thực & khóa API
Mọi yêu cầu đều được xác thực bằng khóa API gửi trong header X-API-Key. Có hai loại khóa, và chúng dùng các tuyến khác nhau — chọn sai tuyến cho loại khóa của bạn là nguyên nhân phổ biến nhất gây ra lỗi 401.
Hãy đối xử với khóa API như mật khẩu. Chỉ gửi chúng từ backend của bạn, xoay vòng khóa nếu bị rò rỉ, và giới hạn khóa doanh nghiệp bằng một mức trần chi tiêu.
Khóa cá nhân — vber_sk_
Dành cho từng nhà phát triển. Được tạo tự phục vụ từ trang khóa API của tài khoản bạn (yêu cầu gói có quyền truy cập API). Tính phí vào tín dụng cá nhân của bạn. Dùng các tuyến /ai/services và /ai/tasks.
Khóa doanh nghiệp — vber_org_sk_
Dành cho sử dụng server-to-server bởi một tổ chức. Do quản trị viên tổ chức cấp trong cổng doanh nghiệp, và giới hạn ở những dịch vụ mà tổ chức của bạn đã được phê duyệt. Tính phí vào quỹ tín dụng của tổ chức bạn. Dùng các tuyến /ai/org-services.
Khía cạnh
Khóa cá nhân
Khóa doanh nghiệp
Tiền tố khóa
vber_sk_
vber_org_sk_
Tiền tố tuyến
/ai/services, /ai/tasks
/ai/org-services
Cách nhận khóa
Tự phục vụ, thiết lập tài khoản
Quản trị viên tổ chức, cổng doanh nghiệp
Tính phí vào
Tín dụng cá nhân
Tín dụng tổ chức
Giới hạn
Giới hạn số yêu cầu mỗi phút / mỗi ngày
Đồng thời theo từng tổ chức (tùy chỉnh)
http
X-API-Key: vber_sk_... # personal key
X-API-Key: vber_org_sk_... # enterprise key
URL cơ sở
text
https://api.vberai.com/api
Yêu cầu & chế độ thực thi
Mọi dịch vụ đều nhận một body JSON có một đối tượng input chứa các tham số của dịch vụ. Cách bạn nhận kết quả phụ thuộc vào chế độ thực thi của dịch vụ.
Dịch vụ đồng bộ
Các dịch vụ nhanh (ví dụ chat hoặc dịch văn bản) trả về kết quả nội tuyến ngay trong cùng phản hồi với HTTP 200. Không cần thăm dò.
Dịch vụ bất đồng bộ
Các dịch vụ nặng hơn (tạo ảnh, matting, xóa nền) trả về HTTP 202 kèm một taskId. Thăm dò tác vụ hoặc nhận kết quả qua webhook khi nó hoàn tất.
Khóa cá nhân
Khóa cá nhân dùng một endpoint duy nhất cho mỗi dịch vụ: POST /ai/services/{code}/execute. Nó trả về kết quả nội tuyến (200) cho dịch vụ đồng bộ, hoặc một tác vụ (202) cho dịch vụ bất đồng bộ — vẫn là cùng một endpoint.
Khóa doanh nghiệp
Khóa doanh nghiệp dùng hai endpoint: /execute cho dịch vụ đồng bộ và /execute-async cho dịch vụ bất đồng bộ. Gọi nhầm endpoint sẽ trả về 400 và cho bạn biết nên dùng endpoint nào.
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.
Thăm dò tuyến nào
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
Hủy một tác vụ
POST /ai/tasks/{taskId}/cancel
Không khả dụng
Trạng thái theo lô
GET /ai/tasks/batch-status
Không khả dụng
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.
Các trạng thái tác vụ
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.
Idempotency cho phép bạn thử lại an toàn một lần gửi sau khi gặp lỗi mạng mà không tạo ra tác vụ trùng lặp hoặc bị tính phí hai lần.
Khóa doanh nghiệp
Gửi kèm một header Idempotency-Key tùy chọn (một giá trị do bạn tạo, tối đa 200 ký tự — một UUID là lý tưởng) trên /execute-async. Thử lại với cùng khóa sẽ trả về tác vụ ban đầu thay vì tạo mới. Máy chủ chỉ khử trùng lặp; nó không tạo khóa thay bạn.
Khóa cá nhân
Các yêu cầu bằng khóa API cá nhân hiện chưa hỗ trợ khóa idempotency. Chỉ thử lại sau khi xác nhận yêu cầu trước đó không tạo ra tác vụ (thăm dò bằng taskId bạn đã nhận).
Thay vì thăm dò, bạn có thể để VberAI POST kết quả đến máy chủ của bạn khi một tác vụ đạt trạng thái kết thúc.
Cấu hình một webhook
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.
Xác minh chữ ký
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.
Các lần gửi thất bại được thử lại vài lần với thời gian chờ lùi dần. Hãy phản hồi 2xx để xác nhận đã nhận.
Các tác vụ AI tiêu tốn tín dụng. Cùng một biểu giá áp dụng cho khóa cá nhân và khóa doanh nghiệp — chỉ khác ví: khóa cá nhân rút từ tín dụng cá nhân của bạn, khóa doanh nghiệp rút từ quỹ của tổ chức bạn.
Giữ chỗ, quyết toán, hoàn tiền
Tín dụng được giữ chỗ khi một tác vụ được chấp nhận và quyết toán theo đúng số lượng khi nó hoàn tất. Nếu một tác vụ thất bại hoặc bị hủy, phần giữ chỗ được hoàn lại toàn bộ — bạn không bao giờ bị tính phí cho một tác vụ thất bại.
Chi phí được tính như thế nào
Chi phí phụ thuộc vào dịch vụ. Một số dịch vụ tính một khoản cố định mỗi yêu cầu; số khác thay đổi theo độ phân giải đầu ra (theo từng pixel) hoặc theo cạnh dài nhất. Gọi endpoint cost để xem trước khoản phí chính xác trước khi bạn chạy một tác vụ.
•Theo yêu cầu — một khoản cố định mỗi lần gọi.
•Theo pixel — thay đổi theo chiều rộng × chiều cao đầu ra.
•Theo kích thước — tính giá theo cạnh dài nhất của đầu ra.
Việc giới hạn tốc độ khác nhau theo loại khóa. Cả hai đều được cấu hình theo từng dịch vụ ở backend — các giá trị bên dưới mô tả cơ chế, không phải những con số cố định.
Khóa cá nhân — tốc độ yêu cầu
Khóa cá nhân bị giới hạn theo số yêu cầu mỗi phút và mỗi ngày, cấu hình theo từng dịch vụ. Mỗi phản hồi đều mang các header bên dưới để bạn điều chỉnh nhịp độ gọi.
Header
Mô tả
X-RateLimit-Limit-Minute
Số yêu cầu được phép mỗi phút.
X-RateLimit-Remaining-Minute
Số yêu cầu còn lại trong cửa sổ phút hiện tại.
X-RateLimit-Limit-Day
Số yêu cầu được phép mỗi ngày.
X-RateLimit-Remaining-Day
Số yêu cầu còn lại trong cửa sổ ngày hiện tại.
Không có header X-RateLimit-Reset. Khi gặp 429, body phản hồi bao gồm retryAfter và resetIn.
Khóa doanh nghiệp — đồng thời
Khóa doanh nghiệp không bị giới hạn theo tốc độ yêu cầu mà theo số tác vụ có thể chạy đồng thời cho tổ chức của bạn. Giới hạn này được tùy chỉnh theo từng tổ chức (và có thể là không giới hạn); vượt quá sẽ trả về 429 CONCURRENCY_LIMIT_EXCEEDED. Các phản hồi doanh nghiệp không mang header X-RateLimit.
Mọi phản hồi đều bao gồm success, message và timestamp. Khi thất bại, một mã lỗi xác định vấn đề. Hãy phân nhánh theo mã, không theo văn bản message — các thông báo có thể thay đổi và chỉ có tiếng Anh.
Mã lỗi nằm ở đâu
Các lỗi doanh nghiệp nhất quán: các vấn đề xác thực đặt mã trong data.code, còn các vấn đề dịch vụ và thanh toán đặt mã trong errorCode ở cấp cao nhất. Lỗi cá nhân thì khác nhau theo endpoint (errorCode cấp cao nhất, data.code, hoặc errors.code) — hãy đọc trường được ghi chú cho mỗi mã.
Mã trạng thái HTTP
Trạng thái
Ý nghĩa
200
Thành công — kết quả trả về nội tuyến.
202
Đã chấp nhận — một tác vụ bất đồng bộ đã được tạo; hãy thăm dò hoặc chờ webhook.
400
Yêu cầu sai — đầu vào không hợp lệ, hoặc sai endpoint cho chế độ thực thi của dịch vụ.
401
Không được phép — khóa API thiếu, sai định dạng, hoặc sai loại.
402
Yêu cầu thanh toán — không đủ tín dụng.
403
Bị cấm — khóa hoặc tài khoản không được dùng dịch vụ này.
404
Không tìm thấy — tác vụ không xác định, hoặc một tác vụ không phải của bạn.
429
Quá nhiều yêu cầu — vượt giới hạn tốc độ hoặc giới hạn đồng thời.
500
Lỗi máy chủ — hãy thử lại; tác vụ (nếu có) sẽ được hoàn tiền.
Các mã lỗi thường gặp
Mã
Vị trí
Ý nghĩa
INSUFFICIENT_CREDITS
errorCode
Không đủ tín dụng cá nhân cho tác vụ.
INSUFFICIENT_ORG_CREDITS
errorCode
Không đủ tín dụng tổ chức cho tác vụ.
ORG_API_KEY_REQUIRED
data.code
Endpoint này cần một khóa API doanh nghiệp (X-API-Key).
INVALID_ORG_API_KEY
data.code
Khóa doanh nghiệp bị thiếu, sai định dạng, hoặc đã bị thu hồi.
INVALID_API_KEY
data.code
Định dạng khóa API không hợp lệ — thường là một tuyến cá nhân được gọi bằng khóa doanh nghiệp (hoặc ngược lại).
API_SERVICE_NOT_ALLOWED
errorCode
Tổ chức của bạn chưa được phê duyệt cho dịch vụ này.
ORG_DISABLED
data.code
Tài khoản tổ chức đã bị vô hiệu hóa.
CONCURRENCY_LIMIT_EXCEEDED
errorCode
Quá nhiều tác vụ chạy đồng thời cho tổ chức của bạn.
Chi tiết cụ thể về yêu cầu và phản hồi cho từng dịch vụ. Các ví dụ hiển thị cả hai loại khóa — hãy chọn tab tương ứng với khóa bạn có. Về các khái niệm mà chúng dựa vào (thăm dò, trạng thái, lỗi, thanh toán), xem các hướng dẫn ở trên.
Hai dịch vụ dưới đây được ghi chép đầy đủ. Để có danh sách trực tiếp, đầy đủ về các dịch vụ mà khóa của bạn có thể gọi — cùng với đặc tả tham số của mỗi dịch vụ — hãy truy vấn các endpoint danh mục. Đây là nguồn có thẩm quyền, vì tính khả dụng phụ thuộc vào gói của bạn và các phê duyệt của tổ chức.
Endpoint
Mô tả
GET /ai/services
Liệt kê các dịch vụ mà khóa của bạn có thể truy cập.