API développeur VberAI

VberAI propose une API REST HTTP pour intégrer ses capacités IA (aujourd'hui AI Super Matting) à vos apps, jeux et pipelines. Authentification par clé API + signature, codes d'erreur normalisés, facturation au crédit.

API v1
Stable

Documentation API

Générez des images, supprimez des arrière-plans et exécutez les pipelines d'IA de VberAI directement via HTTP, avec des clés d'API personnelles ou d'entreprise.

Découpage IA en calques

Une image d'interface aplatie en entrée, des calques modifiables en sortie : un PNG de fond, un PNG transparent par élément et une liste JSON donnant le nom, le type, la position, la taille et l'ordre d'empilement de chaque calque.

Découpe une image statique en éléments de scène multicalques modifiables, le texte restant éditable. Conçu pour le découpage automatique de scènes d’interface et la restitution de maquettes.

Fonctionnement

  1. 1Envoyez la capture aplatie et recevez immédiatement un taskId : le traitement est asynchrone et prend généralement deux à trois minutes.
  2. 2Interrogez la tâche, ou laissez le webhook vous prévenir à la fin.
  3. 3Téléchargez les PNG depuis les URL signées et lisez result.text pour obtenir la liste des calques.

Points d'accès

ActionClé personnelleClé d'entreprise
SoumettrePOST /ai/tasksPOST /ai/org-services/ai-layer-split/execute-async
Interroger le statut de la tâcheGET /ai/tasks/{taskId}GET /ai/org-services/tasks/{taskId}
Resigner de nouvelles URL de téléchargementGET /ai/tasks/{taskId}/outputsGET /ai/org-services/tasks/{taskId}/outputs

Les clés d'entreprise doivent interroger la route /ai/org-services

Une clé d'entreprise (vber_org_sk_) envoyée à une route personnelle /ai/tasks renvoie 401 INVALID_API_KEY — les routes personnelles n'acceptent que les clés personnelles. Interrogez toujours les tâches d'entreprise sur /ai/org-services/tasks/{taskId}. cancel et batch-status sont réservés aux clés personnelles.

Enveloppe de la requête

Les paramètres du service sont identiques pour les deux types de clé ; seule l'enveloppe qui les entoure diffère.

ChampClé personnelleClé d'entreprise
Les paramètres de service listés ci-dessous.serviceCode + inputsinput
webhookUrlfacultatiffacultatif
webhookSecretfacultatiffacultatif

Clé personnelle

Les deux types de clé peuvent se contenter d’interroger la tâche : omettez webhookUrl et vérifiez vous-même, ou indiquez-le pour être appelé à la fin. S’il est fourni, ce doit être une URL https publique.

Paramètres du service

ParamètreTypeObligatoireDescription
messagesarrayl'un des deuxTableau de conversation portant l'image source : content[] doit contenir une partie { "type": "image_url", "image_url": { "url": "…" } }. L'URL peut être un lien https public ou un data: URI en ligne.
referenceImagestringl'un des deuxForme abrégée pour l'image source : une URL https publique ou un data: URI en ligne. À utiliser à la place de messages[].
referenceWidthnumberNonLargeur déclarée de la source en pixels. Sert uniquement à choisir le palier tarifaire à la soumission ; la taille réelle est mesurée sur l'image.
referenceHeightnumberNonHauteur déclarée de la source en pixels. Même rôle que referenceWidth.
imageConfigobjectNonRéservé à de futures options de génération. Ignoré aujourd'hui.
Fournissez l'image source via messages[] (parties de contenu au format OpenAI) ou via referenceImage : l'un des deux est requis.

Images base64 en ligne

Plutôt que d'héberger la capture vous-même, intégrez-la directement dans la requête sous forme de data: URI. La plateforme la stocke côté serveur et transmet l'URL obtenue au pipeline : rien d'autre ne change.

json
{
  "referenceImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "referenceWidth": 1295,
  "referenceHeight": 726
}
Le média en ligne est limité à 20 Mo par élément (taille décodée, pas la longueur du texte base64). Au-delà, transmettez une 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"
}'

Réponse à la soumission — 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"
}

Interroger la tâche

Interrogez jusqu'à ce que status passe à completed ou failed. L'enregistrement et les fichiers restent disponibles sept jours.

Une tâche passe par ces valeurs. Arrêtez d'interroger dès que vous atteignez un status terminal : completed, failed, cancelled ou timeout.

queuedprocessingcompletedfailedcancelledtimeout

Champs de la tâche

ChampDescription
taskIdIdentifiant de la tâche, utilisé pour l'interrogation, les sorties et la corrélation du webhook.
serviceCodeToujours ai-layer-split.
statusqueued · processing · completed · failed · cancelled · timeout.
progressProgression approximative lorsque le backend la remonte ; null sinon.
providerCanal d'exécution. Toujours signalé comme external.
hasResulttrue dès que result est disponible.
errorMotif de l'échec ; null tant que la tâche se déroule bien.
createdAt · startedAt · completedAtDates de création, de démarrage et de fin (ISO 8601, UTC).
expiresAtDate de purge de l'enregistrement et des fichiers : sept jours après la fin.
creditsEstimated · creditsActualCrédits réservés à la soumission et réellement débités à la fin. Identiques en cas de succès ; un échec est intégralement remboursé.
outputCountNombre de fichiers renvoyés.
resultL'objet de résultat décrit ci-dessous ; présent une fois la tâche terminée.

Récupérer le résultat

Le point d'accès des sorties renvoie le même objet result avec des URL de téléchargement re-signées : rappelez-le dès qu'une URL a expiré.

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

Webhooks

Si webhookUrl est défini, la plateforme envoie en POST exactement ce que l'interrogation aurait renvoyé. Avec webhookSecret, vous recevez un en-tête de signature vérifiable.

Si vous définissez un webhookSecret, chaque livraison inclut un en-tête X-Webhook-Signature — un HMAC-SHA256 de la charge utile JSON brute, encodé en hexadécimal. Recalculez-le avec votre secret et comparez avant de faire confiance à la charge utile. Les livraisons portent aussi un X-Idempotency-Key (taskId + status) pour que vous puissiez ignorer les doublons.

Charge utile du 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 · tâche en échec

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

État de la tâche

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

Récupérer les sorties

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

L'objet result

result comporte deux parties : les images de calques dans assets[] et la liste des calques sous forme de chaîne JSON dans text. assets[].name correspond un à un à l'id de son calque.

Fichiers produits

ChampTypeDescription
indexnumberPosition dans le tableau assets.
namestringId du calque. Il est identique à l'id du nœud correspondant dans l'arbre : c'est ainsi qu'on associe une image à sa géométrie.
urlstringLien de téléchargement signé. Utilisez-le tel quel, sans retirer la chaîne de requête.
mimeType"image/png"Toujours image/png avec canal alpha.
sizenumberTaille du fichier en octets.
sha256stringSHA-256 du fichier, pour le contrôle d'intégrité et la déduplication.
s3KeystringClé d'objet interne. Purement informative.
Les URL de téléchargement sont éphémères (environ une heure). Rappelez le point d'accès des sorties pour en obtenir de nouvelles ; les fichiers, eux, vivent sept jours.

Nommage des calques

Les id sont attribués par le serveur et restent stables au sein d'une même tâche. Le préfixe indique la nature du calque.

ValeurSignification
LbgLe PNG de fond : l'image entière sans les éléments détectés, les vides étant repeints. Un seul par tâche, c'est le calque le plus bas. Il peut arriver plus grand que imageSize — mettez-le à l'échelle de votre taille de travail.
A001, A002, …Un PNG par élément graphique, numéroté dans l'ordre de la liste. Fond transparent, parties masquées par d'autres éléments déjà comblées. Sa taille en pixels vaut box × imageSize.
T001, T002, …Éléments de texte. Sans PNG volontairement : vous recevez les caractères exacts et leur style pour les recréer en texte réel.
groupEntrées de groupe. Pas de PNG ; elles indiquent seulement quels calques vont ensemble.

Tâche terminée

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

Liste des calques (result.text)

result.text est une chaîne JSON : analysez-la. Elle liste chaque calque avec son nom, son type, sa position, sa taille, son regroupement et son ordre d'empilement.

Niveau supérieur

ChampTypeDescription
imageSize{ width, height }Taille en pixels de l'image analysée. Chaque box en est une fraction : multipliez par cette taille (ou par celle de votre choix) pour obtenir des pixels.
nodesLayerNode[]Tous les calques dans un tableau à plat. Le regroupement vient de parentId, l'empilement de paintOrder ; l'ordre du tableau n'a aucune signification.

Entrée de calque

ChampTypeDescription
idstringId du calque, identique au assets[].name correspondant (Lbg, A001, T001…). Il sert à associer un calque à son PNG.
namestringNom lisible déduit par l'IA, par exemple join_room_card. Descriptif mais non garanti unique : utilisez id comme clé et name pour l'affichage.
kindstringType de calque ; voir le tableau ci-dessous.
box[x, y, w, h]Position et taille sous la forme [x, y, largeur, hauteur], en fractions de imageSize, origine en haut à gauche. Multipliez par imageSize pour des pixels.
parentIdstring | nullId du groupe contenant, ou null au niveau racine.
paintOrdernumberOrdre d'empilement entre calques de même parent, croissant de l'arrière vers l'avant. Le fond vaut -1.
occludedbooleantrue lorsqu'une partie de cet élément était masquée par un autre et a dû être reconstruite.
instances[x, y, w, h][]Positions supplémentaires du même élément répété. Placez le même PNG à chacune de ces boîtes plutôt que de demander d'autres images.
textobjectStyle de texte ; présent uniquement lorsque kind vaut text.

Types de calques

ValeurSignification
backgroundLe fond reconstitué. Un seul, dessiné en premier.
groupConteneur servant à l'imbrication. Sans image propre.
uiPanneau, carte, bouton ou autre surface d'interface. Livré avec un PNG.
iconPetit pictogramme. Livré avec un PNG, traité comme ui.
textTexte applicatif. Aucun PNG : à recréer en texte modifiable.

Propriétés de texte

ChampTypeDescription
textstringLes caractères lus sur la capture, dans leur langue d'origine.
fontSizePctnumberHauteur des glyphes en fraction de imageSize.height. Multipliez par votre hauteur de travail pour la taille en pixels.
color"#RRGGBB"Couleur de remplissage des glyphes.
fontWeight100–900Graisse numérique de la police.
italicbooleanIndique si le texte est incliné.
align"LEFT" | "CENTER" | "RIGHT"Alignement horizontal dans la boîte.
fontFamilystringFamille suggérée ; repliez-vous sur votre police par défaut si elle est indisponible.
strokeColor"#RRGGBB"Couleur du contour des glyphes, lorsque le texte en possède un.
strokeWidthPctnumberÉpaisseur du contour en fraction de imageSize.height.
shadow{ color, dxPct, dyPct, blurPct }Ombre portée : couleur, plus décalages et flou en fractions de la largeur et de la hauteur de imageSize.

Liste des calques (extrait)

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

Structure

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

Utiliser les calques

Positions et tailles sont des fractions : la même liste fonctionne à n'importe quelle taille en pixels.

  1. 1Choisissez la taille en pixels de travail — imageSize est la taille analysée et chaque box en est une fraction.
  2. 2Placez Lbg tout en bas, couvrant toute la zone.
  3. 3Ordonnez le reste : regroupez par parentId, puis triez par paintOrder croissant (de l'arrière vers l'avant).
  4. 4Placez chaque PNG ui et icon à sa boîte, en répétant à chaque entrée de instances ; pour les calques de texte, utilisez les caractères et le style de text.
Lbg peut être livré plus grand que imageSize — mettez-le à l'échelle au lieu de supposer qu'ils correspondent.
Le texte arrive sous forme de caractères et de style, pas d'image : il reste modifiable, traduisible et net à toute taille.

Construire une liste de placement

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

Facturation

Palier de résolution

Un tarif forfaitaire par appel, déterminé par le grand côté de l'image source. Le montant est renvoyé dans estimatedCredits à la soumission et débité à la fin ; une tâche en échec est intégralement remboursée.

PalierGrand côtéCrédits
1K≤ 1024 px120
2K≤ 2048 px180
4K> 2048 px250
Les tarifs par palier sont configurables : considérez estimatedCredits de la réponse de soumission comme le montant faisant foi pour cet appel.

Limites

ValeurDescription
2048 pxLes sources sont réduites à 2048 px de grand côté avant analyse.
300300 éléments détectés au maximum par image.
20 MBLe média base64 en ligne est limité à 20 Mo par élément.
2–3 minDurée typique de bout en bout.
7 joursConservation de l'enregistrement et des fichiers.
~1 heureValidité d'une URL de téléchargement signée.

Erreurs

Les erreurs de soumission sont renvoyées de façon synchrone ; celles d'exécution apparaissent sous forme de tâche failed accompagnée d'un objet error.

StatutCodeSignification
400—Requête mal formée — le plus souvent aucune image source n'a été fournie, ni dans messages[] ni dans referenceImage.
401INVALID_API_KEY · INVALID_ORG_API_KEYClé d'API absente ou invalide.
402INSUFFICIENT_CREDITS · INSUFFICIENT_ORG_CREDITSCrédits insuffisants pour le palier de résolution de cette image.
403API_SERVICE_NOT_ALLOWED · ORG_DISABLEDLa clé ou l'organisation n'est pas autorisée à appeler ce service.
413—Une image base64 en ligne dépasse la limite de 20 Mo : transmettez plutôt une URL https.
429RATE_LIMIT_MINUTE · RATE_LIMIT_DAY · CONCURRENCY_LIMIT_EXCEEDEDLimite de débit ou de concurrence atteinte ; réessayez après une courte attente.
failederror.codeL'exécution a échoué après le démarrage de la tâche. error.code et error.message en expliquent la raison, et les crédits réservés sont intégralement remboursés.

Réponse d'erreur — 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"
}

Tâche en échec (interrogation)

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