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.

Erweitertes Freistellen

super-matting

Hochwertiges Freistellen, das ein Motiv von seinem Hintergrund trennt und ein sauberes Freistellergebnis zurückgibt. Asynchron – einreichen, dann abfragen oder auf einen Webhook warten.

Preisgestaltung

Berechnet nach der längsten Ausgabekante (Dimensionsstufen – z. B. kosten 512 px 2 Credits, 1024 px 10). Rufe den /cost-Endpoint für den genauen Betrag auf, bevor du einen Auftrag ausführst.

Parameter

ParameterTypErforderlichBeschreibung
source_typestringJaEntweder "url" (input_value ist eine öffentliche http(s)-Bild-URL) oder "base64" (input_value ist ein base64-String oder eine data: URL).
input_valuestringJaDas Quellbild: eine http(s)-URL, wenn source_type "url" ist, oder base64-Bilddaten, wenn source_type "base64" ist.
widthnumberJaZielbreite in Pixeln (64–2048).
heightnumberJaZielhöhe in Pixeln (64–2048).
seednumberNeinOptional. Fester Ganzzahl-Seed für reproduzierbare Ausgabe; wird er weggelassen, wird ein zufälliger Seed verwendet.

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/die Ausgabebild(er) des Freistellens.

Abgeschlossener Task

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

Ü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/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"