VberAI Entwickler-API

VberAI bietet eine REST-HTTP-API, um KI-Funktionen (heute AI Super Matting) in Apps, Spiele und Pipelines einzubinden. Authentifizierung per API-Key + Signatur, einheitliche Fehlercodes, Abrechnung per Credit.

API v1
Stabil

API-Dokumentation

Erzeuge Bilder, entferne Hintergründe und führe die KI-Pipelines von VberAI direkt über HTTP aus – mit persönlichen oder Enterprise-API-Schlüsseln.

Hintergrundentfernung

ai-image-bg-remove

Entfernt den Hintergrund eines Bildes und gibt ein Freistellergebnis mit transparentem Hintergrund zurück. Asynchron – einreichen, dann abfragen oder auf einen Webhook warten.

Preisgestaltung

Eine Pauschalgebühr pro Bild. Rufe den /cost-Endpoint für den genauen Betrag auf.

Parameter

ParameterTypErforderlichBeschreibung
imageUrlstringJaÖffentliche http(s)-URL des zu verarbeitenden Bildes. Dies ist die einzige Eingabe, die der Dienst annimmt – er akzeptiert weder base64 noch einen source_type.
widthnumberNeinOptional. Wird nur als Ersatz für die Abrechnungsfläche verwendet, wenn die Quellauflösung nicht erkannt werden kann; ändert die Ausgabe nicht.
heightnumberNeinOptional. Wird nur als Ersatz für die Abrechnungsfläche verwendet, wenn die Quellauflösung nicht erkannt werden kann; ändert die Ausgabe nicht.

Abfragen und Ergebnisse

Asynchrone Aufträge geben eine taskId zurück. Frage den Task ab, bis sein status einen terminalen Wert erreicht, und lies dann das Ergebnis. Welche Route du abfragst, hängt von deinem Schlüsseltyp ab – das ist das Wichtigste, das du richtig machen musst.

AktionPersönlicher SchlüsselEnterprise-Schlüssel
Task-Status abfragenGET /ai/tasks/{taskId}GET /ai/org-services/tasks/{taskId}
Neue Download-URLs neu signierenAus der Status-Antwort gelesenGET /ai/org-services/tasks/{taskId}/outputs

Enterprise-Schlüssel müssen die Route /ai/org-services abfragen

Ein Enterprise-Schlüssel (vber_org_sk_), der an eine persönliche /ai/tasks-Route gesendet wird, gibt 401 INVALID_API_KEY zurück – die persönlichen Routen akzeptieren nur persönliche Schlüssel. Frage Enterprise-Aufträge immer unter /ai/org-services/tasks/{taskId} ab. cancel und batch-status sind nur mit persönlichen Schlüsseln verfügbar.

Ein Task durchläuft diese Werte. Höre auf abzufragen, sobald du einen terminalen status erreichst: completed, failed, cancelled oder timeout.

createdqueueddispatchingsubmittedprocessingcompletedfailedcancelledtimeout

Wenn status completed ist, enthält result.assets die Ausgabebilder. Jedes asset hat eine url (einen vorsignierten Download-Link, der abläuft), einen mimeType und einen index; width, height, size und expiresAt erscheinen, sofern verfügbar. Rufe die URLs zügig ab – Enterprise-Schlüssel können frische Links vom /outputs-Endpoint neu anfordern.

Nach Abschluss enthält result.assets das freigestellte Bild mit transparentem Hintergrund.

Abgeschlossener Task

json
{
  "success": true,
  "data": {
    "taskId": "6a97e277a148c970dd545f40",
    "serviceCode": "ai-image-bg-remove",
    "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

Übergib beim Einreichen des Auftrags eine öffentliche HTTPS-webhookUrl (und ein optionales webhookSecret). Enterprise-Schlüssel lesen diese aus der obersten Ebene des Bodys; persönliche Schlüssel lesen sie aus options.

Wenn du ein webhookSecret setzt, enthält jede Zustellung einen X-Webhook-Signature-Header – ein HMAC-SHA256 der rohen JSON-Nutzlast, hex-codiert. Berechne ihn mit deinem Secret neu und vergleiche, bevor du der Nutzlast vertraust. Zustellungen tragen außerdem einen X-Idempotency-Key (taskId + status), sodass du Duplikate ignorieren kannst.

POST/ai/services/ai-image-bg-remove/execute
bash
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"}}'
bash
curl https://api.vberai.com/api/ai/tasks/{taskId} \
  -H "X-API-Key: vber_sk_YOUR_KEY"