VberAI 開發者 API

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

API v1
穩定版

API 文件

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

簡介

VberAI API 將驅動 studio 的各種 AI 管線——背景移除、超級去背、圖片生成等——以簡單的 HTTP 端點形式開放。以 API 金鑰進行驗證、提交作業,接著讀回結果或透過 webhook 接收。

統一的請求形式

每個服務都接收 { input } 請求主體,並回傳一個可輪詢或透過 webhook 接收的任務。

兩種金鑰類型

個人金鑰供個別開發者使用,企業金鑰供組織的伺服器對伺服器用途使用。

可預期的計費

提交時預留點數、成功時結算;失敗的作業會自動退款。

運作方式

  1. 1在 X-API-Key 標頭中以你的 API 金鑰進行驗證。
  2. 2以 JSON { input } 請求主體向服務提交作業。
  3. 3內嵌讀取結果(同步服務),或輪詢任務 / 接收 webhook(非同步服務)。
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"

驗證與 API 金鑰

每個請求都以透過 X-API-Key 標頭傳送的 API 金鑰進行驗證。金鑰分兩種,且各自使用不同的路由——為你的金鑰類型選錯路由,是造成 401 最常見的原因。

把 API 金鑰當成密碼看待。只從你的後端傳送,若外洩就輪換,並為企業金鑰設定消費上限。

個人金鑰 —— vber_sk_

供個別開發者使用。可從你帳戶的 API 金鑰頁面自助建立(需具備開放 API 存取的方案)。以你的個人點數計費。使用 /ai/services 與 /ai/tasks 路由。

企業金鑰 —— vber_org_sk_

供組織的伺服器對伺服器用途使用。由組織管理員在企業入口網站簽發,並僅限於你的組織獲核准的服務。以你組織的點數池計費。使用 /ai/org-services 路由。

面向個人金鑰企業金鑰
金鑰前綴vber_sk_vber_org_sk_
路由前綴/ai/services, /ai/tasks/ai/org-services
取得方式自助建立,帳戶設定組織管理員,企業入口網站
計費對象個人點數組織點數
限制每分鐘 / 每日請求限制每組織並行數(自訂)
http
X-API-Key: vber_sk_...        # personal key
X-API-Key: vber_org_sk_...    # enterprise key

基礎 URL

text
https://api.vberai.com/api

請求與執行模式

每個服務都接收一個 JSON 主體,其中的 input 物件承載該服務的參數。取得結果的方式取決於服務的執行模式。

同步服務

快速服務(例如聊天或文字翻譯)會在同一個回應中以 HTTP 200 內嵌回傳結果,無需輪詢。

非同步服務

較重的服務(圖片生成、去背、背景移除)會回傳 HTTP 202 與一個 taskId。完成後輪詢任務或透過 webhook 接收結果。

個人金鑰

個人金鑰每個服務只使用單一端點:POST /ai/services/{code}/execute。同步服務內嵌回傳結果(200),非同步服務回傳任務(202)——都是同一個端點。

企業金鑰

企業金鑰使用兩個端點:同步服務用 /execute,非同步服務用 /execute-async。呼叫錯誤的端點會回傳 400,並告知你應使用哪個端點。
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" }

輪詢與結果

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

該輪詢哪條路由

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

企業金鑰必須輪詢 /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 端點重新請求全新的連結。

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"

已完成的任務

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

冪等性

冪等性讓你在網路錯誤後可以安全地重試提交,而不會建立重複的作業或被重複收費。

企業金鑰

在 /execute-async 上可選擇傳送 Idempotency-Key 標頭(由你產生、最多 200 個字元——UUID 最為理想)。以相同的金鑰重試會回傳原本的任務,而非建立新任務。伺服器只做去重;不會替你產生該金鑰。

個人金鑰

個人 API 金鑰請求目前不支援冪等金鑰。請在確認先前的請求並未建立任務後(以你收到的 taskId 輪詢)再重試。

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

Webhook

除了輪詢,你也可以讓 VberAI 在任務到達終態時,將結果 POST 至你的伺服器。

設定 Webhook

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

驗證簽章

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

投遞失敗會以退避方式重試數次。請以 2xx 回應以確認接收。
json
{
  "input": { "imageUrl": "https://example.com/photo.png" },
  "webhookUrl": "https://your-server.com/hook",
  "webhookSecret": "whsec_your_secret"
}

驗證 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();
});

點數與計費

AI 作業會消耗點數。個人與企業金鑰採用相同的定價——只有錢包不同:個人金鑰動用你的個人點數,企業金鑰動用你組織的點數池。

預留、結算、退款

作業被接受時預留點數,完成時結算為精確金額。若作業失敗或被取消,預留的點數會全額退回——你絕不會為失敗的作業付費。

費用如何計算

費用取決於服務。有些服務按每次請求收取固定金額;有些則隨輸出解析度(每像素)或依最長邊縮放。執行作業前,呼叫 cost 端點以預覽精確費用。

  • •按次——每次呼叫固定金額。
  • •按像素——隨輸出的 寬 × 高 縮放。
  • •按尺寸——依輸出的最長邊定價。
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
  }
}

速率限制

速率限制依金鑰類型而異。兩者皆在後端按服務設定——下方數值描述的是機制,而非固定數字。

個人金鑰 —— 請求速率

個人金鑰以每分鐘與每日的請求數為限,按服務設定。每個回應都會帶有下列標頭,方便你控制呼叫節奏。

標頭說明
X-RateLimit-Limit-Minute每分鐘允許的請求數。
X-RateLimit-Remaining-Minute當前分鐘視窗內剩餘的請求數。
X-RateLimit-Limit-Day每日允許的請求數。
X-RateLimit-Remaining-Day當前日視窗內剩餘的請求數。
沒有 X-RateLimit-Reset 標頭。發生 429 時,回應主體包含 retryAfter 與 resetIn。

企業金鑰 —— 並行

企業金鑰不以請求速率為限,而是以你的組織可同時執行的作業數為限。此上限依組織自訂(且可能無上限);超過會回傳 429 CONCURRENCY_LIMIT_EXCEEDED。企業回應不帶 X-RateLimit 標頭。

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

錯誤

每個回應都含有 success、message 與 timestamp。失敗時,由錯誤碼標識問題。請針對錯誤碼而非訊息文字進行分支——訊息可能變動,且僅提供英文。

錯誤碼的所在位置

企業錯誤是一致的:驗證問題將錯誤碼放在 data.code,而服務與計費問題則放在頂層的 errorCode。個人錯誤則因端點而異(頂層 errorCode、data.code 或 errors.code)——請讀取每個錯誤碼所註明的欄位。

HTTP 狀態碼

狀態意義
200成功——結果內嵌回傳。
202已接受——已建立非同步任務;請輪詢或等待 webhook。
400錯誤的請求——輸入無效,或針對該服務的執行模式使用了錯誤的端點。
401未授權——API 金鑰缺失、格式錯誤或類型不符。
402需付款——點數不足。
403禁止——該金鑰或帳戶不得使用此服務。
404找不到——未知任務,或非屬於你的任務。
429請求過多——超過速率或並行上限。
500伺服器錯誤——請重試;作業(若有)會退款。

常見錯誤碼

錯誤碼位置意義
INSUFFICIENT_CREDITSerrorCode個人點數不足以執行該作業。
INSUFFICIENT_ORG_CREDITSerrorCode組織點數不足以執行該作業。
ORG_API_KEY_REQUIREDdata.code此端點需要企業 API 金鑰(X-API-Key)。
INVALID_ORG_API_KEYdata.code企業金鑰缺失、格式錯誤或已撤銷。
INVALID_API_KEYdata.codeAPI 金鑰格式無效——通常是以企業金鑰呼叫個人路由(或反之)。
API_SERVICE_NOT_ALLOWEDerrorCode你的組織未獲核准使用此服務。
ORG_DISABLEDdata.code組織帳戶已停用。
CONCURRENCY_LIMIT_EXCEEDEDerrorCode你的組織並行作業過多。
SERVICE_NOT_EXTERNALLY_ACCESSIBLEerrorCode此服務不透過外部 API 提供。
TASK_NOT_FOUNDerrorCode此金鑰下無此任務。
json
{
  "success": false,
  "errorCode": "INSUFFICIENT_ORG_CREDITS",
  "message": "Insufficient organization credits",
  "timestamp": "2026-01-15T10:30:00.000Z"
}

API 文件

各服務具體的請求與回應細節。範例同時呈現兩種金鑰類型——請選擇你所持金鑰對應的分頁。至於它們依賴的概念(輪詢、狀態、錯誤、計費),請參閱上方指南。

可用服務

下方兩個服務有完整文件。至於你的金鑰可呼叫的完整即時服務清單——以及每個服務的參數規格——請查詢目錄端點。這是權威來源,因為可用性取決於你的方案與組織核准情況。

端點說明
GET /ai/services列出你的金鑰可存取的服務。
GET /ai/external/services/{code}/spec取得單一服務的參數規格。
bash
curl https://api.vberai.com/api/ai/services \
  -H "X-API-Key: YOUR_API_KEY"