VberAI 开发者 API

VberAI 提供 RESTful HTTP API,把 AI 超强抠图等能力嵌入到你的应用、游戏与自动化流程。使用 API Key + 签名鉴权,统一错误码,按积分按次计费。

API v1
稳定版

API 文档

通过 HTTP 直接调用 VberAI 的 AI 能力——生成图片、去除背景、运行各类 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} 轮询。取消与批量状态查询仅个人密钥可用。

请求外层结构

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