VberAI 開發者 API
VberAI 提供 RESTful HTTP API,將 AI 超強去背等能力嵌入到你的應用、遊戲與自動化流程。使用 API Key + 簽章驗證,統一錯誤碼,按點數計費。
VberAI 提供 RESTful HTTP API,將 AI 超強去背等能力嵌入到你的應用、遊戲與自動化流程。使用 API Key + 簽章驗證,統一錯誤碼,按點數計費。
透過 HTTP 直接生成圖片、去除背景並執行 VberAI 的 AI 管線——支援個人或企業 API 金鑰。
VberAI API 將驅動 studio 的各種 AI 管線——背景移除、超級去背、圖片生成等——以簡單的 HTTP 端點形式開放。以 API 金鑰進行驗證、提交作業,接著讀回結果或透過 webhook 接收。
統一的請求形式
每個服務都接收 { input } 請求主體,並回傳一個可輪詢或透過 webhook 接收的任務。
兩種金鑰類型
個人金鑰供個別開發者使用,企業金鑰供組織的伺服器對伺服器用途使用。
可預期的計費
提交時預留點數、成功時結算;失敗的作業會自動退款。
# 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-API-Key 標頭傳送的 API 金鑰進行驗證。金鑰分兩種,且各自使用不同的路由——為你的金鑰類型選錯路由,是造成 401 最常見的原因。
個人金鑰 —— 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 |
| 取得方式 | 自助建立,帳戶設定 | 組織管理員,企業入口網站 |
| 計費對象 | 個人點數 | 組織點數 |
| 限制 | 每分鐘 / 每日請求限制 | 每組織並行數(自訂) |
X-API-Key: vber_sk_... # personal key
X-API-Key: vber_org_sk_... # enterprise key基礎 URL
https://api.vberai.com/api每個服務都接收一個 JSON 主體,其中的 input 物件承載該服務的參數。取得結果的方式取決於服務的執行模式。
同步服務
快速服務(例如聊天或文字翻譯)會在同一個回應中以 HTTP 200 內嵌回傳結果,無需輪詢。
非同步服務
較重的服務(圖片生成、去背、背景移除)會回傳 HTTP 202 與一個 taskId。完成後輪詢任務或透過 webhook 接收結果。
個人金鑰
企業金鑰
{
"input": {
"imageUrl": "https://example.com/photo.png"
},
"webhookUrl": "https://your-server.com/hook"
}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 路由
任務會歷經這些值。一旦到達終態即停止輪詢:completed、failed、cancelled 或 timeout。
當 status 為 completed 時,result.assets 承載輸出圖片。每個 asset 都含有 url(會過期的預簽下載連結)、mimeType 與 index;width、height、size 與 expiresAt 於可得時出現。請及時擷取 URL——企業金鑰可從 /outputs 端點重新請求全新的連結。
# 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"已完成的任務
{
"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 輪詢)再重試。
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000除了輪詢,你也可以讓 VberAI 在任務到達終態時,將結果 POST 至你的伺服器。
提交作業時傳入一個公開的 HTTPS webhookUrl(以及選用的 webhookSecret)。企業金鑰從主體頂層讀取這些值;個人金鑰則從 options 讀取。
若你設定了 webhookSecret,每次投遞都會包含一個 X-Webhook-Signature 標頭——為原始 JSON 負載的 HMAC-SHA256,以十六進位編碼。請用你的 secret 重新計算並比對,通過後再信任該負載。投遞也會帶有 X-Idempotency-Key(taskId + status),讓你可以忽略重複項。
{
"input": { "imageUrl": "https://example.com/photo.png" },
"webhookUrl": "https://your-server.com/hook",
"webhookSecret": "whsec_your_secret"
}驗證 webhook(Node.js)
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 端點以預覽精確費用。
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}}'{
"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 | 當前日視窗內剩餘的請求數。 |
企業金鑰不以請求速率為限,而是以你的組織可同時執行的作業數為限。此上限依組織自訂(且可能無上限);超過會回傳 429 CONCURRENCY_LIMIT_EXCEEDED。企業回應不帶 X-RateLimit 標頭。
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 59
X-RateLimit-Limit-Day: 2000
X-RateLimit-Remaining-Day: 1997每個回應都含有 success、message 與 timestamp。失敗時,由錯誤碼標識問題。請針對錯誤碼而非訊息文字進行分支——訊息可能變動,且僅提供英文。
錯誤碼的所在位置
| 狀態 | 意義 |
|---|---|
| 200 | 成功——結果內嵌回傳。 |
| 202 | 已接受——已建立非同步任務;請輪詢或等待 webhook。 |
| 400 | 錯誤的請求——輸入無效,或針對該服務的執行模式使用了錯誤的端點。 |
| 401 | 未授權——API 金鑰缺失、格式錯誤或類型不符。 |
| 402 | 需付款——點數不足。 |
| 403 | 禁止——該金鑰或帳戶不得使用此服務。 |
| 404 | 找不到——未知任務,或非屬於你的任務。 |
| 429 | 請求過多——超過速率或並行上限。 |
| 500 | 伺服器錯誤——請重試;作業(若有)會退款。 |
| 錯誤碼 | 位置 | 意義 |
|---|---|---|
INSUFFICIENT_CREDITS | errorCode | 個人點數不足以執行該作業。 |
INSUFFICIENT_ORG_CREDITS | errorCode | 組織點數不足以執行該作業。 |
ORG_API_KEY_REQUIRED | data.code | 此端點需要企業 API 金鑰(X-API-Key)。 |
INVALID_ORG_API_KEY | data.code | 企業金鑰缺失、格式錯誤或已撤銷。 |
INVALID_API_KEY | data.code | API 金鑰格式無效——通常是以企業金鑰呼叫個人路由(或反之)。 |
API_SERVICE_NOT_ALLOWED | errorCode | 你的組織未獲核准使用此服務。 |
ORG_DISABLED | data.code | 組織帳戶已停用。 |
CONCURRENCY_LIMIT_EXCEEDED | errorCode | 你的組織並行作業過多。 |
SERVICE_NOT_EXTERNALLY_ACCESSIBLE | errorCode | 此服務不透過外部 API 提供。 |
TASK_NOT_FOUND | errorCode | 此金鑰下無此任務。 |
{
"success": false,
"errorCode": "INSUFFICIENT_ORG_CREDITS",
"message": "Insufficient organization credits",
"timestamp": "2026-01-15T10:30:00.000Z"
}各服務具體的請求與回應細節。範例同時呈現兩種金鑰類型——請選擇你所持金鑰對應的分頁。至於它們依賴的概念(輪詢、狀態、錯誤、計費),請參閱上方指南。
下方兩個服務有完整文件。至於你的金鑰可呼叫的完整即時服務清單——以及每個服務的參數規格——請查詢目錄端點。這是權威來源,因為可用性取決於你的方案與組織核准情況。
| 端點 | 說明 |
|---|---|
GET /ai/services | 列出你的金鑰可存取的服務。 |
GET /ai/external/services/{code}/spec | 取得單一服務的參數規格。 |
curl https://api.vberai.com/api/ai/services \
-H "X-API-Key: YOUR_API_KEY"