VberAI 開發者 API
VberAI 提供 RESTful HTTP API,將 AI 超強去背等能力嵌入到你的應用、遊戲與自動化流程。使用 API Key + 簽章驗證,統一錯誤碼,按點數計費。
VberAI 提供 RESTful HTTP API,將 AI 超強去背等能力嵌入到你的應用、遊戲與自動化流程。使用 API Key + 簽章驗證,統一錯誤碼,按點數計費。
透過 HTTP 直接生成圖片、去除背景並執行 VberAI 的 AI 管線——支援個人或企業 API 金鑰。
輸入一張扁平 UI 圖,得到可編輯圖層:一張背景 PNG、每個元素一張透明 PNG,以及一份 JSON 清單,給出每個圖層的名稱、型別、位置、尺寸和層級順序。將一張靜態圖智慧拆分為可編輯的多圖層場景元素,文字可編輯。適用於 UI 場景自動拆分與設計還原。
| 動作 | 個人金鑰 | 企業金鑰 |
|---|---|---|
| 提交任務 | POST /ai/tasks | POST /ai/org-services/ai-layer-split/execute-async |
| 輪詢任務狀態 | GET /ai/tasks/{taskId} | GET /ai/org-services/tasks/{taskId} |
| 重新簽發全新的下載 URL | GET /ai/tasks/{taskId}/outputs | GET /ai/org-services/tasks/{taskId}/outputs |
企業金鑰必須輪詢 /ai/org-services 路由
兩種 Key 的服務引數完全一致,只是外層包裝不同。
| 欄位 | 個人金鑰 | 企業金鑰 |
|---|---|---|
| 下方列出的服務引數。 | serviceCode + inputs | input |
webhookUrl | 可選 | 可選 |
webhookSecret | 可選 | 可選 |
個人金鑰
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
messages | array | 二選一 | 承載原圖的對話陣列:content[] 中必須包含一個 { "type": "image_url", "image_url": { "url": "…" } } 塊。URL 可以是公網 https 連結,也可以是內聯 data: URI。 |
referenceImage | string | 二選一 | 原圖的簡寫形式:公網 https 連結或內聯 data: URI,與 messages[] 二選一。 |
referenceWidth | number | 否 | 原圖的宣告寬度(畫素)。僅用於提交時預估價格檔位,實際尺寸以圖片本身為準。 |
referenceHeight | number | 否 | 原圖的宣告高度(畫素),作用同 referenceWidth。 |
imageConfig | object | 否 | 為後續生成選項預留,當前忽略。 |
無需自行託管效果圖,可直接把它作為 data: URI 放進請求。平臺會在服務端轉存,並把生成的 URL 交給管線,其餘流程完全不變。
{
"referenceImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
"referenceWidth": 1295,
"referenceHeight": 726
}/ai/taskscurl -X POST https://api.vberai.com/api/ai/tasks \
-H "X-API-Key: vber_sk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"serviceCode": "ai-layer-split",
"inputs": {
"messages": [
{
"role": "user",
"content": [
{ "type": "image_url", "image_url": { "url": "https://example.com/lobby.png" } }
]
}
],
"referenceWidth": 1295,
"referenceHeight": 726
},
"webhookUrl": "https://your-server.com/hook",
"webhookSecret": "whsec_your_secret"
}'提交響應 — HTTP 201
{
"success": true,
"message": "Created",
"data": {
"taskId": "6a9db1471ef5f25400621411",
"taskToken": "510932d23b39a0176837a3adfd6f64a773bc85f984417a7d6bcde08108494d30",
"status": "queued",
"estimatedCredits": 150,
"message": "Task queued for processing"
},
"timestamp": "2026-09-06T18:30:31.837Z"
}輪詢直到 status 變為 completed 或 failed。任務記錄與產物檔案保留 7 天。
任務會歷經這些值。一旦到達終態即停止輪詢:completed、failed、cancelled 或 timeout。
| 欄位 | 說明 |
|---|---|
taskId | 任務標識,用於輪詢、取產物和關聯 webhook。 |
serviceCode | 固定為 ai-layer-split。 |
status | queued · processing · completed · failed · cancelled · timeout。 |
progress | 後端上報時給出的粗略進度,否則為 null。 |
provider | 執行通道,統一上報為 external。 |
hasResult | result 已就緒時為 true。 |
error | 失敗原因;任務正常時為 null。 |
createdAt · startedAt · completedAt | 建立、開始執行與完成時間(ISO 8601,UTC)。 |
expiresAt | 任務記錄與產物的清理時間,完成後 7 天。 |
creditsEstimated · creditsActual | 提交時預留與完成時實際扣除的積分。成功時兩者一致;失敗全額退回。 |
outputCount | 返回的產物數量。 |
result | 下文描述的結果物件,任務完成後出現。 |
outputs 介面返回同一個 result 物件,並重新簽發下載 URL —— 連結過期後再調一次即可。
{
"success": true,
"data": {
"taskId": "6a9db1431ef5f254006213e0",
"status": "completed",
"result": { "type": "images", "assets": [ … ], "text": "{ … }" },
"completedAt": "2026-09-06T18:32:26.326Z"
}
}設定 webhookUrl 後,平臺會以 POST 推送與輪詢完全相同的內容。設定 webhookSecret 可獲得簽名頭用於校驗。
若你設定了 webhookSecret,每次投遞都會包含一個 X-Webhook-Signature 標頭——為原始 JSON 負載的 HMAC-SHA256,以十六進位編碼。請用你的 secret 重新計算並比對,通過後再信任該負載。投遞也會帶有 X-Idempotency-Key(taskId + status),讓你可以忽略重複項。
Webhook 回撥內容
{
"taskId": "6a9db1431ef5f254006213e0",
"serviceCode": "ai-layer-split",
"status": "completed",
"timestamp": "2026-09-06T18:32:26.401Z",
"result": {
"type": "images",
"assets": [ { "index": 0, "name": "Lbg", "url": "https://assets.vberai.org/…/0.png?<signed-query>", "mimeType": "image/png", "size": 5067542, "sha256": "7ceb4dad…" }, … ],
"text": "{\"imageSize\":{\"width\":1295,\"height\":726},\"nodes\":[…]}"
}
}Webhook · 任務失敗
{
"taskId": "6a9db1431ef5f254006213e0",
"serviceCode": "ai-layer-split",
"status": "failed",
"timestamp": "2026-09-06T18:32:26.401Z",
"error": { "code": "EXECUTION_ERROR", "message": "Task processing failed" }
}查詢任務狀態
/ai/tasks/{taskId}curl https://api.vberai.com/api/ai/tasks/{taskId} \
-H "X-API-Key: vber_sk_YOUR_KEY"獲取產物
/ai/tasks/{taskId}/outputscurl https://api.vberai.com/api/ai/tasks/{taskId}/outputs \
-H "X-API-Key: vber_sk_YOUR_KEY"result 有兩部分:assets[] 裡的圖層圖片,以及 text 裡以 JSON 字串給出的圖層清單。assets[].name 與圖層的 id 一一對應。
| 欄位 | 型別 | 說明 |
|---|---|---|
index | number | 在 assets 陣列中的位置。 |
name | string | 圖層 id,與圖層樹中對應節點的 id 相同 —— 圖片與幾何資訊就是靠它配對的。 |
url | string | 簽名下載連結,請原樣使用,不要去掉查詢串。 |
mimeType | "image/png" | 固定為帶 alpha 通道的 image/png。 |
size | number | 檔案位元組數。 |
sha256 | string | 檔案的 SHA-256,可用於校驗與去重。 |
s3Key | string | 內部物件鍵,僅供參考。 |
id 由服務端分配,在同一個任務內穩定不變,字首說明了圖層的性質。
| 值 | 意義 |
|---|---|
Lbg | 背景 PNG:整幅圖移除全部已識別元素並修補空缺後的結果。每個任務一張,位於最底層。它可能大於 imageSize,請按你放置的尺寸縮放。 |
A001, A002, … | 每個影象元素一張 PNG,按清單順序編號。透明底,被其它元素遮住的部分已補全。畫素尺寸等於 box × imageSize。 |
T001, T002, … | 文字元素。刻意不出圖 —— 你拿到的是準確的文字內容與樣式,可以重建為真正的文字。 |
| group | 分組條目。不帶圖片,只說明哪些圖層屬於同一組。 |
已完成的任務
{
"success": true,
"data": {
"taskId": "6a9db1431ef5f254006213e0",
"serviceCode": "ai-layer-split",
"status": "completed",
"progress": null,
"provider": "external",
"hasResult": true,
"error": null,
"createdAt": "2026-09-06T18:30:27.398Z",
"startedAt": "2026-09-06T18:30:29.012Z",
"completedAt": "2026-09-06T18:32:26.326Z",
"expiresAt": "2026-09-13T18:32:26.326Z",
"creditsEstimated": 150,
"creditsActual": 150,
"outputCount": 23,
"result": {
"type": "images",
"assets": [
{
"index": 0,
"url": "https://assets.vberai.org/tmp/user-assets/6a76f458…/task_6a9db143…_background/0.png?<signed-query>",
"mimeType": "image/png",
"s3Key": "tmp/user-assets/6a76f458…/task_6a9db143…_background/0.png",
"size": 5067542,
"sha256": "7ceb4dad585d2c60368e35c994ea53819b45f29f84fa5ec36704e9b3794a5f5e",
"name": "Lbg"
},
{
"index": 1,
"url": "https://assets.vberai.org/ai-deliveries/6a76f458…/task_6a9db143…/A001-ab405a4a….png?<signed-query>",
"mimeType": "image/png",
"s3Key": "ai-deliveries/6a76f458…/task_6a9db143…/A001-ab405a4a….png",
"size": 73117,
"sha256": "ab405a4a607a7c9e95bd5dba0150f84743c73362f482bbeb990fc4687c90055e",
"name": "A001"
},
… 21 more "A002" … "A022" assets …
],
"text": "{\"imageSize\":{\"width\":1295,\"height\":726},\"nodes\":[{\"id\":\"Lbg\",…},{\"id\":\"A001\",…},…]}"
}
}
}result.text 是 JSON 字串,請先解析。它列出每個圖層的名稱、型別、位置、尺寸、分組與層級順序。
| 欄位 | 型別 | 說明 |
|---|---|---|
imageSize | { width, height } | 被分析圖片的畫素尺寸。所有 box 都是它的比例值 —— 乘以它(或你想要的任意尺寸)即得畫素。 |
nodes | LayerNode[] | 所有圖層的平鋪陣列。分組由 parentId 給出,層級順序由 paintOrder 給出;陣列本身的順序沒有含義。 |
| 欄位 | 型別 | 說明 |
|---|---|---|
id | string | 圖層 id,與對應的 assets[].name 完全相同(Lbg、A001、T001 …),用它把圖層和它的 PNG 配對。 |
name | string | AI 推斷出的可讀名稱,例如 join_room_card。具有描述性但不保證唯一 —— 用 id 作鍵,用 name 展示。 |
kind | string | 圖層型別,見下表。 |
box | [x, y, w, h] | 位置與尺寸,形如 [x, y, 寬, 高],為 imageSize 的比例值,原點在左上角。乘以 imageSize 即得畫素。 |
parentId | string | null | 所屬分組的 id,位於根層級時為 null。 |
paintOrder | number | 同一父級下的層級順序,升序表示由後向前。背景為 -1。 |
occluded | boolean | 為 true 表示該元素有部分被其它元素遮擋,已經過補全重建。 |
instances | [x, y, w, h][] | 同一元素重複出現的其餘位置。在這些框上放同一張 PNG,無需再請求圖片。 |
text | object | 文字樣式,僅當 kind 為 text 時出現。 |
| 值 | 意義 |
|---|---|
background | 修補後的背景,只有一張,最先繪製。 |
group | 用於巢狀的容器,本身不帶圖片。 |
ui | 面板、卡片、按鈕等介面元素,帶 PNG。 |
icon | 小圖示,帶 PNG,處理方式與 ui 相同。 |
text | 程式文字,不帶 PNG,請重建為可編輯文字。 |
| 欄位 | 型別 | 說明 |
|---|---|---|
text | string | 從效果圖中識別出的文字內容,保持原語言。 |
fontSizePct | number | 字形高度相對 imageSize.height 的比例。乘以你使用的高度即得畫素字號。 |
color | "#RRGGBB" | 字形填充色。 |
fontWeight | 100–900 | 字重數值。 |
italic | boolean | 是否為斜體。 |
align | "LEFT" | "CENTER" | "RIGHT" | 在框內的水平對齊方式。 |
fontFamily | string | 建議使用的字型族;不可用時回退到你自己的預設字型。 |
strokeColor | "#RRGGBB" | 字形描邊顏色(文字帶描邊時給出)。 |
strokeWidthPct | number | 描邊寬度相對 imageSize.height 的比例。 |
shadow | { color, dxPct, dyPct, blurPct } | 投影:顏色,以及相對 imageSize 寬高比例給出的偏移與模糊。 |
圖層清單(節選)
{
"imageSize": { "width": 1295, "height": 726 },
"nodes": [
{ "id": "Lbg", "name": "background", "kind": "background", "box": [0, 0, 1, 1], "parentId": null, "paintOrder": -1, "occluded": false },
{ "id": "A001", "name": "player_info_bg", "kind": "ui", "box": [0.0026, 0, 0.2644, 0.1322], "parentId": null, "paintOrder": 1, "occluded": false },
{ "id": "A005", "name": "player_avatar", "kind": "ui", "box": [0.0108, 0.0069, 0.068, 0.1157], "parentId": null, "paintOrder": 5, "occluded": false },
{ "id": "A013", "name": "join_room_card", "kind": "ui", "box": [0.3153, 0.2546, 0.1825, 0.6906], "parentId": null, "paintOrder": 13, "occluded": false },
{
"id": "T001", "name": "player_name", "kind": "text",
"box": [0.0827, 0.0193, 0.1543, 0.0427], "parentId": null, "paintOrder": 18, "occluded": false,
"text": { "text": "明月清风晓星尘", "fontSizePct": 0.022, "color": "#FFFFFF", "fontWeight": 400, "align": "LEFT" }
},
{
"id": "T003", "name": "currency_1_amount", "kind": "text",
"box": [0.3614, 0.0372, 0.0533, 0.0455], "parentId": null, "paintOrder": 20, "occluded": false,
"text": {
"text": "87万", "fontSizePct": 0.0248, "color": "#FFFFFF", "fontWeight": 700, "align": "CENTER",
"strokeColor": "#5C3A21", "strokeWidthPct": 0.0028
}
},
… 23 more nodes …
]
}結構
// JSON.parse(result.text)
{
imageSize: { width, height }, // px of the analysed image
nodes: [
{
id: "Lbg" | "A001" | "T001" | "<group id>", // == asset name
name: "join_room_card", // AI-given, may repeat
kind: "background" | "group" | "ui" | "icon" | "text",
box: [x, y, w, h], // fractions 0..1 of imageSize
parentId: null | "<group id>",
paintOrder: -1 | 0 | 1 | ..., // ascending = bottom → top (siblings)
occluded: false,
instances: [[x, y, w, h]], // optional: repeated placements
text: { // only when kind === "text"
text, fontSizePct, color, fontWeight, italic, align,
fontFamily, strokeColor, strokeWidthPct,
shadow: { color, dxPct, dyPct, blurPct }
}
}
]
}位置和尺寸都是比例值,因此同一份清單在任意畫素尺寸下都適用。
生成放置清單
const { result } = task; // from polling, outputs or the webhook
const tree = JSON.parse(result.text);
const { width: W, height: H } = tree.imageSize; // reference pixel size
const png = Object.fromEntries(result.assets.map((a) => [a.name, a.url]));
// 1) box fractions -> pixels, at whatever size you work at
const px = ([x, y, w, h]) => ({ x: x * W, y: y * H, width: w * W, height: h * H });
// 2) back -> front within each parent
const childrenOf = (parentId) =>
tree.nodes
.filter((n) => n.parentId === parentId)
.sort((a, b) => a.paintOrder - b.paintOrder);
// 3) flatten into a placement list your app can consume
function collect(parentId = null, out = []) {
for (const n of childrenOf(parentId)) {
if (n.kind === "group") { collect(n.id, out); continue; }
for (const box of [n.box, ...(n.instances ?? [])]) {
out.push({
id: n.id,
name: n.name, // e.g. "join_room_card"
kind: n.kind, // background | ui | icon | text
...px(box), // x, y, width, height in px
order: n.paintOrder,
image: n.kind === "text" ? null : png[n.id],
text: n.text ?? null, // content + styling, text only
});
}
}
return out;
}
const layers = collect(); // ready to place or import
每次呼叫一口價,按原圖長邊所處的檔位計費。提交時以 estimatedCredits 返回,完成時扣除;任務失敗全額退回。
| 檔位 | 長邊 | 積分 |
|---|---|---|
1K | ≤ 1024 px | 120 |
2K | ≤ 2048 px | 180 |
4K | > 2048 px | 250 |
| 值 | 說明 |
|---|---|
2048 px | 分析前會把原圖縮放到長邊 2048 畫素。 |
300 | 單張圖最多識別 300 個元素。 |
20 MB | 內聯 base64 媒體單項上限 20 MB。 |
| 2–3 分鐘 | 端到端典型耗時。 |
| 7 天 | 任務記錄與產物的保留時長。 |
| 約 1 小時 | 簽名下載連結的有效期。 |
提交階段的錯誤同步返回;執行階段的錯誤表現為任務狀態 failed 並附帶 error 物件。
| 狀態 | 錯誤碼 | 意義 |
|---|---|---|
| 400 | — | 請求格式有誤,最常見的是 messages[] 與 referenceImage 都沒有提供原圖。 |
| 401 | INVALID_API_KEY · INVALID_ORG_API_KEY | 缺少 API Key 或 Key 無效。 |
| 402 | INSUFFICIENT_CREDITS · INSUFFICIENT_ORG_CREDITS | 積分不足以支付該圖片所屬解析度檔位。 |
| 403 | API_SERVICE_NOT_ALLOWED · ORG_DISABLED | 該 Key 或該企業沒有呼叫此服務的許可權。 |
| 413 | — | 內聯 base64 圖片超過 20 MB 上限,請改用 https 連結。 |
| 429 | RATE_LIMIT_MINUTE · RATE_LIMIT_DAY · CONCURRENCY_LIMIT_EXCEEDED | 觸發頻率或併發限制,稍作退避後重試。 |
| failed | error.code | 任務開始後執行失敗。error.code 與 error.message 說明原因,預留積分全額退回。 |
錯誤響應 — HTTP 400
{
"success": false,
"message": "A reference image is required: provide it as an `image_url` part inside messages[].content[], or pass `referenceImage` directly.",
"timestamp": "2026-09-06T18:30:27.398Z"
}失敗任務(輪詢回應)
{
"success": true,
"data": {
"taskId": "6a9db1431ef5f254006213e0",
"serviceCode": "ai-layer-split",
"status": "failed",
"hasResult": false,
"error": { "code": "EXECUTION_ERROR", "message": "Task processing failed" },
"creditsEstimated": 150,
"creditsActual": 0,
"outputCount": 0
}
}