VberAI 開發者 API

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

API v1
穩定版

API 文件

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

AI 圖層拆分

輸入一張扁平 UI 圖,得到可編輯圖層:一張背景 PNG、每個元素一張透明 PNG,以及一份 JSON 清單,給出每個圖層的名稱、型別、位置、尺寸和層級順序。

將一張靜態圖智慧拆分為可編輯的多圖層場景元素,文字可編輯。適用於 UI 場景自動拆分與設計還原。

工作流程

  1. 1提交效果圖後立即拿到 taskId —— 任務非同步執行,通常需要 2 到 3 分鐘。
  2. 2輪詢任務狀態,或等待 webhook 在完成時回撥你。
  3. 3用簽名 URL 下載 PNG,讀取 result.text 獲取圖層清單。

介面地址

動作個人金鑰企業金鑰
提交任務POST /ai/tasksPOST /ai/org-services/ai-layer-split/execute-async
輪詢任務狀態GET /ai/tasks/{taskId}GET /ai/org-services/tasks/{taskId}
重新簽發全新的下載 URLGET /ai/tasks/{taskId}/outputsGET /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 僅限個人金鑰。

請求外層結構

兩種 Key 的服務引數完全一致,只是外層包裝不同。

欄位個人金鑰企業金鑰
下方列出的服務引數。serviceCode + inputsinput
webhookUrl可選可選
webhookSecret可選可選

個人金鑰

兩種 Key 都可以只輪詢:不給 webhookUrl 就自行查詢任務狀態,給了則在完成時收到回呼。填寫時必須是公網 https 位址。

服務引數

參數型別必填說明
messagesarray二選一承載原圖的對話陣列:content[] 中必須包含一個 { "type": "image_url", "image_url": { "url": "…" } } 塊。URL 可以是公網 https 連結,也可以是內聯 data: URI。
referenceImagestring二選一原圖的簡寫形式:公網 https 連結或內聯 data: URI,與 messages[] 二選一。
referenceWidthnumber否原圖的宣告寬度(畫素)。僅用於提交時預估價格檔位,實際尺寸以圖片本身為準。
referenceHeightnumber否原圖的宣告高度(畫素),作用同 referenceWidth。
imageConfigobject否為後續生成選項預留,當前忽略。
原圖可以透過 messages[](OpenAI 風格的內容塊)傳入,也可以用 referenceImage 傳入,二者必居其一。

內聯 base64 圖片

無需自行託管效果圖,可直接把它作為 data: URI 放進請求。平臺會在服務端轉存,並把生成的 URL 交給管線,其餘流程完全不變。

json
{
  "referenceImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "referenceWidth": 1295,
  "referenceHeight": 726
}
內聯媒體單項上限 20 MB(按解碼後的體積計,而非 base64 文字長度)。更大的原圖請改用 https 連結。
POST/ai/tasks
bash
curl -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

json
{
  "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。

queuedprocessingcompletedfailedcancelledtimeout

任務欄位

欄位說明
taskId任務標識,用於輪詢、取產物和關聯 webhook。
serviceCode固定為 ai-layer-split。
statusqueued · processing · completed · failed · cancelled · timeout。
progress後端上報時給出的粗略進度,否則為 null。
provider執行通道,統一上報為 external。
hasResultresult 已就緒時為 true。
error失敗原因;任務正常時為 null。
createdAt · startedAt · completedAt建立、開始執行與完成時間(ISO 8601,UTC)。
expiresAt任務記錄與產物的清理時間,完成後 7 天。
creditsEstimated · creditsActual提交時預留與完成時實際扣除的積分。成功時兩者一致;失敗全額退回。
outputCount返回的產物數量。
result下文描述的結果物件,任務完成後出現。

獲取結果

outputs 介面返回同一個 result 物件,並重新簽發下載 URL —— 連結過期後再調一次即可。

json
{
  "success": true,
  "data": {
    "taskId": "6a9db1431ef5f254006213e0",
    "status": "completed",
    "result": { "type": "images", "assets": [ … ], "text": "{ … }" },
    "completedAt": "2026-09-06T18:32:26.326Z"
  }
}

Webhook

設定 webhookUrl 後,平臺會以 POST 推送與輪詢完全相同的內容。設定 webhookSecret 可獲得簽名頭用於校驗。

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

Webhook 回撥內容

json
{
  "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 · 任務失敗

json
{
  "taskId": "6a9db1431ef5f254006213e0",
  "serviceCode": "ai-layer-split",
  "status": "failed",
  "timestamp": "2026-09-06T18:32:26.401Z",
  "error": { "code": "EXECUTION_ERROR", "message": "Task processing failed" }
}

查詢任務狀態

GET/ai/tasks/{taskId}
bash
curl https://api.vberai.com/api/ai/tasks/{taskId} \
  -H "X-API-Key: vber_sk_YOUR_KEY"

獲取產物

GET/ai/tasks/{taskId}/outputs
bash
curl https://api.vberai.com/api/ai/tasks/{taskId}/outputs \
  -H "X-API-Key: vber_sk_YOUR_KEY"

結果物件

result 有兩部分:assets[] 裡的圖層圖片,以及 text 裡以 JSON 字串給出的圖層清單。assets[].name 與圖層的 id 一一對應。

產物列表

欄位型別說明
indexnumber在 assets 陣列中的位置。
namestring圖層 id,與圖層樹中對應節點的 id 相同 —— 圖片與幾何資訊就是靠它配對的。
urlstring簽名下載連結,請原樣使用,不要去掉查詢串。
mimeType"image/png"固定為帶 alpha 通道的 image/png。
sizenumber檔案位元組數。
sha256string檔案的 SHA-256,可用於校驗與去重。
s3Keystring內部物件鍵,僅供參考。
下載連結為短期有效(約 1 小時)。過期後重新呼叫 outputs 介面即可換取新連結,檔案本身保留 7 天。

圖層命名規則

id 由服務端分配,在同一個任務內穩定不變,字首說明了圖層的性質。

值意義
Lbg背景 PNG:整幅圖移除全部已識別元素並修補空缺後的結果。每個任務一張,位於最底層。它可能大於 imageSize,請按你放置的尺寸縮放。
A001, A002, …每個影象元素一張 PNG,按清單順序編號。透明底,被其它元素遮住的部分已補全。畫素尺寸等於 box × imageSize。
T001, T002, …文字元素。刻意不出圖 —— 你拿到的是準確的文字內容與樣式,可以重建為真正的文字。
group分組條目。不帶圖片,只說明哪些圖層屬於同一組。

已完成的任務

json
{
  "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)

result.text 是 JSON 字串,請先解析。它列出每個圖層的名稱、型別、位置、尺寸、分組與層級順序。

頂層欄位

欄位型別說明
imageSize{ width, height }被分析圖片的畫素尺寸。所有 box 都是它的比例值 —— 乘以它(或你想要的任意尺寸)即得畫素。
nodesLayerNode[]所有圖層的平鋪陣列。分組由 parentId 給出,層級順序由 paintOrder 給出;陣列本身的順序沒有含義。

圖層條目

欄位型別說明
idstring圖層 id,與對應的 assets[].name 完全相同(Lbg、A001、T001 …),用它把圖層和它的 PNG 配對。
namestringAI 推斷出的可讀名稱,例如 join_room_card。具有描述性但不保證唯一 —— 用 id 作鍵,用 name 展示。
kindstring圖層型別,見下表。
box[x, y, w, h]位置與尺寸,形如 [x, y, 寬, 高],為 imageSize 的比例值,原點在左上角。乘以 imageSize 即得畫素。
parentIdstring | null所屬分組的 id,位於根層級時為 null。
paintOrdernumber同一父級下的層級順序,升序表示由後向前。背景為 -1。
occludedboolean為 true 表示該元素有部分被其它元素遮擋,已經過補全重建。
instances[x, y, w, h][]同一元素重複出現的其餘位置。在這些框上放同一張 PNG,無需再請求圖片。
textobject文字樣式,僅當 kind 為 text 時出現。

圖層型別

值意義
background修補後的背景,只有一張,最先繪製。
group用於巢狀的容器,本身不帶圖片。
ui面板、卡片、按鈕等介面元素,帶 PNG。
icon小圖示,帶 PNG,處理方式與 ui 相同。
text程式文字,不帶 PNG,請重建為可編輯文字。

文字屬性

欄位型別說明
textstring從效果圖中識別出的文字內容,保持原語言。
fontSizePctnumber字形高度相對 imageSize.height 的比例。乘以你使用的高度即得畫素字號。
color"#RRGGBB"字形填充色。
fontWeight100–900字重數值。
italicboolean是否為斜體。
align"LEFT" | "CENTER" | "RIGHT"在框內的水平對齊方式。
fontFamilystring建議使用的字型族;不可用時回退到你自己的預設字型。
strokeColor"#RRGGBB"字形描邊顏色(文字帶描邊時給出)。
strokeWidthPctnumber描邊寬度相對 imageSize.height 的比例。
shadow{ color, dxPct, dyPct, blurPct }投影:顏色,以及相對 imageSize 寬高比例給出的偏移與模糊。

圖層清單(節選)

json
{
  "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 …
  ]
}

結構

javascript
// 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 }
      }
    }
  ]
}

使用圖層

位置和尺寸都是比例值,因此同一份清單在任意畫素尺寸下都適用。

  1. 1選定你要使用的畫素尺寸 —— imageSize 是被分析的尺寸,每個 box 都是它的比例值。
  2. 2把 Lbg 放在最底層,鋪滿整個區域。
  3. 3排列其餘圖層:按 parentId 分組,再按 paintOrder 升序(由後向前)排序。
  4. 4把每個 ui 與 icon 的 PNG 放到它的 box 上,instances 的每個位置各放一次;文字圖層則使用 text 裡的文字內容與樣式。
Lbg 可能比 imageSize 大,請縮放它,不要假定兩者相同。
文字給出的是文字內容加樣式而不是圖片,這樣它始終可編輯、可翻譯,並且在任意尺寸下都清晰。

生成放置清單

javascript
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 px120
2K≤ 2048 px180
4K> 2048 px250
檔位價格可在後臺調整,因此請以提交響應中的 estimatedCredits 作為該次呼叫的準確金額。

限制

值說明
2048 px分析前會把原圖縮放到長邊 2048 畫素。
300單張圖最多識別 300 個元素。
20 MB內聯 base64 媒體單項上限 20 MB。
2–3 分鐘端到端典型耗時。
7 天任務記錄與產物的保留時長。
約 1 小時簽名下載連結的有效期。

錯誤處理

提交階段的錯誤同步返回;執行階段的錯誤表現為任務狀態 failed 並附帶 error 物件。

狀態錯誤碼意義
400—請求格式有誤,最常見的是 messages[] 與 referenceImage 都沒有提供原圖。
401INVALID_API_KEY · INVALID_ORG_API_KEY缺少 API Key 或 Key 無效。
402INSUFFICIENT_CREDITS · INSUFFICIENT_ORG_CREDITS積分不足以支付該圖片所屬解析度檔位。
403API_SERVICE_NOT_ALLOWED · ORG_DISABLED該 Key 或該企業沒有呼叫此服務的許可權。
413—內聯 base64 圖片超過 20 MB 上限,請改用 https 連結。
429RATE_LIMIT_MINUTE · RATE_LIMIT_DAY · CONCURRENCY_LIMIT_EXCEEDED觸發頻率或併發限制,稍作退避後重試。
failederror.code任務開始後執行失敗。error.code 與 error.message 說明原因,預留積分全額退回。

錯誤響應 — HTTP 400

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

失敗任務(輪詢回應)

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