VberAI 开发者 API
VberAI 提供 RESTful HTTP API,把 AI 超强抠图等能力嵌入到你的应用、游戏与自动化流程。使用 API Key + 签名鉴权,统一错误码,按积分按次计费。
VberAI 提供 RESTful HTTP API,把 AI 超强抠图等能力嵌入到你的应用、游戏与自动化流程。使用 API Key + 签名鉴权,统一错误码,按积分按次计费。
通过 HTTP 直接调用 VberAI 的 AI 能力——生成图片、去除背景、运行各类 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
}
}