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étourage avancé

super-matting

Détourage de haute qualité qui sépare un sujet de son arrière-plan et renvoie un résultat de détourage net. Asynchrone — soumettez, puis interrogez ou attendez un webhook.

Tarification

Facturé selon le bord de sortie le plus long (paliers de dimension — p. ex. 512 px coûtent 2 crédits, 1024 px en coûtent 10). Appelez l'endpoint /cost pour le montant exact avant d'exécuter une tâche.

Paramètres

ParamètreTypeObligatoireDescription
source_typestringOuiL'une des valeurs "url" (input_value est une URL http(s) publique d'image) ou "base64" (input_value est une chaîne base64 ou une data: URL).
input_valuestringOuiL'image source : une URL http(s) lorsque source_type vaut "url", ou des données d'image base64 lorsque source_type vaut "base64".
widthnumberOuiLargeur cible en pixels (64–2048).
heightnumberOuiHauteur cible en pixels (64–2048).
seednumberNonFacultatif. Graine entière fixe pour une sortie reproductible ; une graine aléatoire est utilisée si elle est omise.

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.

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

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.

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

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.

Une fois terminée, result.assets contient la ou les images de sortie du détourage.

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

Webhooks

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.

POST/ai/services/super-matting/execute
bash
curl -X POST https://api.vberai.com/api/ai/services/super-matting/execute \
  -H "X-API-Key: vber_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "source_type": "url",
      "input_value": "https://example.com/photo.png",
      "width": 1024,
      "height": 768
    }
  }'
bash
curl https://api.vberai.com/api/ai/tasks/{taskId} \
  -H "X-API-Key: vber_sk_YOUR_KEY"