API для разработчиков VberAI
VberAI предоставляет REST HTTP API, чтобы встраивать AI-возможности (сегодня — AI Super Matting) в приложения, игры и пайплайны. Аутентификация по ключу + подписи, единые коды ошибок, оплата по кредитам.
VberAI предоставляет REST HTTP API, чтобы встраивать AI-возможности (сегодня — AI Super Matting) в приложения, игры и пайплайны. Аутентификация по ключу + подписи, единые коды ошибок, оплата по кредитам.
Генерируйте изображения, удаляйте фон и запускайте AI-конвейеры VberAI прямо по HTTP — с личными или корпоративными API-ключами.
На входе плоский скриншот интерфейса, на выходе редактируемые слои: фоновый 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
Параметры сервиса одинаковы для обоих типов ключей; различается только обёртка вокруг них.
| Поле | Личный ключ | Корпоративный ключ |
|---|---|---|
| Параметры сервиса, перечисленные ниже. | serviceCode + inputs | input |
webhookUrl | необязательно | необязательно |
webhookSecret | необязательно | необязательно |
Личный ключ
| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
messages | array | одно из двух | Массив сообщений с исходным изображением: в content[] должна быть часть { "type": "image_url", "image_url": { "url": "…" } }. URL может быть публичной https-ссылкой или встроенным data:-URI. |
referenceImage | string | одно из двух | Краткая форма передачи исходного изображения: публичный https-URL или встроенный data:-URI. Используется вместо messages[]. |
referenceWidth | number | Нет | Заявленная ширина исходника в пикселях. Нужна только для выбора тарифного уровня при отправке; фактический размер измеряется по самому изображению. |
referenceHeight | number | Нет | Заявленная высота исходника в пикселях. Назначение то же, что у referenceWidth. |
imageConfig | object | Нет | Зарезервировано под будущие параметры генерации. Сейчас игнорируется. |
Вместо собственного хостинга скриншот можно вложить прямо в запрос в виде data:-URI. Платформа сохранит его на своей стороне и передаст полученную ссылку в конвейер — остальное не меняется.
{
"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. Запись задачи и файлы доступны семь дней.
Задача проходит через эти значения. Прекратите опрос, как только достигнете терминального статуса: completed, failed, cancelled или timeout.
| Поле | Описание |
|---|---|
taskId | Идентификатор задачи: используется для опроса, получения файлов и сопоставления webhook. |
serviceCode | Всегда ai-layer-split. |
status | queued · processing · completed · failed · cancelled · timeout. |
progress | Приблизительный прогресс, если бэкенд его сообщает; иначе null. |
provider | Канал выполнения. Всегда сообщается как external. |
hasResult | true, как только result заполнен. |
error | Причина сбоя; null, пока задача идёт нормально. |
createdAt · startedAt · completedAt | Время создания, начала выполнения и завершения (ISO 8601, UTC). |
expiresAt | Когда запись и файлы удаляются — через семь дней после завершения. |
creditsEstimated · creditsActual | Кредиты, зарезервированные при отправке, и фактически списанные при завершении. При успехе совпадают, при сбое возвращаются полностью. |
outputCount | Количество возвращённых файлов. |
result | Объект результата, описанный ниже; появляется после завершения задачи. |
Эндпоинт выдачи возвращает тот же объект result со свежими подписанными ссылками — вызовите его снова, когда ссылка истечёт.
{
"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 — HMAC-SHA256 сырого JSON-payload в шестнадцатеричном представлении. Пересчитайте его с вашим секретом и сравните, прежде чем доверять payload. Доставки также несут 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[] и список слоёв в виде JSON-строки в text. Значение assets[].name однозначно совпадает с id своего слоя.
| Поле | Тип | Описание |
|---|---|---|
index | number | Позиция в массиве assets. |
name | string | Id слоя. Совпадает с id соответствующего узла в дереве — именно так изображение связывается с геометрией. |
url | string | Подписанная ссылка для скачивания. Используйте как есть, не удаляя строку запроса. |
mimeType | "image/png" | Всегда image/png с альфа-каналом. |
size | number | Размер файла в байтах. |
sha256 | string | SHA-256 файла — для проверки целостности и дедупликации. |
s3Key | string | Внутренний ключ объекта. Только для справки. |
Id назначает сервер, внутри одной задачи они неизменны. Префикс говорит, что это за слой.
| Значение | Значение |
|---|---|
Lbg | Фоновый PNG: всё изображение без найденных элементов, пустоты дорисованы. Один на задачу, самый нижний слой. Может прийти больше imageSize — масштабируйте под размер, в котором работаете. |
A001, A002, … | По одному PNG на графический элемент, пронумерованы в порядке списка. Прозрачный фон, части, скрытые за другими элементами, дополнены. Размер в пикселях равен box × imageSize. |
T001, T002, … | Текстовые элементы. Изображения намеренно нет: вы получаете точные символы и их оформление, чтобы воссоздать настоящий текст. |
| group | Записи групп. Без PNG; они лишь показывают, какие слои относятся к одной группе. |
Завершённая задача
{
"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 | Понятное имя, выведенное ИИ, например 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 px по длинной стороне. |
300 | Определяется не более 300 элементов на изображение. |
20 MB | Встроенные base64-медиа ограничены 20 МБ на элемент. |
| 2–3 мин | Типичное время выполнения целиком. |
| 7 дней | Срок хранения записи задачи и файлов. |
| ~1 час | Срок действия подписанной ссылки на скачивание. |
Ошибки отправки возвращаются синхронно; ошибки выполнения проявляются как задача в статусе failed с объектом error.
| Статус | Код | Значение |
|---|---|---|
| 400 | — | Некорректный запрос — чаще всего исходное изображение не передано ни в messages[], ни в referenceImage. |
| 401 | INVALID_API_KEY · INVALID_ORG_API_KEY | API-ключ отсутствует или недействителен. |
| 402 | INSUFFICIENT_CREDITS · INSUFFICIENT_ORG_CREDITS | Недостаточно кредитов для уровня разрешения этого изображения. |
| 403 | API_SERVICE_NOT_ALLOWED · ORG_DISABLED | Ключу или организации не разрешено вызывать этот сервис. |
| 413 | — | Встроенное base64-изображение превышает лимит 20 МБ — передайте его по 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
}
}