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.

Introduction

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.

Comment ça marche

  1. 1Authentifiez-vous avec votre clé d'API dans l'en-tête X-API-Key.
  2. 2Soumettez une tâche à un service avec un corps JSON { input }.
  3. 3Lisez le résultat en ligne (services synchrones) ou interrogez la tâche / recevez un webhook (services asynchrones).
bash
# 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"

Authentification et clés d'API

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.

Traitez les clés d'API comme des mots de passe. Ne les envoyez que depuis votre backend, faites-les tourner en cas de fuite et limitez les clés d'entreprise avec un plafond de dépenses.

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.

AspectClé personnelleClé d'entreprise
Préfixe de clévber_sk_vber_org_sk_
Préfixe de route/ai/services, /ai/tasks/ai/org-services
Comment l'obtenirLibre-service, paramètres du compteAdministrateur de l'organisation, portail d'entreprise
Facturé àCrédits personnelsCrédits de l'organisation
LimitesLimites de requêtes par minute / par jourConcurrence par organisation (personnalisée)
http
X-API-Key: vber_sk_...        # personal key
X-API-Key: vber_org_sk_...    # enterprise key

URL de base

text
https://api.vberai.com/api

Requêtes et modes d'exécution

Chaque 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

Les clés personnelles utilisent un seul endpoint par service : POST /ai/services/{code}/execute. Il renvoie le résultat en ligne (200) pour les services synchrones, ou une tâche (202) pour les asynchrones — le même endpoint dans les deux cas.

Clé d'entreprise

Les clés d'entreprise utilisent deux endpoints : /execute pour les services synchrones et /execute-async pour les asynchrones. Appeler le mauvais renvoie un 400 vous indiquant quel endpoint utiliser.
json
{
  "input": {
    "imageUrl": "https://example.com/photo.png"
  },
  "webhookUrl": "https://your-server.com/hook"
}
bash
HTTP 200  # sync: result inline
HTTP 202  # async: { "taskId": "...", "status": "queued" }

Interrogation et résultats

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.

Quelle route interroger

ActionClé personnelleClé d'entreprise
Interroger le statut de la tâcheGET /ai/tasks/{taskId}GET /ai/org-services/tasks/{taskId}
Resigner de nouvelles URL de téléchargementLu depuis la réponse de statutGET /ai/org-services/tasks/{taskId}/outputs
Annuler une tâchePOST /ai/tasks/{taskId}/cancelNon disponible
Statut par lotGET /ai/tasks/batch-statusNon disponible

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.

Statuts de tâche

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

createdqueueddispatchingsubmittedprocessingcompletedfailedcancelledtimeout

Lecture du résultat

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.

bash
# 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

json
{
  "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"
  }
}

Idempotence

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).

http
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Webhooks

Au lieu d'interroger, vous pouvez demander à VberAI d'envoyer le résultat par POST à votre serveur lorsqu'une tâche atteint un statut terminal.

Configurer un webhook

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.

Vérifier la signature

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.

Les livraisons en échec sont réessayées plusieurs fois avec un délai croissant. Répondez avec un 2xx pour accuser réception.
json
{
  "input": { "imageUrl": "https://example.com/photo.png" },
  "webhookUrl": "https://your-server.com/hook",
  "webhookSecret": "whsec_your_secret"
}

Vérifier un webhook (Node.js)

javascript
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();
});

Crédits et facturation

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.

Réserver, régler, rembourser

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.

Comment le coût est calculé

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.

  • •Par requête — un montant fixe à chaque appel.
  • •Par pixel — varie selon width × height de la sortie.
  • •Par dimension — facturé selon le bord le plus long de la sortie.
bash
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}}'
json
{
  "success": true,
  "data": {
    "estimatedCredits": 10,
    "pricingType": "custom",
    "pricingMode": "dimension",
    "sufficient": true
  }
}

Limites de débit

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.

Clés personnelles — débit de requêtes

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êteDescription
X-RateLimit-Limit-MinuteRequêtes autorisées par minute.
X-RateLimit-Remaining-MinuteRequêtes restantes dans la fenêtre de la minute en cours.
X-RateLimit-Limit-DayRequêtes autorisées par jour.
X-RateLimit-Remaining-DayRequêtes restantes dans la fenêtre du jour en cours.
Il n'y a pas d'en-tête X-RateLimit-Reset. Lors d'un 429, le corps de la réponse inclut retryAfter et resetIn.

Clés d'entreprise — concurrence

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.

http
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 59
X-RateLimit-Limit-Day: 2000
X-RateLimit-Remaining-Day: 1997

Erreurs

Chaque 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

Les erreurs d'entreprise sont cohérentes : les problèmes d'authentification placent le code dans data.code, tandis que les problèmes de service et de facturation le placent dans le errorCode de niveau supérieur. Les erreurs personnelles varient selon l'endpoint (errorCode de niveau supérieur, data.code ou errors.code) — lisez le champ indiqué pour chaque code.

Codes de statut HTTP

StatutSignification
200Succès — résultat renvoyé en ligne.
202Accepté — une tâche asynchrone a été créée ; interrogez ou attendez le webhook.
400Requête incorrecte — entrée non valide, ou mauvais endpoint pour le mode d'exécution du service.
401Non autorisé — clé d'API manquante, mal formée ou de type incorrect.
402Paiement requis — crédits insuffisants.
403Interdit — la clé ou le compte n'est pas autorisé à utiliser ce service.
404Introuvable — tâche inconnue, ou tâche qui ne vous appartient pas.
429Trop de requêtes — limite de débit ou de concurrence dépassée.
500Erreur du serveur — réessayez ; la tâche (le cas échéant) est remboursée.

Codes d'erreur courants

CodeEmplacementSignification
INSUFFICIENT_CREDITSerrorCodeCrédits personnels insuffisants pour la tâche.
INSUFFICIENT_ORG_CREDITSerrorCodeCrédits de l'organisation insuffisants pour la tâche.
ORG_API_KEY_REQUIREDdata.codeCet endpoint nécessite une clé d'API d'entreprise (X-API-Key).
INVALID_ORG_API_KEYdata.codeLa clé d'entreprise est manquante, mal formée ou révoquée.
INVALID_API_KEYdata.codeLe 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_ALLOWEDerrorCodeVotre organisation n'est pas approuvée pour ce service.
ORG_DISABLEDdata.codeLe compte de l'organisation est désactivé.
CONCURRENCY_LIMIT_EXCEEDEDerrorCodeTrop de tâches simultanées pour votre organisation.
SERVICE_NOT_EXTERNALLY_ACCESSIBLEerrorCodeCe service n'est pas disponible via l'API externe.
TASK_NOT_FOUNDerrorCodeAucune tâche de ce type pour cette clé.
json
{
  "success": false,
  "errorCode": "INSUFFICIENT_ORG_CREDITS",
  "message": "Insufficient organization credits",
  "timestamp": "2026-01-15T10:30:00.000Z"
}

Documentation API

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.

Services disponibles

Les 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.

EndpointDescription
GET /ai/servicesListe les services auxquels votre clé peut accéder.
GET /ai/external/services/{code}/specRécupère la spécification des paramètres d'un service.
bash
curl https://api.vberai.com/api/ai/services \
  -H "X-API-Key: YOUR_API_KEY"