VberAI Entwickler-API

VberAI bietet eine REST-HTTP-API, um KI-Funktionen (heute AI Super Matting) in Apps, Spiele und Pipelines einzubinden. Authentifizierung per API-Key + Signatur, einheitliche Fehlercodes, Abrechnung per Credit.

API v1
Stabil

API-Dokumentation

Erzeuge Bilder, entferne Hintergründe und führe die KI-Pipelines von VberAI direkt über HTTP aus – mit persönlichen oder Enterprise-API-Schlüsseln.

KI-Ebenentrennung

Ein flaches UI-Bild rein, bearbeitbare Ebenen raus: ein Hintergrund-PNG, je Element ein transparentes PNG und eine JSON-Liste mit Name, Art, Position, Größe und Stapelreihenfolge jeder Ebene.

Zerlegt ein statisches Bild in bearbeitbare, mehrschichtige Szenenelemente und hält den Text editierbar. Gedacht für die automatische Zerlegung von UI-Szenen und die Rekonstruktion von Designs.

Ablauf

  1. 1Screenshot senden und sofort eine taskId erhalten – der Auftrag läuft asynchron und dauert meist zwei bis drei Minuten.
  2. 2Den Auftrag abfragen oder den Webhook bei Fertigstellung anrufen lassen.
  3. 3Laden Sie die PNGs über die signierten URLs und lesen Sie die Ebenenliste aus result.text.

Endpunkte

AktionPersönlicher SchlüsselEnterprise-Schlüssel
EinreichenPOST /ai/tasksPOST /ai/org-services/ai-layer-split/execute-async
Task-Status abfragenGET /ai/tasks/{taskId}GET /ai/org-services/tasks/{taskId}
Neue Download-URLs neu signierenGET /ai/tasks/{taskId}/outputsGET /ai/org-services/tasks/{taskId}/outputs

Enterprise-Schlüssel müssen die Route /ai/org-services abfragen

Ein Enterprise-Schlüssel (vber_org_sk_), der an eine persönliche /ai/tasks-Route gesendet wird, gibt 401 INVALID_API_KEY zurück – die persönlichen Routen akzeptieren nur persönliche Schlüssel. Frage Enterprise-Aufträge immer unter /ai/org-services/tasks/{taskId} ab. cancel und batch-status sind nur mit persönlichen Schlüsseln verfügbar.

Request-Hülle

Die Serviceparameter sind für beide Schlüsselarten identisch; nur die Hülle darum unterscheidet sich.

FeldPersönlicher SchlüsselEnterprise-Schlüssel
Die unten aufgeführten Serviceparameter.serviceCode + inputsinput
webhookUrloptionaloptional
webhookSecretoptionaloptional

Persönlicher Schlüssel

Beide Schlüsselarten können einfach pollen: webhookUrl weglassen und selbst nachsehen, oder setzen, um bei Abschluss gerufen zu werden. Wenn gesetzt, muss es eine öffentliche https-URL sein.

Serviceparameter

ParameterTypErforderlichBeschreibung
messagesarrayeines von beidenKonversationsarray mit dem Quellbild: content[] muss einen Part { "type": "image_url", "image_url": { "url": "…" } } enthalten. Die URL darf ein öffentlicher https-Link oder ein eingebetteter data:-URI sein.
referenceImagestringeines von beidenKurzform für das Quellbild: öffentliche https-URL oder eingebetteter data:-URI. Alternative zu messages[].
referenceWidthnumberNeinAngegebene Breite der Quelle in Pixeln. Dient nur der Preisstufe beim Einreichen; die tatsächliche Größe wird aus dem Bild gemessen.
referenceHeightnumberNeinAngegebene Höhe der Quelle in Pixeln. Gleicher Zweck wie referenceWidth.
imageConfigobjectNeinFür künftige Generierungsoptionen reserviert und derzeit ohne Wirkung.
Übergeben Sie das Quellbild entweder über messages[] (Content-Parts im OpenAI-Stil) oder über referenceImage – eines von beiden ist Pflicht.

Eingebettete base64-Bilder

Statt den Screenshot selbst zu hosten, können Sie ihn als data:-URI direkt in den Request legen. Die Plattform speichert ihn serverseitig und übergibt die entstandene URL an die Pipeline – sonst ändert sich nichts.

json
{
  "referenceImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "referenceWidth": 1295,
  "referenceHeight": 726
}
Eingebettete Medien sind auf 20 MB je Element begrenzt (dekodierte Größe, nicht die Länge des base64-Texts). Größere Quellen bitte als https-URL übergeben.
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"
}'

Antwort beim Einreichen — 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"
}

Auftrag abfragen

So lange abfragen, bis status auf completed oder failed steht. Auftragsdatensatz und Dateien bleiben sieben Tage verfügbar.

Ein Task durchläuft diese Werte. Höre auf abzufragen, sobald du einen terminalen status erreichst: completed, failed, cancelled oder timeout.

queuedprocessingcompletedfailedcancelledtimeout

Auftragsfelder

FeldBeschreibung
taskIdAuftragskennung – für Abfrage, Ergebnisabruf und Zuordnung des Webhooks.
serviceCodeImmer ai-layer-split.
statusqueued · processing · completed · failed · cancelled · timeout.
progressGrober Fortschritt, sofern das Backend ihn meldet; sonst null.
providerAusführungskanal. Wird stets als external gemeldet.
hasResulttrue, sobald result gefüllt ist.
errorFehlergrund; null, solange der Auftrag fehlerfrei läuft.
createdAt · startedAt · completedAtZeitpunkte von Erstellung, Ausführungsstart und Abschluss (ISO 8601, UTC).
expiresAtWann Datensatz und Dateien gelöscht werden – sieben Tage nach Abschluss.
creditsEstimated · creditsActualBeim Einreichen reservierte und beim Abschluss tatsächlich berechnete Credits. Bei Erfolg identisch; ein Fehlschlag wird vollständig erstattet.
outputCountAnzahl der gelieferten Dateien.
resultDas unten beschriebene Ergebnisobjekt; erscheint nach Abschluss.

Ergebnis abholen

Der Outputs-Endpunkt liefert dasselbe result-Objekt mit frisch signierten Download-URLs – einfach erneut aufrufen, sobald eine URL abgelaufen ist.

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

Webhooks

Ist webhookUrl gesetzt, sendet die Plattform per POST genau das, was die Abfrage geliefert hätte. Mit webhookSecret erhalten Sie einen prüfbaren Signatur-Header.

Wenn du ein webhookSecret setzt, enthält jede Zustellung einen X-Webhook-Signature-Header – ein HMAC-SHA256 der rohen JSON-Nutzlast, hex-codiert. Berechne ihn mit deinem Secret neu und vergleiche, bevor du der Nutzlast vertraust. Zustellungen tragen außerdem einen X-Idempotency-Key (taskId + status), sodass du Duplikate ignorieren kannst.

Webhook-Payload

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 · fehlgeschlagen

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

Auftragsstatus abfragen

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

Ergebnisse abrufen

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

Das result-Objekt

result besteht aus zwei Teilen: den Ebenenbildern in assets[] und der Ebenenliste als JSON-String in text. assets[].name entspricht eins zu eins der id seiner Ebene.

Dateien

FeldTypBeschreibung
indexnumberPosition im assets-Array.
namestringEbenen-id. Sie stimmt mit der id des zugehörigen Knotens im Baum überein – so gehören Bild und Geometrie zusammen.
urlstringSignierter Download-Link. Unverändert verwenden, den Query-String nicht entfernen.
mimeType"image/png"Immer image/png mit Alphakanal.
sizenumberDateigröße in Bytes.
sha256stringSHA-256 der Datei, für Integritätsprüfung und Deduplizierung.
s3KeystringInterner Objektschlüssel. Nur zur Information.
Download-URLs sind kurzlebig (etwa eine Stunde). Rufen Sie den Outputs-Endpunkt erneut auf, um frische zu erhalten; die Dateien selbst bleiben sieben Tage bestehen.

Ebenenbenennung

Die ids vergibt der Server; innerhalb eines Auftrags sind sie stabil. Das Präfix sagt, worum es sich handelt.

WertBedeutung
LbgDas Hintergrund-PNG: das ganze Bild ohne die erkannten Elemente, die Lücken neu gemalt. Eines je Auftrag und die unterste Ebene. Es kann größer als imageSize kommen – skalieren Sie es auf Ihre Arbeitsgröße.
A001, A002, …Je Bildelement ein PNG, in Listenreihenfolge nummeriert. Transparenter Hintergrund, von anderen Elementen verdeckte Teile ergänzt. Die Pixelgröße ist box × imageSize.
T001, T002, …Textelemente. Bewusst ohne PNG: Sie erhalten die genauen Zeichen und ihr Format, um sie als echten Text nachzubauen.
groupGruppeneinträge. Ohne PNG; sie sagen nur, welche Ebenen zusammengehören.

Abgeschlossener Auftrag

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

Ebenenliste (result.text)

result.text ist ein JSON-String – parsen Sie ihn. Er listet jede Ebene mit Name, Art, Position, Größe, Gruppierung und Stapelreihenfolge.

Oberste Ebene

FeldTypBeschreibung
imageSize{ width, height }Pixelgröße des analysierten Bildes. Jede box ist ein Anteil davon – multiplizieren Sie damit (oder mit einer beliebigen Größe), um Pixel zu erhalten.
nodesLayerNode[]Alle Ebenen in einem flachen Array. Die Gruppierung kommt aus parentId, die Stapelung aus paintOrder; die Reihenfolge im Array bedeutet nichts.

Ebeneneintrag

FeldTypBeschreibung
idstringEbenen-id, identisch mit dem passenden assets[].name (Lbg, A001, T001 …). Damit ordnen Sie einer Ebene ihr PNG zu.
namestringVon der KI abgeleiteter, lesbarer Name, z. B. join_room_card. Beschreibend, aber nicht garantiert eindeutig – als Schlüssel id, zur Anzeige name.
kindstringEbenenart; siehe Tabelle unten.
box[x, y, w, h]Position und Größe als [x, y, Breite, Höhe] in Anteilen von imageSize, Ursprung oben links. Mit imageSize multiplizieren ergibt Pixel.
parentIdstring | nullid der umgebenden Gruppe oder null auf oberster Ebene.
paintOrdernumberStapelreihenfolge unter Ebenen mit demselben Elternteil, aufsteigend von hinten nach vorn. Der Hintergrund ist -1.
occludedbooleantrue, wenn ein Teil dieses Elements hinter einem anderen verborgen war und rekonstruiert werden musste.
instances[x, y, w, h][]Weitere Positionen desselben wiederholten Elements. Platzieren Sie dasselbe PNG an jeder dieser Boxen, statt weitere Bilder anzufordern.
textobjectTextstil; nur vorhanden, wenn kind gleich text ist.

Ebenenarten

WertBedeutung
backgroundDer aufgefüllte Hintergrund. Genau einer, zuerst gezeichnet.
groupContainer zur Verschachtelung. Ohne eigenes Bild.
uiPanel, Karte, Schaltfläche oder andere Oberfläche. Mit PNG.
iconKleines Piktogramm. Mit PNG, Behandlung wie ui.
textProgrammtext. Kein PNG – als bearbeitbaren Text nachbauen.

Texteigenschaften

FeldTypBeschreibung
textstringDie aus dem Screenshot gelesenen Zeichen in der Originalsprache.
fontSizePctnumberGlyphenhöhe als Anteil von imageSize.height. Mit Ihrer Arbeitshöhe multiplizieren ergibt die Schriftgröße in Pixeln.
color"#RRGGBB"Füllfarbe der Glyphen.
fontWeight100–900Numerische Schriftstärke.
italicbooleanOb der Text kursiv ist.
align"LEFT" | "CENTER" | "RIGHT"Horizontale Ausrichtung innerhalb der Box.
fontFamilystringVorgeschlagene Schriftfamilie; greifen Sie auf Ihre Standardschrift zurück, wenn sie fehlt.
strokeColor"#RRGGBB"Konturfarbe der Glyphen, sofern der Text eine Kontur hat.
strokeWidthPctnumberKonturstärke als Anteil von imageSize.height.
shadow{ color, dxPct, dyPct, blurPct }Schlagschatten: Farbe sowie Versatz und Weichzeichnung als Anteile von Breite und Höhe der imageSize.

Ebenenliste (Auszug)

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

Struktur

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

Ebenen verwenden

Positionen und Größen sind Anteile, dieselbe Liste passt also zu jeder Pixelgröße.

  1. 1Wählen Sie Ihre Arbeitsgröße in Pixeln – imageSize ist die analysierte Größe, und jede box ist ein Anteil davon.
  2. 2Legen Sie Lbg ganz nach unten, sodass es die gesamte Fläche abdeckt.
  3. 3Ordnen Sie den Rest: nach parentId gruppieren, dann nach paintOrder aufsteigend (hinten nach vorn) sortieren.
  4. 4Platzieren Sie jedes ui- und icon-PNG an seiner box und wiederholen Sie das an jedem Eintrag aus instances; für Textebenen nehmen Sie Zeichen und Format aus text.
Lbg kann größer als imageSize geliefert werden – skalieren Sie es, statt Übereinstimmung anzunehmen.
Text kommt als Zeichen plus Format statt als Bild und bleibt so bearbeitbar, übersetzbar und in jeder Größe scharf.

Platzierungsliste erzeugen

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

Abrechnung

Auflösungsstufe

Ein Festpreis pro Aufruf, bestimmt durch die lange Kante des Quellbilds. Der Betrag wird beim Einreichen als estimatedCredits zurückgegeben und beim Abschluss berechnet; ein fehlgeschlagener Auftrag wird vollständig erstattet.

StufeLange KanteCredits
1K≤ 1024 px120
2K≤ 2048 px180
4K> 2048 px250
Die Stufenpreise sind konfigurierbar – nehmen Sie estimatedCredits aus der Einreichungsantwort als verbindlichen Betrag für diesen Aufruf.

Grenzwerte

WertBeschreibung
2048 pxQuellen werden vor der Analyse auf 2048 px lange Kante verkleinert.
300Höchstens 300 Elemente je Bild werden erkannt.
20 MBEingebettete base64-Medien sind auf 20 MB je Element begrenzt.
2–3 Min.Typische Gesamtlaufzeit.
7 TageAufbewahrung von Datensatz und Dateien.
~1 StundeGültigkeit einer signierten Download-URL.

Fehler

Fehler beim Einreichen kommen synchron zurück; Ausführungsfehler zeigen sich als Auftrag im Status failed mit einem error-Objekt.

StatusCodeBedeutung
400—Fehlerhafter Request – meist wurde weder in messages[] noch in referenceImage ein Quellbild übergeben.
401INVALID_API_KEY · INVALID_ORG_API_KEYAPI-Schlüssel fehlt oder ist ungültig.
402INSUFFICIENT_CREDITS · INSUFFICIENT_ORG_CREDITSNicht genügend Credits für die Auflösungsstufe dieses Bildes.
403API_SERVICE_NOT_ALLOWED · ORG_DISABLEDDer Schlüssel oder die Organisation darf diesen Service nicht aufrufen.
413—Ein eingebettetes base64-Bild überschreitet die 20-MB-Grenze – übergeben Sie stattdessen eine https-URL.
429RATE_LIMIT_MINUTE · RATE_LIMIT_DAY · CONCURRENCY_LIMIT_EXCEEDEDRaten- oder Parallelitätsgrenze erreicht; nach kurzer Wartezeit erneut versuchen.
failederror.codeDie Ausführung ist nach dem Start fehlgeschlagen. error.code und error.message nennen den Grund, die reservierten Credits werden vollständig erstattet.

Fehlerantwort — 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"
}

Fehlgeschlagener Auftrag (Abfrage)

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