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.

Super Matting

super-matting

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ểuBắt buộcMô tả
source_typestringCó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_valuestringCóẢ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".
widthnumberCóChiều rộng mục tiêu tính bằng pixel (64–2048).
heightnumberCóChiều cao mục tiêu tính bằng pixel (64–2048).
seednumberKhôngTù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 độ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

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.

createdqueueddispatchingsubmittedprocessingcompletedfailedcancelledtimeout

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.

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"
  }
}

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.

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.

POST/ai/services/super-matting/execute
bash
curl -X POST https://api.vberai.com/api/ai/services/super-matting/execute \
  -H "X-API-Key: vber_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "source_type": "url",
      "input_value": "https://example.com/photo.png",
      "width": 1024,
      "height": 768
    }
  }'
bash
curl https://api.vberai.com/api/ai/tasks/{taskId} \
  -H "X-API-Key: vber_sk_YOUR_KEY"