API для разработчиков VberAI

VberAI предоставляет REST HTTP API, чтобы встраивать AI-возможности (сегодня — AI Super Matting) в приложения, игры и пайплайны. Аутентификация по ключу + подписи, единые коды ошибок, оплата по кредитам.

API v1
Стабильная версия

Документация API

Генерируйте изображения, удаляйте фон и запускайте AI-конвейеры VberAI прямо по HTTP — с личными или корпоративными API-ключами.

ИИ-разбор на слои

На входе плоский скриншот интерфейса, на выходе редактируемые слои: фоновый PNG, по прозрачному PNG на каждый элемент и JSON-список с именем, типом, положением, размером и порядком наложения каждого слоя.

Разбирает одно статичное изображение на редактируемые многослойные элементы сцены, сохраняя текст редактируемым. Предназначен для автоматического разбора UI-сцен и восстановления макетов.

Как это работает

  1. 1Отправьте плоский скриншот и сразу получите taskId — задача выполняется асинхронно и обычно занимает две-три минуты.
  2. 2Опрашивайте задачу или дождитесь вызова webhook по завершении.
  3. 3Скачайте PNG по подписанным ссылкам и прочитайте список слоёв из result.text.

Эндпоинты

ДействиеЛичный ключКорпоративный ключ
ОтправкаPOST /ai/tasksPOST /ai/org-services/ai-layer-split/execute-async
Опросить статус задачиGET /ai/tasks/{taskId}GET /ai/org-services/tasks/{taskId}
Заново подписать свежие URL для скачиванияGET /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}. Отмена и статус пакета доступны только для личных ключей.

Обёртка запроса

Параметры сервиса одинаковы для обоих типов ключей; различается только обёртка вокруг них.

ПолеЛичный ключКорпоративный ключ
Параметры сервиса, перечисленные ниже.serviceCode + inputsinput
webhookUrlнеобязательнонеобязательно
webhookSecretнеобязательнонеобязательно

Личный ключ

Оба типа ключей могут просто опрашивать задачу: не указывайте webhookUrl и проверяйте статус сами либо задайте его, чтобы получить вызов по завершении. Если указан, это должен быть публичный https-URL.

Параметры сервиса

ПараметрТипОбязательныйОписание
messagesarrayодно из двухМассив сообщений с исходным изображением: в content[] должна быть часть { "type": "image_url", "image_url": { "url": "…" } }. URL может быть публичной https-ссылкой или встроенным data:-URI.
referenceImagestringодно из двухКраткая форма передачи исходного изображения: публичный https-URL или встроенный data:-URI. Используется вместо messages[].
referenceWidthnumberНетЗаявленная ширина исходника в пикселях. Нужна только для выбора тарифного уровня при отправке; фактический размер измеряется по самому изображению.
referenceHeightnumberНетЗаявленная высота исходника в пикселях. Назначение то же, что у referenceWidth.
imageConfigobjectНетЗарезервировано под будущие параметры генерации. Сейчас игнорируется.
Исходное изображение передаётся либо через messages[] (части контента в стиле OpenAI), либо через referenceImage — нужно одно из двух.

Встроенные base64-изображения

Вместо собственного хостинга скриншот можно вложить прямо в запрос в виде data:-URI. Платформа сохранит его на своей стороне и передаст полученную ссылку в конвейер — остальное не меняется.

json
{
  "referenceImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "referenceWidth": 1295,
  "referenceHeight": 726
}
Встроенные медиа ограничены 20 МБ на элемент (размер после декодирования, а не длина 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. Запись задачи и файлы доступны семь дней.

Задача проходит через эти значения. Прекратите опрос, как только достигнете терминального статуса: completed, failed, cancelled или timeout.

queuedprocessingcompletedfailedcancelledtimeout

Поля задачи

ПолеОписание
taskIdИдентификатор задачи: используется для опроса, получения файлов и сопоставления webhook.
serviceCodeВсегда ai-layer-split.
statusqueued · processing · completed · failed · cancelled · timeout.
progressПриблизительный прогресс, если бэкенд его сообщает; иначе null.
providerКанал выполнения. Всегда сообщается как external.
hasResulttrue, как только result заполнен.
errorПричина сбоя; null, пока задача идёт нормально.
createdAt · startedAt · completedAtВремя создания, начала выполнения и завершения (ISO 8601, UTC).
expiresAtКогда запись и файлы удаляются — через семь дней после завершения.
creditsEstimated · creditsActualКредиты, зарезервированные при отправке, и фактически списанные при завершении. При успехе совпадают, при сбое возвращаются полностью.
outputCountКоличество возвращённых файлов.
resultОбъект результата, описанный ниже; появляется после завершения задачи.

Получение результата

Эндпоинт выдачи возвращает тот же объект result со свежими подписанными ссылками — вызовите его снова, когда ссылка истечёт.

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 — HMAC-SHA256 сырого JSON-payload в шестнадцатеричном представлении. Пересчитайте его с вашим секретом и сравните, прежде чем доверять payload. Доставки также несут 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

В result две части: изображения слоёв в assets[] и список слоёв в виде JSON-строки в text. Значение assets[].name однозначно совпадает с id своего слоя.

Файлы результата

ПолеТипОписание
indexnumberПозиция в массиве assets.
namestringId слоя. Совпадает с id соответствующего узла в дереве — именно так изображение связывается с геометрией.
urlstringПодписанная ссылка для скачивания. Используйте как есть, не удаляя строку запроса.
mimeType"image/png"Всегда image/png с альфа-каналом.
sizenumberРазмер файла в байтах.
sha256stringSHA-256 файла — для проверки целостности и дедупликации.
s3KeystringВнутренний ключ объекта. Только для справки.
Ссылки для скачивания живут недолго (около часа). Чтобы получить новые, снова вызовите эндпоинт выдачи; сами файлы хранятся семь дней.

Именование слоёв

Id назначает сервер, внутри одной задачи они неизменны. Префикс говорит, что это за слой.

ЗначениеЗначение
LbgФоновый PNG: всё изображение без найденных элементов, пустоты дорисованы. Один на задачу, самый нижний слой. Может прийти больше imageSize — масштабируйте под размер, в котором работаете.
A001, A002, …По одному PNG на графический элемент, пронумерованы в порядке списка. Прозрачный фон, части, скрытые за другими элементами, дополнены. Размер в пикселях равен box × imageSize.
T001, T002, …Текстовые элементы. Изображения намеренно нет: вы получаете точные символы и их оформление, чтобы воссоздать настоящий текст.
groupЗаписи групп. Без PNG; они лишь показывают, какие слои относятся к одной группе.

Завершённая задача

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; порядок самого массива значения не имеет.

Запись слоя

ПолеТипОписание
idstringId слоя, совпадающий с соответствующим assets[].name (Lbg, A001, T001…). По нему слой связывается со своим PNG.
namestringПонятное имя, выведенное ИИ, например join_room_card. Описательное, но не обязательно уникальное: ключ — id, для показа — name.
kindstringТип слоя; см. таблицу ниже.
box[x, y, w, h]Положение и размер в виде [x, y, ширина, высота] в долях imageSize, начало координат в левом верхнем углу. Умножьте на imageSize, чтобы получить пиксели.
parentIdstring | nullId содержащей группы или null на корневом уровне.
paintOrdernumberПорядок наложения среди слоёв с одним родителем, по возрастанию от дальнего к ближнему. У фона -1.
occludedbooleantrue, если часть элемента была скрыта за другим и её пришлось восстанавливать.
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Разместите каждый PNG ui и icon в его 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 px по длинной стороне.
300Определяется не более 300 элементов на изображение.
20 MBВстроенные base64-медиа ограничены 20 МБ на элемент.
2–3 минТипичное время выполнения целиком.
7 днейСрок хранения записи задачи и файлов.
~1 часСрок действия подписанной ссылки на скачивание.

Ошибки

Ошибки отправки возвращаются синхронно; ошибки выполнения проявляются как задача в статусе failed с объектом error.

СтатусКодЗначение
400—Некорректный запрос — чаще всего исходное изображение не передано ни в messages[], ни в referenceImage.
401INVALID_API_KEY · INVALID_ORG_API_KEYAPI-ключ отсутствует или недействителен.
402INSUFFICIENT_CREDITS · INSUFFICIENT_ORG_CREDITSНедостаточно кредитов для уровня разрешения этого изображения.
403API_SERVICE_NOT_ALLOWED · ORG_DISABLEDКлючу или организации не разрешено вызывать этот сервис.
413—Встроенное base64-изображение превышает лимит 20 МБ — передайте его по 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
  }
}