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.
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.
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.
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.
| Aktion | Persönlicher Schlüssel | Enterprise-Schlüssel |
|---|---|---|
| Einreichen | POST /ai/tasks | POST /ai/org-services/ai-layer-split/execute-async |
| Task-Status abfragen | GET /ai/tasks/{taskId} | GET /ai/org-services/tasks/{taskId} |
| Neue Download-URLs neu signieren | GET /ai/tasks/{taskId}/outputs | GET /ai/org-services/tasks/{taskId}/outputs |
Enterprise-Schlüssel müssen die Route /ai/org-services abfragen
Die Serviceparameter sind für beide Schlüsselarten identisch; nur die Hülle darum unterscheidet sich.
| Feld | Persönlicher Schlüssel | Enterprise-Schlüssel |
|---|---|---|
| Die unten aufgeführten Serviceparameter. | serviceCode + inputs | input |
webhookUrl | optional | optional |
webhookSecret | optional | optional |
Persönlicher Schlüssel
| Parameter | Typ | Erforderlich | Beschreibung |
|---|---|---|---|
messages | array | eines von beiden | Konversationsarray 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. |
referenceImage | string | eines von beiden | Kurzform für das Quellbild: öffentliche https-URL oder eingebetteter data:-URI. Alternative zu messages[]. |
referenceWidth | number | Nein | Angegebene Breite der Quelle in Pixeln. Dient nur der Preisstufe beim Einreichen; die tatsächliche Größe wird aus dem Bild gemessen. |
referenceHeight | number | Nein | Angegebene Höhe der Quelle in Pixeln. Gleicher Zweck wie referenceWidth. |
imageConfig | object | Nein | Für künftige Generierungsoptionen reserviert und derzeit ohne Wirkung. |
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.
{
"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"
}'Antwort beim Einreichen — 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"
}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.
| Feld | Beschreibung |
|---|---|
taskId | Auftragskennung – für Abfrage, Ergebnisabruf und Zuordnung des Webhooks. |
serviceCode | Immer ai-layer-split. |
status | queued · processing · completed · failed · cancelled · timeout. |
progress | Grober Fortschritt, sofern das Backend ihn meldet; sonst null. |
provider | Ausführungskanal. Wird stets als external gemeldet. |
hasResult | true, sobald result gefüllt ist. |
error | Fehlergrund; null, solange der Auftrag fehlerfrei läuft. |
createdAt · startedAt · completedAt | Zeitpunkte von Erstellung, Ausführungsstart und Abschluss (ISO 8601, UTC). |
expiresAt | Wann Datensatz und Dateien gelöscht werden – sieben Tage nach Abschluss. |
creditsEstimated · creditsActual | Beim Einreichen reservierte und beim Abschluss tatsächlich berechnete Credits. Bei Erfolg identisch; ein Fehlschlag wird vollständig erstattet. |
outputCount | Anzahl der gelieferten Dateien. |
result | Das unten beschriebene Ergebnisobjekt; erscheint nach Abschluss. |
Der Outputs-Endpunkt liefert dasselbe result-Objekt mit frisch signierten Download-URLs – einfach erneut aufrufen, sobald eine URL abgelaufen ist.
{
"success": true,
"data": {
"taskId": "6a9db1431ef5f254006213e0",
"status": "completed",
"result": { "type": "images", "assets": [ … ], "text": "{ … }" },
"completedAt": "2026-09-06T18:32:26.326Z"
}
}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
{
"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
{
"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
/ai/tasks/{taskId}curl https://api.vberai.com/api/ai/tasks/{taskId} \
-H "X-API-Key: vber_sk_YOUR_KEY"Ergebnisse abrufen
/ai/tasks/{taskId}/outputscurl https://api.vberai.com/api/ai/tasks/{taskId}/outputs \
-H "X-API-Key: vber_sk_YOUR_KEY"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.
| Feld | Typ | Beschreibung |
|---|---|---|
index | number | Position im assets-Array. |
name | string | Ebenen-id. Sie stimmt mit der id des zugehörigen Knotens im Baum überein – so gehören Bild und Geometrie zusammen. |
url | string | Signierter Download-Link. Unverändert verwenden, den Query-String nicht entfernen. |
mimeType | "image/png" | Immer image/png mit Alphakanal. |
size | number | Dateigröße in Bytes. |
sha256 | string | SHA-256 der Datei, für Integritätsprüfung und Deduplizierung. |
s3Key | string | Interner Objektschlüssel. Nur zur Information. |
Die ids vergibt der Server; innerhalb eines Auftrags sind sie stabil. Das Präfix sagt, worum es sich handelt.
| Wert | Bedeutung |
|---|---|
Lbg | Das 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. |
| group | Gruppeneinträge. Ohne PNG; sie sagen nur, welche Ebenen zusammengehören. |
Abgeschlossener Auftrag
{
"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 ist ein JSON-String – parsen Sie ihn. Er listet jede Ebene mit Name, Art, Position, Größe, Gruppierung und Stapelreihenfolge.
| Feld | Typ | Beschreibung |
|---|---|---|
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. |
nodes | LayerNode[] | Alle Ebenen in einem flachen Array. Die Gruppierung kommt aus parentId, die Stapelung aus paintOrder; die Reihenfolge im Array bedeutet nichts. |
| Feld | Typ | Beschreibung |
|---|---|---|
id | string | Ebenen-id, identisch mit dem passenden assets[].name (Lbg, A001, T001 …). Damit ordnen Sie einer Ebene ihr PNG zu. |
name | string | Von der KI abgeleiteter, lesbarer Name, z. B. join_room_card. Beschreibend, aber nicht garantiert eindeutig – als Schlüssel id, zur Anzeige name. |
kind | string | Ebenenart; 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. |
parentId | string | null | id der umgebenden Gruppe oder null auf oberster Ebene. |
paintOrder | number | Stapelreihenfolge unter Ebenen mit demselben Elternteil, aufsteigend von hinten nach vorn. Der Hintergrund ist -1. |
occluded | boolean | true, 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. |
text | object | Textstil; nur vorhanden, wenn kind gleich text ist. |
| Wert | Bedeutung |
|---|---|
background | Der aufgefüllte Hintergrund. Genau einer, zuerst gezeichnet. |
group | Container zur Verschachtelung. Ohne eigenes Bild. |
ui | Panel, Karte, Schaltfläche oder andere Oberfläche. Mit PNG. |
icon | Kleines Piktogramm. Mit PNG, Behandlung wie ui. |
text | Programmtext. Kein PNG – als bearbeitbaren Text nachbauen. |
| Feld | Typ | Beschreibung |
|---|---|---|
text | string | Die aus dem Screenshot gelesenen Zeichen in der Originalsprache. |
fontSizePct | number | Glyphenhöhe als Anteil von imageSize.height. Mit Ihrer Arbeitshöhe multiplizieren ergibt die Schriftgröße in Pixeln. |
color | "#RRGGBB" | Füllfarbe der Glyphen. |
fontWeight | 100–900 | Numerische Schriftstärke. |
italic | boolean | Ob der Text kursiv ist. |
align | "LEFT" | "CENTER" | "RIGHT" | Horizontale Ausrichtung innerhalb der Box. |
fontFamily | string | Vorgeschlagene Schriftfamilie; greifen Sie auf Ihre Standardschrift zurück, wenn sie fehlt. |
strokeColor | "#RRGGBB" | Konturfarbe der Glyphen, sofern der Text eine Kontur hat. |
strokeWidthPct | number | Konturstä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)
{
"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
// 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 }
}
}
]
}Positionen und Größen sind Anteile, dieselbe Liste passt also zu jeder Pixelgröße.
Platzierungsliste erzeugen
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
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.
| Stufe | Lange Kante | Credits |
|---|---|---|
1K | ≤ 1024 px | 120 |
2K | ≤ 2048 px | 180 |
4K | > 2048 px | 250 |
| Wert | Beschreibung |
|---|---|
2048 px | Quellen werden vor der Analyse auf 2048 px lange Kante verkleinert. |
300 | Höchstens 300 Elemente je Bild werden erkannt. |
20 MB | Eingebettete base64-Medien sind auf 20 MB je Element begrenzt. |
| 2–3 Min. | Typische Gesamtlaufzeit. |
| 7 Tage | Aufbewahrung von Datensatz und Dateien. |
| ~1 Stunde | Gültigkeit einer signierten Download-URL. |
Fehler beim Einreichen kommen synchron zurück; Ausführungsfehler zeigen sich als Auftrag im Status failed mit einem error-Objekt.
| Status | Code | Bedeutung |
|---|---|---|
| 400 | — | Fehlerhafter Request – meist wurde weder in messages[] noch in referenceImage ein Quellbild übergeben. |
| 401 | INVALID_API_KEY · INVALID_ORG_API_KEY | API-Schlüssel fehlt oder ist ungültig. |
| 402 | INSUFFICIENT_CREDITS · INSUFFICIENT_ORG_CREDITS | Nicht genügend Credits für die Auflösungsstufe dieses Bildes. |
| 403 | API_SERVICE_NOT_ALLOWED · ORG_DISABLED | Der 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. |
| 429 | RATE_LIMIT_MINUTE · RATE_LIMIT_DAY · CONCURRENCY_LIMIT_EXCEEDED | Raten- oder Parallelitätsgrenze erreicht; nach kurzer Wartezeit erneut versuchen. |
| failed | error.code | Die 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
{
"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)
{
"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
}
}