API para desarrolladores de VberAI

VberAI ofrece una API REST HTTP para integrar sus capacidades de IA (hoy AI Super Matting) en tus apps, juegos y pipelines. Autenticación con clave API y firma, códigos de error estandarizados, facturación por crédito.

API v1
Estable

Documentación API

Genera imágenes, elimina fondos y ejecuta las canalizaciones de IA de VberAI directamente sobre HTTP, con claves de API personales o de empresa.

Separación de capas con IA

Entra una imagen de interfaz plana y salen capas editables: un PNG de fondo, un PNG transparente por elemento y una lista JSON con el nombre, tipo, posición, tamaño y orden de apilado de cada capa.

Divide una imagen estática en elementos de escena multicapa editables, manteniendo el texto editable. Pensado para dividir escenas de interfaz automáticamente y reconstruir diseños.

Cómo funciona

  1. 1Envía la captura plana y recibes un taskId al instante: el trabajo es asíncrono y suele tardar entre dos y tres minutos.
  2. 2Consulta el estado de la tarea o deja que el webhook te avise al terminar.
  3. 3Descarga los PNG desde las URL firmadas y lee result.text para obtener la lista de capas.

Endpoints

AcciónClave personalClave de empresa
EnviarPOST /ai/tasksPOST /ai/org-services/ai-layer-split/execute-async
Sondear el estado de la tareaGET /ai/tasks/{taskId}GET /ai/org-services/tasks/{taskId}
Volver a firmar URLs de descarga nuevasGET /ai/tasks/{taskId}/outputsGET /ai/org-services/tasks/{taskId}/outputs

Las claves de empresa deben sondear la ruta /ai/org-services

Una clave de empresa (vber_org_sk_) enviada a una ruta personal /ai/tasks devuelve 401 INVALID_API_KEY: las rutas personales solo aceptan claves personales. Sondea siempre los trabajos de empresa en /ai/org-services/tasks/{taskId}. cancel y batch-status son exclusivos de las claves personales.

Envoltorio de la petición

Los parámetros del servicio son idénticos para ambos tipos de clave; solo cambia el envoltorio que los rodea.

CampoClave personalClave de empresa
Los parámetros del servicio que se listan abajo.serviceCode + inputsinput
webhookUrlopcionalopcional
webhookSecretopcionalopcional

Clave personal

Ambos tipos de clave pueden limitarse a consultar: omite webhookUrl y comprueba la tarea tú mismo, o indícalo para recibir la llamada al terminar. Si lo indicas, debe ser una URL https pública.

Parámetros del servicio

ParámetroTipoObligatorioDescripción
messagesarrayuno de los dosArray de conversación que transporta la imagen de origen: content[] debe incluir una parte { "type": "image_url", "image_url": { "url": "…" } }. La URL puede ser un enlace https público o un data: URI en línea.
referenceImagestringuno de los dosForma abreviada de indicar la imagen de origen: una URL https pública o un data: URI en línea. Úsala en lugar de messages[].
referenceWidthnumberNoAncho declarado del original en píxeles. Solo sirve para elegir el tramo de precio al enviar; el tamaño real se mide de la propia imagen.
referenceHeightnumberNoAlto declarado del original en píxeles. Mismo propósito que referenceWidth.
imageConfigobjectNoReservado para futuras opciones de generación. Hoy se ignora.
Proporciona la imagen de origen mediante messages[] (partes de contenido al estilo OpenAI) o mediante referenceImage: uno de los dos es obligatorio.

Imágenes base64 en línea

En lugar de alojar la captura por tu cuenta, puedes incrustarla directamente en la petición como data: URI. La plataforma la almacena en el servidor y entrega la URL resultante al proceso, sin ningún otro cambio.

json
{
  "referenceImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "referenceWidth": 1295,
  "referenceHeight": 726
}
El contenido en línea está limitado a 20 MB por elemento (el tamaño decodificado, no la longitud del texto base64). Los originales mayores deben enviarse como URL 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"
}'

Respuesta al enviar — 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"
}

Consultar la tarea

Consulta hasta que status sea completed o failed. El registro de la tarea y sus archivos se conservan siete días.

Una tarea pasa por estos valores. Deja de sondear en cuanto alcances un status terminal: completed, failed, cancelled o timeout.

queuedprocessingcompletedfailedcancelledtimeout

Campos de la tarea

CampoDescripción
taskIdIdentificador de la tarea; se usa para consultar, obtener salidas y correlacionar el webhook.
serviceCodeSiempre ai-layer-split.
statusqueued · processing · completed · failed · cancelled · timeout.
progressProgreso aproximado cuando el backend lo informa; en caso contrario null.
providerCanal de ejecución. Siempre se informa como external.
hasResulttrue en cuanto result está disponible.
errorMotivo del fallo; null mientras la tarea va bien.
createdAt · startedAt · completedAtMomentos de creación, inicio de ejecución y finalización (ISO 8601, UTC).
expiresAtCuándo se eliminan el registro y los archivos: siete días después de completarse.
creditsEstimated · creditsActualCréditos reservados al enviar y realmente cobrados al completar. Coinciden si todo va bien; un fallo se reembolsa íntegramente.
outputCountNúmero de recursos devueltos.
resultEl objeto de resultado descrito más abajo; aparece cuando la tarea termina.

Obtener el resultado

El endpoint de salidas devuelve el mismo objeto result con URL de descarga recién firmadas: vuelve a llamarlo cuando una URL haya caducado.

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

Webhooks

Si defines webhookUrl, la plataforma envía por POST el mismo contenido que devolvería la consulta. Con webhookSecret recibes una cabecera de firma que puedes verificar.

Si defines un webhookSecret, cada entrega incluye una cabecera X-Webhook-Signature: un HMAC-SHA256 de la carga JSON en bruto, codificado en hexadecimal. Vuelve a calcularlo con tu secreto y compáralo antes de confiar en la carga. Las entregas también llevan un X-Idempotency-Key (taskId + status) para que puedas ignorar los duplicados.

Carga del 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 · tarea fallida

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

Consultar estado

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

Obtener salidas

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

El objeto result

result tiene dos partes: las imágenes de capa en assets[] y la lista de capas como cadena JSON en text. assets[].name coincide uno a uno con el id de su capa.

Recursos

CampoTipoDescripción
indexnumberPosición dentro del array assets.
namestringId de la capa. Coincide con el id del nodo correspondiente en el árbol: así se emparejan imagen y geometría.
urlstringEnlace de descarga firmado. Úsalo tal cual, sin quitar la cadena de consulta.
mimeType"image/png"Siempre image/png con canal alfa.
sizenumberTamaño del archivo en bytes.
sha256stringSHA-256 del archivo, útil para comprobar integridad y evitar duplicados.
s3KeystringClave interna del objeto. Solo informativa.
Las URL de descarga son efímeras (alrededor de una hora). Vuelve a llamar al endpoint de salidas para obtener nuevas; los archivos viven siete días.

Nomenclatura de capas

Los id los asigna el servidor y son estables dentro de una misma tarea. El prefijo indica qué es la capa.

ValorSignificado
LbgEl PNG de fondo: la imagen completa sin los elementos detectados y con los huecos repintados. Uno por tarea y es la capa más baja. Puede llegar más grande que imageSize: escálalo al tamaño con el que trabajes.
A001, A002, …Un PNG por elemento gráfico, numerado en el orden de la lista. Fondo transparente y con las partes ocultas por otros elementos ya rellenadas. Su tamaño en píxeles es box × imageSize.
T001, T002, …Elementos de texto. Sin PNG a propósito: recibes los caracteres exactos y su estilo para recrearlos como texto real.
groupEntradas de grupo. Sin PNG; solo indican qué capas van juntas.

Tarea completada

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

Lista de capas (result.text)

result.text es una cadena JSON: analízala. Enumera cada capa con su nombre, tipo, posición, tamaño, agrupación y orden de apilado.

Nivel superior

CampoTipoDescripción
imageSize{ width, height }Tamaño en píxeles de la imagen analizada. Cada box es una fracción de él: multiplica por este valor (o por el tamaño que prefieras) para obtener píxeles.
nodesLayerNode[]Todas las capas en un array plano. La agrupación viene de parentId y el apilado de paintOrder; el orden del array no significa nada.

Entrada de capa

CampoTipoDescripción
idstringId de la capa, idéntico al assets[].name correspondiente (Lbg, A001, T001…). Sirve para emparejar una capa con su PNG.
namestringNombre legible deducido por la IA, p. ej. join_room_card. Descriptivo pero no garantizado único: usa id como clave y name para mostrar.
kindstringTipo de capa; consulta la tabla siguiente.
box[x, y, w, h]Posición y tamaño como [x, y, ancho, alto], en fracciones de imageSize y con el origen arriba a la izquierda. Multiplica por imageSize para obtener píxeles.
parentIdstring | nullId del grupo contenedor, o null en el nivel raíz.
paintOrdernumberOrden de apilado entre capas con el mismo padre, ascendente de atrás hacia delante. El fondo es -1.
occludedbooleantrue cuando parte de este elemento estaba oculta tras otro y hubo que reconstruirla.
instances[x, y, w, h][]Posiciones adicionales del mismo elemento repetido. Coloca el mismo PNG en cada una de esas cajas en lugar de pedir más imágenes.
textobjectEstilo de texto; presente solo cuando kind es text.

Tipos de capa

ValorSignificado
backgroundEl fondo reconstruido. Solo uno y se dibuja primero.
groupContenedor usado para anidar. No tiene imagen propia.
uiPanel, tarjeta, botón u otra superficie de interfaz. Incluye PNG.
iconPictograma pequeño. Incluye PNG y se trata igual que ui.
textTexto de programa. Sin PNG: recréalo como texto editable.

Propiedades de texto

CampoTipoDescripción
textstringLos caracteres leídos de la captura, en su idioma original.
fontSizePctnumberAltura del glifo como fracción de imageSize.height. Multiplícala por la altura con la que trabajes para obtener el tamaño en píxeles.
color"#RRGGBB"Color de relleno del glifo.
fontWeight100–900Grosor numérico de la fuente.
italicbooleanSi el texto está inclinado.
align"LEFT" | "CENTER" | "RIGHT"Alineación horizontal dentro de la caja.
fontFamilystringFamilia sugerida; recurre a tu fuente por defecto si no está disponible.
strokeColor"#RRGGBB"Color del contorno del glifo, cuando el texto lo tiene.
strokeWidthPctnumberGrosor del contorno como fracción de imageSize.height.
shadow{ color, dxPct, dyPct, blurPct }Sombra: color, más desplazamientos y desenfoque como fracciones del ancho y alto de imageSize.

Lista de capas (extracto)

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

Estructura

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

Usar las capas

Las posiciones y tamaños son fracciones, así que la misma lista sirve a cualquier tamaño en píxeles.

  1. 1Elige el tamaño en píxeles con el que vas a trabajar: imageSize es el tamaño analizado y cada box es una fracción de él.
  2. 2Coloca Lbg abajo del todo, cubriendo toda el área.
  3. 3Ordena el resto: agrupa por parentId y ordena por paintOrder ascendente (de atrás hacia delante).
  4. 4Coloca cada PNG de ui e icon en su box, repitiendo en cada entrada de instances; para las capas de texto usa los caracteres y el estilo de text.
Lbg puede llegar más grande que imageSize: escálalo en vez de dar por hecho que coinciden.
El texto llega como caracteres y estilo, no como imagen, así sigue siendo editable, traducible y nítido a cualquier tamaño.

Crear una lista de colocación

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

Facturación

Tramo de resolución

Precio fijo por llamada, elegido según el lado largo de la imagen de origen. El importe se devuelve como estimatedCredits al enviar y se cobra al completar; una tarea fallida se reembolsa por completo.

TramoLado largoCréditos
1K≤ 1024 px120
2K≤ 2048 px180
4K> 2048 px250
Los precios por tramo son configurables, así que toma estimatedCredits de la respuesta de envío como importe definitivo de esa llamada.

Límites

ValorDescripción
2048 pxLos originales se reducen a 2048 px de lado largo antes del análisis.
300Se detectan como máximo 300 elementos por imagen.
20 MBEl contenido base64 en línea está limitado a 20 MB por elemento.
2–3 minDuración típica de principio a fin.
7 díasConservación del registro y los archivos.
~1 horaValidez de una URL de descarga firmada.

Errores

Los errores de envío se devuelven de forma síncrona; los de ejecución aparecen como tarea failed con un objeto error.

EstadoCódigoSignificado
400—Petición mal formada: lo más habitual es no haber aportado imagen de origen ni en messages[] ni en referenceImage.
401INVALID_API_KEY · INVALID_ORG_API_KEYFalta la clave de API o no es válida.
402INSUFFICIENT_CREDITS · INSUFFICIENT_ORG_CREDITSCréditos insuficientes para el tramo de resolución de esta imagen.
403API_SERVICE_NOT_ALLOWED · ORG_DISABLEDLa clave o la organización no tiene permiso para llamar a este servicio.
413—Una imagen base64 en línea supera el límite de 20 MB: envíala como URL https.
429RATE_LIMIT_MINUTE · RATE_LIMIT_DAY · CONCURRENCY_LIMIT_EXCEEDEDSe alcanzó el límite de frecuencia o de concurrencia; reintenta tras una breve espera.
failederror.codeLa ejecución falló después de iniciarse la tarea. error.code y error.message explican el motivo y los créditos reservados se reembolsan íntegramente.

Respuesta de error — 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"
}

Tarea fallida (consulta)

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