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.

Giới thiệu

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

  1. 1Xác thực bằng khóa API của bạn trong header X-API-Key.
  2. 2Gửi một tác vụ đến một dịch vụ bằng body JSON { input }.
  3. 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 job
curl -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ạnhKhóa cá nhânKhóa doanh nghiệp
Tiền tố khóavber_sk_vber_org_sk_
Tiền tố tuyến/ai/services, /ai/tasks/ai/org-services
Cách nhận khóaTự phục vụ, thiết lập tài khoảnQuản trị viên tổ chức, cổng doanh nghiệp
Tính phí vàoTín dụng cá nhânTín dụng tổ chức
Giới hạnGiớ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.
json
{
  "input": {
    "imageUrl": "https://example.com/photo.png"
  },
  "webhookUrl": "https://your-server.com/hook"
}
bash
HTTP 200  # sync: result inline
HTTP 202  # async: { "taskId": "...", "status": "queued" }

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.

Thăm dò tuyến nào

Hành độngKhóa cá nhânKhó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áiGET /ai/org-services/tasks/{taskId}/outputs
Hủy một tác vụPOST /ai/tasks/{taskId}/cancelKhông khả dụng
Trạng thái theo lôGET /ai/tasks/batch-statusKhô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.

createdqueueddispatchingsubmittedprocessingcompletedfailedcancelledtimeout

Đọc kết quả

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.

bash
# personal
curl https://api.vberai.com/api/ai/tasks/{taskId} \
  -H "X-API-Key: vber_sk_YOUR_KEY"

# enterprise
curl https://api.vberai.com/api/ai/org-services/tasks/{taskId} \
  -H "X-API-Key: vber_org_sk_YOUR_ORG_KEY"

Tác vụ đã hoàn tất

json
{
  "success": true,
  "data": {
    "taskId": "6a97e277a148c970dd545f40",
    "serviceCode": "super-matting",
    "status": "completed",
    "creditsEstimated": 10,
    "creditsActual": 10,
    "outputCount": 1,
    "result": {
      "type": "images",
      "assets": [
        {
          "index": 0,
          "url": "https://assets.vberai.org/tmp/user-assets/.../0.png?signature=...",
          "mimeType": "image/png",
          "expiresAt": "2026-01-22T10:30:12.000Z"
        }
      ]
    },
    "completedAt": "2026-01-15T10:30:12.000Z"
  }
}

Tính bất biến (idempotency)

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).

http
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Webhook

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.
json
{
  "input": { "imageUrl": "https://example.com/photo.png" },
  "webhookUrl": "https://your-server.com/hook",
  "webhookSecret": "whsec_your_secret"
}

Xác minh một webhook (Node.js)

javascript
import crypto from "node:crypto";

function verify(rawBody, signature, secret) {
  const expected = crypto
    .createHmac("sha256", secret)
    .update(rawBody)
    .digest("hex");

  return signature === expected;
}

app.post("/hook", (req, res) => {
  const sig = req.header("X-Webhook-Signature");
  if (!verify(req.rawBody, sig, process.env.WEBHOOK_SECRET)) {
    return res.status(401).end();
  }
  // req.body: { taskId, serviceCode, status, ... }
  res.status(200).end();
});

Tín dụng & thanh toá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.
bash
curl -X POST https://api.vberai.com/api/ai/services/super-matting/cost \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"input": {"width": 1024, "height": 768}}'
json
{
  "success": true,
  "data": {
    "estimatedCredits": 10,
    "pricingType": "custom",
    "pricingMode": "dimension",
    "sufficient": true
  }
}

Giới hạn tốc độ

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.

HeaderMô tả
X-RateLimit-Limit-MinuteSố yêu cầu được phép mỗi phút.
X-RateLimit-Remaining-MinuteSố yêu cầu còn lại trong cửa sổ phút hiện tại.
X-RateLimit-Limit-DaySố yêu cầu được phép mỗi ngày.
X-RateLimit-Remaining-DaySố 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.

http
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 59
X-RateLimit-Limit-Day: 2000
X-RateLimit-Remaining-Day: 1997

Lỗi

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
200Thà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.
400Yê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ụ.
401Không được phép — khóa API thiếu, sai định dạng, hoặc sai loại.
402Yêu cầu thanh toán — không đủ tín dụng.
403Bị cấm — khóa hoặc tài khoản không được dùng dịch vụ này.
404Khô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.
429Quá nhiều yêu cầu — vượt giới hạn tốc độ hoặc giới hạn đồng thời.
500Lỗ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_CREDITSerrorCodeKhông đủ tín dụng cá nhân cho tác vụ.
INSUFFICIENT_ORG_CREDITSerrorCodeKhông đủ tín dụng tổ chức cho tác vụ.
ORG_API_KEY_REQUIREDdata.codeEndpoint này cần một khóa API doanh nghiệp (X-API-Key).
INVALID_ORG_API_KEYdata.codeKhóa doanh nghiệp bị thiếu, sai định dạng, hoặc đã bị thu hồi.
INVALID_API_KEYdata.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_ALLOWEDerrorCodeTổ chức của bạn chưa được phê duyệt cho dịch vụ này.
ORG_DISABLEDdata.codeTài khoản tổ chức đã bị vô hiệu hóa.
CONCURRENCY_LIMIT_EXCEEDEDerrorCodeQuá nhiều tác vụ chạy đồng thời cho tổ chức của bạn.
SERVICE_NOT_EXTERNALLY_ACCESSIBLEerrorCodeDịch vụ này không khả dụng qua API bên ngoài.
TASK_NOT_FOUNDerrorCodeKhông có tác vụ nào như vậy cho khóa này.
json
{
  "success": false,
  "errorCode": "INSUFFICIENT_ORG_CREDITS",
  "message": "Insufficient organization credits",
  "timestamp": "2026-01-15T10:30:00.000Z"
}

Tài liệu API

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.

Các dịch vụ có sẵ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.

EndpointMô tả
GET /ai/servicesLiệt kê các dịch vụ mà khóa của bạn có thể truy cập.
GET /ai/external/services/{code}/specLấy đặc tả tham số cho một dịch vụ.
bash
curl https://api.vberai.com/api/ai/services \
  -H "X-API-Key: YOUR_API_KEY"