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.
L'API VberAI expose les mêmes pipelines d'IA que ceux qui font fonctionner le studio — suppression d'arrière-plan, détourage avancé, génération d'images et plus encore — sous forme d'endpoints HTTP simples. Authentifiez-vous avec une clé d'API, soumettez une tâche, puis lisez le résultat ou recevez-le via un webhook.
Une seule forme de requête
Chaque service reçoit un corps { input } et renvoie une tâche que vous pouvez interroger ou recevoir par webhook.
Deux types de clé
Des clés personnelles pour les développeurs individuels, des clés d'entreprise pour l'usage serveur à serveur d'une organisation.
Facturation prévisible
Les crédits sont réservés à la soumission et réglés en cas de succès ; les tâches en échec sont remboursées automatiquement.
# 1. Submit a job
curl -X POST https://api.vberai.com/api/ai/services/ai-image-bg-remove/execute \
-H "X-API-Key: vber_sk_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"imageUrl": "https://example.com/photo.png"}}'
# => { "data": { "taskId": "...", "status": "queued" } }
# 2. Poll until status is "completed"
curl https://api.vberai.com/api/ai/tasks/{taskId} \
-H "X-API-Key: vber_sk_YOUR_KEY"Chaque requête est authentifiée avec une clé d'API envoyée dans l'en-tête X-API-Key. Il existe deux types de clé, qui utilisent des routes différentes — choisir la mauvaise route pour votre type de clé est la cause la plus fréquente d'une erreur 401.
Clés personnelles — vber_sk_
Pour les développeurs individuels. Créées en libre-service depuis la page des clés d'API de votre compte (nécessite un forfait avec accès à l'API). Facturées sur vos crédits personnels. Utilisez les routes /ai/services et /ai/tasks.
Clés d'entreprise — vber_org_sk_
Pour un usage serveur à serveur par une organisation. Émises par un administrateur de l'organisation dans le portail d'entreprise, et limitées aux services pour lesquels votre organisation est approuvée. Facturées sur le pool de crédits de votre organisation. Utilisez les routes /ai/org-services.
| Aspect | Clé personnelle | Clé d'entreprise |
|---|---|---|
| Préfixe de clé | vber_sk_ | vber_org_sk_ |
| Préfixe de route | /ai/services, /ai/tasks | /ai/org-services |
| Comment l'obtenir | Libre-service, paramètres du compte | Administrateur de l'organisation, portail d'entreprise |
| Facturé à | Crédits personnels | Crédits de l'organisation |
| Limites | Limites de requêtes par minute / par jour | Concurrence par organisation (personnalisée) |
X-API-Key: vber_sk_... # personal key
X-API-Key: vber_org_sk_... # enterprise keyURL de base
https://api.vberai.com/apiChaque service reçoit un corps JSON avec un objet input contenant les paramètres du service. La façon dont vous obtenez le résultat dépend du mode d'exécution du service.
Services synchrones
Les services rapides (par exemple le chat ou la traduction de texte) renvoient leur résultat en ligne dans la même réponse avec un HTTP 200. Aucune interrogation nécessaire.
Services asynchrones
Les services plus lourds (génération d'images, détourage, suppression d'arrière-plan) renvoient un HTTP 202 avec un taskId. Interrogez la tâche ou recevez le résultat via un webhook une fois terminé.
Clé personnelle
Clé d'entreprise
{
"input": {
"imageUrl": "https://example.com/photo.png"
},
"webhookUrl": "https://your-server.com/hook"
}HTTP 200 # sync: result inline
HTTP 202 # async: { "taskId": "...", "status": "queued" }Les tâches asynchrones renvoient un taskId. Interrogez la tâche jusqu'à ce que son status atteigne une valeur terminale, puis lisez le résultat. La route que vous interrogez dépend de votre type de clé — c'est le point le plus important à ne pas manquer.
| Action | Clé personnelle | Clé d'entreprise |
|---|---|---|
| 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 | Lu depuis la réponse de statut | GET /ai/org-services/tasks/{taskId}/outputs |
| Annuler une tâche | POST /ai/tasks/{taskId}/cancel | Non disponible |
| Statut par lot | GET /ai/tasks/batch-status | Non disponible |
Les clés d'entreprise doivent interroger la route /ai/org-services
Une tâche passe par ces valeurs. Arrêtez d'interroger dès que vous atteignez un status terminal : completed, failed, cancelled ou timeout.
Lorsque status vaut completed, result.assets contient les images de sortie. Chaque asset possède une url (un lien de téléchargement présigné qui expire), un mimeType et un index ; width, height, size et expiresAt apparaissent lorsqu'ils sont disponibles. Récupérez les URL rapidement — les clés d'entreprise peuvent redemander de nouveaux liens depuis l'endpoint /outputs.
# personal
curl https://api.vberai.com/api/ai/tasks/{taskId} \
-H "X-API-Key: vber_sk_YOUR_KEY"
# enterprise
curl https://api.vberai.com/api/ai/org-services/tasks/{taskId} \
-H "X-API-Key: vber_org_sk_YOUR_ORG_KEY"Tâche terminée
{
"success": true,
"data": {
"taskId": "6a97e277a148c970dd545f40",
"serviceCode": "super-matting",
"status": "completed",
"creditsEstimated": 10,
"creditsActual": 10,
"outputCount": 1,
"result": {
"type": "images",
"assets": [
{
"index": 0,
"url": "https://assets.vberai.org/tmp/user-assets/.../0.png?signature=...",
"mimeType": "image/png",
"expiresAt": "2026-01-22T10:30:12.000Z"
}
]
},
"completedAt": "2026-01-15T10:30:12.000Z"
}
}L'idempotence vous permet de réessayer une soumission en toute sécurité après une erreur réseau, sans créer de tâche en double ni être facturé deux fois.
Clés d'entreprise
Envoyez un en-tête facultatif Idempotency-Key (une valeur que vous générez, jusqu'à 200 caractères — un UUID est idéal) sur /execute-async. Réessayer avec la même clé renvoie la tâche d'origine au lieu d'en créer une nouvelle. Le serveur se contente de dédupliquer ; il ne génère pas la clé à votre place.
Clés personnelles
Les requêtes avec une clé d'API personnelle ne prennent pas en charge, pour l'instant, de clé d'idempotence. Ne réessayez qu'après avoir confirmé que la requête précédente n'a pas créé de tâche (interrogez avec le taskId que vous avez reçu).
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000Au lieu d'interroger, vous pouvez demander à VberAI d'envoyer le résultat par POST à votre serveur lorsqu'une tâche atteint un statut terminal.
Passez un webhookUrl HTTPS public (et un webhookSecret facultatif) lorsque vous soumettez la tâche. Les clés d'entreprise les lisent au niveau supérieur du corps ; les clés personnelles les lisent depuis options.
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.
{
"input": { "imageUrl": "https://example.com/photo.png" },
"webhookUrl": "https://your-server.com/hook",
"webhookSecret": "whsec_your_secret"
}Vérifier un webhook (Node.js)
import crypto from "node:crypto";
function verify(rawBody, signature, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(rawBody)
.digest("hex");
return signature === expected;
}
app.post("/hook", (req, res) => {
const sig = req.header("X-Webhook-Signature");
if (!verify(req.rawBody, sig, process.env.WEBHOOK_SECRET)) {
return res.status(401).end();
}
// req.body: { taskId, serviceCode, status, ... }
res.status(200).end();
});Les tâches d'IA coûtent des crédits. La même tarification s'applique aux clés personnelles et d'entreprise — seul le portefeuille diffère : les clés personnelles puisent dans vos crédits personnels, les clés d'entreprise dans le pool de votre organisation.
Les crédits sont réservés lorsqu'une tâche est acceptée et réglés au montant exact lorsqu'elle se termine. Si une tâche échoue ou est annulée, la réservation est intégralement remboursée — vous n'êtes jamais facturé pour une tâche en échec.
Le coût dépend du service. Certains services facturent un montant fixe par requête ; d'autres varient selon la résolution de sortie (par pixel) ou selon le bord le plus long. Appelez l'endpoint cost pour prévisualiser le montant exact avant d'exécuter une tâche.
curl -X POST https://api.vberai.com/api/ai/services/super-matting/cost \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": {"width": 1024, "height": 768}}'{
"success": true,
"data": {
"estimatedCredits": 10,
"pricingType": "custom",
"pricingMode": "dimension",
"sufficient": true
}
}La limitation de débit diffère selon le type de clé. Les deux sont configurées par service dans le backend — les valeurs ci-dessous décrivent le mécanisme, pas des chiffres fixes.
Les clés personnelles sont limitées par requêtes par minute et par jour, configurées par service. Chaque réponse porte les en-têtes ci-dessous pour vous permettre de cadencer vos appels.
| En-tête | Description |
|---|---|
X-RateLimit-Limit-Minute | Requêtes autorisées par minute. |
X-RateLimit-Remaining-Minute | Requêtes restantes dans la fenêtre de la minute en cours. |
X-RateLimit-Limit-Day | Requêtes autorisées par jour. |
X-RateLimit-Remaining-Day | Requêtes restantes dans la fenêtre du jour en cours. |
Les clés d'entreprise ne sont pas limitées par le débit de requêtes, mais par le nombre de tâches pouvant s'exécuter simultanément pour votre organisation. La limite est personnalisée par organisation (et peut être illimitée) ; la dépasser renvoie 429 CONCURRENCY_LIMIT_EXCEEDED. Les réponses d'entreprise ne portent pas d'en-têtes X-RateLimit.
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 59
X-RateLimit-Limit-Day: 2000
X-RateLimit-Remaining-Day: 1997Chaque réponse inclut success, message et timestamp. En cas d'échec, un code d'erreur identifie le problème. Aiguillez selon le code, pas selon le texte du message — les messages peuvent changer et sont uniquement en anglais.
Où se trouve le code
| Statut | Signification |
|---|---|
| 200 | Succès — résultat renvoyé en ligne. |
| 202 | Accepté — une tâche asynchrone a été créée ; interrogez ou attendez le webhook. |
| 400 | Requête incorrecte — entrée non valide, ou mauvais endpoint pour le mode d'exécution du service. |
| 401 | Non autorisé — clé d'API manquante, mal formée ou de type incorrect. |
| 402 | Paiement requis — crédits insuffisants. |
| 403 | Interdit — la clé ou le compte n'est pas autorisé à utiliser ce service. |
| 404 | Introuvable — tâche inconnue, ou tâche qui ne vous appartient pas. |
| 429 | Trop de requêtes — limite de débit ou de concurrence dépassée. |
| 500 | Erreur du serveur — réessayez ; la tâche (le cas échéant) est remboursée. |
| Code | Emplacement | Signification |
|---|---|---|
INSUFFICIENT_CREDITS | errorCode | Crédits personnels insuffisants pour la tâche. |
INSUFFICIENT_ORG_CREDITS | errorCode | Crédits de l'organisation insuffisants pour la tâche. |
ORG_API_KEY_REQUIRED | data.code | Cet endpoint nécessite une clé d'API d'entreprise (X-API-Key). |
INVALID_ORG_API_KEY | data.code | La clé d'entreprise est manquante, mal formée ou révoquée. |
INVALID_API_KEY | data.code | Le format de la clé d'API n'est pas valide — souvent une route personnelle appelée avec une clé d'entreprise (ou inversement). |
API_SERVICE_NOT_ALLOWED | errorCode | Votre organisation n'est pas approuvée pour ce service. |
ORG_DISABLED | data.code | Le compte de l'organisation est désactivé. |
CONCURRENCY_LIMIT_EXCEEDED | errorCode | Trop de tâches simultanées pour votre organisation. |
SERVICE_NOT_EXTERNALLY_ACCESSIBLE | errorCode | Ce service n'est pas disponible via l'API externe. |
TASK_NOT_FOUND | errorCode | Aucune tâche de ce type pour cette clé. |
{
"success": false,
"errorCode": "INSUFFICIENT_ORG_CREDITS",
"message": "Insufficient organization credits",
"timestamp": "2026-01-15T10:30:00.000Z"
}Détails concrets de requête et de réponse par service. Les exemples montrent les deux types de clé — choisissez l'onglet correspondant à la clé dont vous disposez. Pour les concepts sur lesquels ils reposent (interrogation, statuts, erreurs, facturation), consultez les guides ci-dessus.
ai-video-genDétourage avancésuper-mattingSuppression d'arrière-planai-image-bg-removeDécoupage en calquesai-layer-splitLes deux services ci-dessous sont entièrement documentés. Pour la liste complète et à jour des services que votre clé peut appeler — et la spécification des paramètres de chaque service —, interrogez les endpoints du catalogue. C'est la source faisant autorité, car la disponibilité dépend de votre forfait et des approbations de l'organisation.
| Endpoint | Description |
|---|---|
GET /ai/services | Liste les services auxquels votre clé peut accéder. |
GET /ai/external/services/{code}/spec | Récupère la spécification des paramètres d'un service. |
curl https://api.vberai.com/api/ai/services \
-H "X-API-Key: YOUR_API_KEY"