VberAI 開發者 API

VberAI 提供 RESTful HTTP API,將 AI 超強去背等能力嵌入到你的應用、遊戲與自動化流程。使用 API Key + 簽章驗證,統一錯誤碼,按點數計費。

API v1
穩定版

API 文件

透過 HTTP 直接生成圖片、去除背景並執行 VberAI 的 AI 管線——支援個人或企業 API 金鑰。

超級去背

super-matting

高品質去背,將主體從背景中分離並回傳乾淨的去背結果。非同步——提交後輪詢或等待 webhook。

定價

依輸出最長邊定價(尺寸分級——例如 512 px 為 2 點數,1024 px 為 10 點數)。執行作業前請呼叫 /cost 端點取得精確金額。

參數

參數型別必填說明
source_typestring是"url"(input_value 為公開的 http(s) 圖片 URL)或 "base64"(input_value 為 base64 字串或 data: URL)其中之一。
input_valuestring是來源圖片:source_type 為 "url" 時為 http(s) URL,為 "base64" 時為 base64 圖片資料。
widthnumber是目標寬度(像素,64–2048)。
heightnumber是目標高度(像素,64–2048)。
seednumber否選用。用於可重現輸出的固定整數 seed;省略時使用隨機 seed。

輪詢與結果

非同步作業會回傳一個 taskId。輪詢任務直到其狀態為終態值,再讀取結果。要輪詢哪條路由取決於你的金鑰類型——這是最重要、務必做對的一件事。

動作個人金鑰企業金鑰
輪詢任務狀態GET /ai/tasks/{taskId}GET /ai/org-services/tasks/{taskId}
重新簽發全新的下載 URL從狀態回應中讀取GET /ai/org-services/tasks/{taskId}/outputs

企業金鑰必須輪詢 /ai/org-services 路由

將企業金鑰(vber_org_sk_)送往個人 /ai/tasks 路由會回傳 401 INVALID_API_KEY——個人路由只接受個人金鑰。企業作業請一律在 /ai/org-services/tasks/{taskId} 輪詢。cancel 與 batch-status 僅限個人金鑰。

任務會歷經這些值。一旦到達終態即停止輪詢:completed、failed、cancelled 或 timeout。

createdqueueddispatchingsubmittedprocessingcompletedfailedcancelledtimeout

當 status 為 completed 時,result.assets 承載輸出圖片。每個 asset 都含有 url(會過期的預簽下載連結)、mimeType 與 index;width、height、size 與 expiresAt 於可得時出現。請及時擷取 URL——企業金鑰可從 /outputs 端點重新請求全新的連結。

完成時,result.assets 承載去背輸出圖片。

已完成的任務

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

提交作業時傳入一個公開的 HTTPS webhookUrl(以及選用的 webhookSecret)。企業金鑰從主體頂層讀取這些值;個人金鑰則從 options 讀取。

若你設定了 webhookSecret,每次投遞都會包含一個 X-Webhook-Signature 標頭——為原始 JSON 負載的 HMAC-SHA256,以十六進位編碼。請用你的 secret 重新計算並比對,通過後再信任該負載。投遞也會帶有 X-Idempotency-Key(taskId + status),讓你可以忽略重複項。

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"