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.
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.
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.
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.
| Action | Clé personnelle | Clé d'entreprise |
|---|---|---|
| Soumettre | POST /ai/tasks | POST /ai/org-services/ai-layer-split/execute-async |
| Interroger le statut de la tâche | GET /ai/tasks/{taskId} | GET /ai/org-services/tasks/{taskId} |
| Resigner de nouvelles URL de téléchargement | GET /ai/tasks/{taskId}/outputs | GET /ai/org-services/tasks/{taskId}/outputs |
Les clés d'entreprise doivent interroger la route /ai/org-services
Les paramètres du service sont identiques pour les deux types de clé ; seule l'enveloppe qui les entoure diffère.
| Champ | Clé personnelle | Clé d'entreprise |
|---|---|---|
| Les paramètres de service listés ci-dessous. | serviceCode + inputs | input |
webhookUrl | facultatif | facultatif |
webhookSecret | facultatif | facultatif |
Clé personnelle
| Paramètre | Type | Obligatoire | Description |
|---|---|---|---|
messages | array | l'un des deux | Tableau 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. |
referenceImage | string | l'un des deux | Forme abrégée pour l'image source : une URL https publique ou un data: URI en ligne. À utiliser à la place de messages[]. |
referenceWidth | number | Non | Largeur 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. |
referenceHeight | number | Non | Hauteur déclarée de la source en pixels. Même rôle que referenceWidth. |
imageConfig | object | Non | Réservé à de futures options de génération. Ignoré aujourd'hui. |
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.
{
"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"
}'Réponse à la soumission — 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"
}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.
| Champ | Description |
|---|---|
taskId | Identifiant de la tâche, utilisé pour l'interrogation, les sorties et la corrélation du webhook. |
serviceCode | Toujours ai-layer-split. |
status | queued · processing · completed · failed · cancelled · timeout. |
progress | Progression approximative lorsque le backend la remonte ; null sinon. |
provider | Canal d'exécution. Toujours signalé comme external. |
hasResult | true dès que result est disponible. |
error | Motif de l'échec ; null tant que la tâche se déroule bien. |
createdAt · startedAt · completedAt | Dates de création, de démarrage et de fin (ISO 8601, UTC). |
expiresAt | Date de purge de l'enregistrement et des fichiers : sept jours après la fin. |
creditsEstimated · creditsActual | Cré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é. |
outputCount | Nombre de fichiers renvoyés. |
result | L'objet de résultat décrit ci-dessous ; présent une fois la tâche terminée. |
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é.
{
"success": true,
"data": {
"taskId": "6a9db1431ef5f254006213e0",
"status": "completed",
"result": { "type": "images", "assets": [ … ], "text": "{ … }" },
"completedAt": "2026-09-06T18:32:26.326Z"
}
}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
{
"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
{
"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
/ai/tasks/{taskId}curl https://api.vberai.com/api/ai/tasks/{taskId} \
-H "X-API-Key: vber_sk_YOUR_KEY"Récupérer les sorties
/ai/tasks/{taskId}/outputscurl https://api.vberai.com/api/ai/tasks/{taskId}/outputs \
-H "X-API-Key: vber_sk_YOUR_KEY"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.
| Champ | Type | Description |
|---|---|---|
index | number | Position dans le tableau assets. |
name | string | Id 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. |
url | string | Lien 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. |
size | number | Taille du fichier en octets. |
sha256 | string | SHA-256 du fichier, pour le contrôle d'intégrité et la déduplication. |
s3Key | string | Clé d'objet interne. Purement informative. |
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.
| Valeur | Signification |
|---|---|
Lbg | Le 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. |
| group | Entrées de groupe. Pas de PNG ; elles indiquent seulement quels calques vont ensemble. |
Tâche terminée
{
"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 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.
| Champ | Type | Description |
|---|---|---|
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. |
nodes | LayerNode[] | Tous les calques dans un tableau à plat. Le regroupement vient de parentId, l'empilement de paintOrder ; l'ordre du tableau n'a aucune signification. |
| Champ | Type | Description |
|---|---|---|
id | string | Id du calque, identique au assets[].name correspondant (Lbg, A001, T001…). Il sert à associer un calque à son PNG. |
name | string | Nom 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. |
kind | string | Type 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. |
parentId | string | null | Id du groupe contenant, ou null au niveau racine. |
paintOrder | number | Ordre d'empilement entre calques de même parent, croissant de l'arrière vers l'avant. Le fond vaut -1. |
occluded | boolean | true 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. |
text | object | Style de texte ; présent uniquement lorsque kind vaut text. |
| Valeur | Signification |
|---|---|
background | Le fond reconstitué. Un seul, dessiné en premier. |
group | Conteneur servant à l'imbrication. Sans image propre. |
ui | Panneau, carte, bouton ou autre surface d'interface. Livré avec un PNG. |
icon | Petit pictogramme. Livré avec un PNG, traité comme ui. |
text | Texte applicatif. Aucun PNG : à recréer en texte modifiable. |
| Champ | Type | Description |
|---|---|---|
text | string | Les caractères lus sur la capture, dans leur langue d'origine. |
fontSizePct | number | Hauteur 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. |
fontWeight | 100–900 | Graisse numérique de la police. |
italic | boolean | Indique si le texte est incliné. |
align | "LEFT" | "CENTER" | "RIGHT" | Alignement horizontal dans la boîte. |
fontFamily | string | Famille 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. |
strokeWidthPct | number | É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)
{
"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
// 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 }
}
}
]
}Positions et tailles sont des fractions : la même liste fonctionne à n'importe quelle taille en pixels.
Construire une liste de placement
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
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.
| Palier | Grand côté | Crédits |
|---|---|---|
1K | ≤ 1024 px | 120 |
2K | ≤ 2048 px | 180 |
4K | > 2048 px | 250 |
| Valeur | Description |
|---|---|
2048 px | Les sources sont réduites à 2048 px de grand côté avant analyse. |
300 | 300 éléments détectés au maximum par image. |
20 MB | Le média base64 en ligne est limité à 20 Mo par élément. |
| 2–3 min | Durée typique de bout en bout. |
| 7 jours | Conservation de l'enregistrement et des fichiers. |
| ~1 heure | Validité d'une URL de téléchargement signée. |
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.
| Statut | Code | Signification |
|---|---|---|
| 400 | — | Requête mal formée — le plus souvent aucune image source n'a été fournie, ni dans messages[] ni dans referenceImage. |
| 401 | INVALID_API_KEY · INVALID_ORG_API_KEY | Clé d'API absente ou invalide. |
| 402 | INSUFFICIENT_CREDITS · INSUFFICIENT_ORG_CREDITS | Crédits insuffisants pour le palier de résolution de cette image. |
| 403 | API_SERVICE_NOT_ALLOWED · ORG_DISABLED | La 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. |
| 429 | RATE_LIMIT_MINUTE · RATE_LIMIT_DAY · CONCURRENCY_LIMIT_EXCEEDED | Limite de débit ou de concurrence atteinte ; réessayez après une courte attente. |
| failed | error.code | L'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
{
"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)
{
"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
}
}