VberAI API — RESTful Reference for Developers

The VberAI API is a RESTful HTTP API for embedding VberAI's AI capabilities (today: AI Super Matting) into your apps, games, and automation pipelines. Authentication uses API keys with signature-based requests; common error codes are standardised; per-call billing is paid in VberAI credits.

API DocsAI Layer Split

AI Layer Split

One flat UI image in, editable layers out: a background PNG, one transparent PNG per element, and a JSON list giving each layer's name, type, position, size and stacking order.

Splits one static image into editable multi-layer scene elements, with text kept editable. Built for automatic UI scene splitting and design reconstruction.

How it works

  1. 1Submit the flat screenshot and get a taskId back immediately — the job runs asynchronously and usually takes two to three minutes.
  2. 2Poll the task, or let the webhook call you when it finishes.
  3. 3Download the PNGs from the signed URLs and read result.text for the layer list.

Endpoints

ActionPersonal keyEnterprise key
SubmitPOST /ai/tasksPOST /ai/org-services/ai-layer-split/execute-async
Poll task statusGET /ai/tasks/{taskId}GET /ai/org-services/tasks/{taskId}
Re-sign fresh download URLsGET /ai/tasks/{taskId}/outputsGET /ai/org-services/tasks/{taskId}/outputs

Enterprise keys must poll the /ai/org-services route

An enterprise key (vber_org_sk_) sent to a personal /ai/tasks route returns 401 INVALID_API_KEY — the personal routes only accept personal keys. Always poll enterprise jobs at /ai/org-services/tasks/{taskId}. Cancel and batch-status are personal-key only.

Request envelope

The service parameters are identical for both key types; only the wrapper around them differs.

FieldPersonal keyEnterprise key
The service parameters listed below.serviceCode + inputsinput
webhookUrloptionaloptional
webhookSecretoptionaloptional

Personal key

Both key types may simply poll: leave webhookUrl out and check the task yourself, or set it to be called when the task finishes. When set, it must be a public https URL.

Service parameters

ParameterTypeRequiredDescription
messagesarrayone ofConversation array carrying the source image: content[] must include one { "type": "image_url", "image_url": { "url": "…" } } part. The URL may be a public https link or an inline data: URI.
referenceImagestringone ofShorthand for the source image: a public https URL or an inline data: URI. Use it instead of messages[].
referenceWidthnumberNoDeclared pixel width of the source. Only used to pick the price tier up front; the real size is measured from the image itself.
referenceHeightnumberNoDeclared pixel height of the source. Same purpose as referenceWidth.
imageConfigobjectNoReserved for future generation options. Ignored today.
Provide the source image either as messages[] (OpenAI-style content parts) or as referenceImage — one of the two is required.

Inline base64 images

Instead of hosting the screenshot yourself, put it straight into the request as a data: URI. The platform stores it server-side and hands the resulting URL to the pipeline, so nothing else changes.

json
{
  "referenceImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "referenceWidth": 1295,
  "referenceHeight": 726
}
Inline media is capped at 20 MB per item (the decoded size, not the base64 text). Larger sources must be passed as an https URL.
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"
}'

Submit response — 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"
}

Polling the task

Poll until status becomes completed or failed. The task record and its files stay available for seven days.

A task moves through these values. Stop polling once you reach a terminal status: completed, failed, cancelled or timeout.

queuedprocessingcompletedfailedcancelledtimeout

Task fields

FieldDescription
taskIdTask identifier — use it for polling, outputs and webhook correlation.
serviceCodeAlways ai-layer-split.
statusqueued · processing · completed · failed · cancelled · timeout.
progressCoarse progress when the backend reports it; null otherwise.
providerExecution channel. Always reported as external.
hasResulttrue once result is populated.
errorFailure reason; null while the task is healthy.
createdAt · startedAt · completedAtCreation, execution start and completion times (ISO 8601, UTC).
expiresAtWhen the task record and its files are purged — seven days after completion.
creditsEstimated · creditsActualCredits reserved at submit and actually charged at completion. They match on success; a failure refunds in full.
outputCountNumber of returned assets.
resultThe result object described below; present once the task completes.

Fetching the result

The outputs endpoint returns the same result object with freshly signed download URLs — call it again whenever a URL has expired.

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

Webhooks

When webhookUrl is set, the platform POSTs the same payload it would have returned from polling. Set webhookSecret to receive a signature header you can verify.

If you set a webhookSecret, each delivery includes an X-Webhook-Signature header — an HMAC-SHA256 of the raw JSON payload, hex-encoded. Recompute it with your secret and compare before trusting the payload. Deliveries also carry an X-Idempotency-Key (taskId + status) so you can ignore duplicates.

Webhook payload

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 · failed task

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

Poll task status

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

Fetch outputs

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

The result object

result has two parts: the layer images in assets[], and the layer list as a JSON string in text. assets[].name matches the id of its layer one to one.

Assets

FieldTypeDescription
indexnumberPosition in the assets array.
namestringLayer id. It equals the id of the matching node in the layer tree — this is how you pair an image with its geometry.
urlstringSigned download link. Fetch it as-is; do not strip the query string.
mimeType"image/png"Always image/png with an alpha channel.
sizenumberFile size in bytes.
sha256stringSHA-256 of the file, for integrity checks and deduplication.
s3KeystringInternal object key. Informational only.
Download URLs are short-lived (about an hour). Call the outputs endpoint again to obtain fresh ones — the underlying files live for seven days.

Layer naming

Ids are assigned by the server and are stable within one task. The prefix tells you what the layer is.

ValueMeaning
LbgThe background PNG: the whole image with every detected element removed and the gaps repainted. One per task, the bottom-most layer. It can come back larger than imageSize — scale it to the size you place at.
A001, A002, …One PNG per image element, numbered in list order. Transparent background, parts that were hidden behind other elements filled in. Its pixel size is box × imageSize.
T001, T002, …Text elements. No PNG on purpose — you get the exact characters and their styling instead, so you can recreate them as real text.
groupGrouping entries. No PNG; they only tell you which layers belong together.

Completed task

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\",…},…]}"
    }
  }
}

Layer list (result.text)

result.text is a JSON string — parse it. It lists every layer with its name, type, position, size, grouping and stacking order.

Top level

FieldTypeDescription
imageSize{ width, height }Pixel size of the analysed image. Every box is a fraction of it — multiply by it (or by any size you prefer) to get pixels.
nodesLayerNode[]All layers in one flat array. Grouping comes from parentId, stacking from paintOrder; the array order itself means nothing.

Layer entry

FieldTypeDescription
idstringLayer id, identical to the matching assets[].name (Lbg, A001, T001 …). Use it to pair a layer with its PNG.
namestringReadable name inferred by the AI, e.g. join_room_card. Descriptive but not guaranteed unique — key on id, show name.
kindstringLayer type; see the table below.
box[x, y, w, h]Position and size as [x, y, width, height], given as fractions of imageSize with the origin at the top left. Multiply by imageSize for pixels.
parentIdstring | nullId of the containing group, or null at root level.
paintOrdernumberStacking order among layers with the same parent, ascending from back to front. The background is -1.
occludedbooleantrue when part of this element was hidden behind another one and had to be reconstructed.
instances[x, y, w, h][]Extra positions of the same repeated element. Place the same PNG at each of these boxes instead of asking for more images.
textobjectText styling; present only when kind is text.

Layer kinds

ValueMeaning
backgroundThe inpainted backdrop. Exactly one, drawn first.
groupA container used for nesting. No image of its own.
uiA panel, card, button or other interface surface. Ships a PNG.
iconA small pictogram. Ships a PNG, same handling as ui.
textProgram text. No PNG — rebuild it as editable text.

Text properties

FieldTypeDescription
textstringThe characters read from the screenshot, in the original language.
fontSizePctnumberGlyph height as a fraction of imageSize.height. Multiply by your working height for the pixel font size.
color"#RRGGBB"Glyph fill colour.
fontWeight100–900Numeric font weight.
italicbooleanWhether the text is slanted.
align"LEFT" | "CENTER" | "RIGHT"Horizontal alignment inside the box.
fontFamilystringSuggested family; fall back to your own default when it is unavailable.
strokeColor"#RRGGBB"Glyph outline colour, when the text has one.
strokeWidthPctnumberOutline width as a fraction of imageSize.height.
shadow{ color, dxPct, dyPct, blurPct }Drop shadow: colour, plus offsets and blur as fractions of imageSize width and height.

Layer list (excerpt)

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 …
  ]
}

Shape

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

Using the layers

Positions and sizes are fractions, so the same list works at any pixel size.

  1. 1Pick the pixel size you work at — imageSize is the analysed size, and every box is a fraction of it.
  2. 2Place Lbg at the bottom, covering the full area.
  3. 3Order the rest: group by parentId, then sort by paintOrder ascending (back to front).
  4. 4Place each ui and icon PNG at its box, repeating at every entry of instances; for text layers use the characters and styling from text.
Lbg can be delivered larger than imageSize — scale it rather than assuming the two match.
Text ships as characters plus styling, not as an image, so it stays editable, translatable and sharp at any size.

Building a placement list

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

Billing

Resolution tier

One flat price per call, chosen by the long edge of the source image. The amount is returned as estimatedCredits when you submit and charged at completion; a failed task is refunded in full.

TierLong edgeCredits
1K≤ 1024 px120
2K≤ 2048 px180
4K> 2048 px250
Tier prices are configurable, so treat estimatedCredits from the submit response as the authoritative amount for that call.

Limits

ValueDescription
2048 pxSources are downscaled to a 2048 px long edge before analysis.
300At most 300 elements are detected per image.
20 MBInline base64 media is capped at 20 MB per item.
2–3 minTypical end-to-end runtime.
7 daysRetention of the task record and its files.
~1 hourValidity of a signed download URL.

Errors

Submission errors come back synchronously; execution errors surface as a failed task with an error object.

StatusCodeMeaning
400—Malformed request — most often no source image was supplied in messages[] or referenceImage.
401INVALID_API_KEY · INVALID_ORG_API_KEYMissing or invalid API key.
402INSUFFICIENT_CREDITS · INSUFFICIENT_ORG_CREDITSNot enough credits for the resolution tier of this image.
403API_SERVICE_NOT_ALLOWED · ORG_DISABLEDThe key or the organisation is not allowed to call this service.
413—An inline base64 image exceeds the 20 MB limit — pass an https URL instead.
429RATE_LIMIT_MINUTE · RATE_LIMIT_DAY · CONCURRENCY_LIMIT_EXCEEDEDRate or concurrency limit reached; retry after a short back-off.
failederror.codeExecution failed after the task started. error.code and error.message explain why, and the reserved credits are refunded in full.

Error response — 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"
}

Failed task (polled)

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