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.

Einführung

Die VberAI-API stellt dieselben KI-Pipelines, die das studio antreiben – Hintergrundentfernung, erweitertes Freistellen, Bilderzeugung und mehr –, als einfache HTTP-Endpoints bereit. Authentifiziere dich mit einem API-Schlüssel, reiche einen Auftrag ein und lies das Ergebnis zurück oder empfange es über einen Webhook.

Eine einheitliche Anfrageform

Jeder Dienst nimmt einen { input }-Body entgegen und gibt einen Task zurück, den du abfragen oder per Webhook empfangen kannst.

Zwei Schlüsseltypen

Persönliche Schlüssel für einzelne Entwickler, Enterprise-Schlüssel für die Server-zu-Server-Nutzung einer Organisation.

Vorhersehbare Abrechnung

Credits werden bei der Einreichung reserviert und bei Erfolg abgerechnet; fehlgeschlagene Aufträge werden automatisch erstattet.

So funktioniert es

  1. 1Authentifiziere dich mit deinem API-Schlüssel im X-API-Key-Header.
  2. 2Reiche einen Auftrag bei einem Dienst mit einem JSON-{ input }-Body ein.
  3. 3Lies das Ergebnis inline (synchrone Dienste) oder frage den Task ab / empfange einen Webhook (asynchrone Dienste).
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"

Authentifizierung und API-Schlüssel

RSA-Signaturprüfung und Code-Verschleierung. MCP lädt Projektquellcode oder Assets nicht von sich aus auf VberAI-Server hoch; ob Tool-Ergebnisse in die Cloud gehen, hängt vom konfigurierten KI-Client und Modell ab.

Behandle API-Schlüssel wie Passwörter. Sende sie nur von deinem Backend, rotiere sie bei einem Leck und begrenze Enterprise-Schlüssel mit einem Ausgabenlimit.

Persönliche Schlüssel – vber_sk_

Für einzelne Entwickler. Im Self-Service auf der API-Schlüssel-Seite deines Kontos erstellt (erfordert einen Tarif mit API-Zugang). Wird von deinen persönlichen Credits abgebucht. Verwende die Routen /ai/services und /ai/tasks.

Enterprise-Schlüssel – vber_org_sk_

Für die Server-zu-Server-Nutzung durch eine Organisation. Werden von einem Organisationsadministrator im Enterprise-Portal ausgestellt und sind auf die Dienste beschränkt, für die deine Organisation freigegeben ist. Wird aus dem Credit-Pool deiner Organisation abgebucht. Verwende die Routen /ai/org-services.

AspektPersönlicher SchlüsselEnterprise-Schlüssel
Schlüsselpräfixvber_sk_vber_org_sk_
Routenpräfix/ai/services, /ai/tasks/ai/org-services
BezugSelf-Service, KontoeinstellungenOrganisationsadministrator, Enterprise-Portal
Abgebucht vonPersönliche CreditsOrganisations-Credits
LimitsAnfragelimits pro Minute / pro TagParallelität pro Organisation (individuell)
http
X-API-Key: vber_sk_...        # personal key
X-API-Key: vber_org_sk_...    # enterprise key

Basis-URL

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

Anfragen und Ausführungsmodi

Jeder Dienst nimmt einen JSON-Body mit einem input-Objekt entgegen, das die Parameter des Dienstes enthält. Wie du das Ergebnis erhältst, hängt vom Ausführungsmodus des Dienstes ab.

Synchrone Dienste

Schnelle Dienste (zum Beispiel Chat oder Textübersetzung) geben ihr Ergebnis inline in derselben Antwort mit HTTP 200 zurück. Kein Abfragen nötig.

Asynchrone Dienste

Schwerere Dienste (Bilderzeugung, Freistellen, Hintergrundentfernung) geben HTTP 202 mit einer taskId zurück. Frage den Task ab oder empfange das Ergebnis über einen Webhook, sobald er fertig ist.

Persönlicher Schlüssel

Persönliche Schlüssel verwenden einen einzigen Endpoint pro Dienst: POST /ai/services/{code}/execute. Er gibt das Ergebnis inline (200) für synchrone Dienste zurück oder einen Task (202) für asynchrone – in beiden Fällen derselbe Endpoint.

Enterprise-Schlüssel

Enterprise-Schlüssel verwenden zwei Endpoints: /execute für synchrone Dienste und /execute-async für asynchrone. Der Aufruf des falschen gibt 400 zurück und teilt dir mit, welchen Endpoint du verwenden sollst.
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" }

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.

Welche Route abfragen

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
Einen Task abbrechenPOST /ai/tasks/{taskId}/cancelNicht verfügbar
Batch-StatusGET /ai/tasks/batch-statusNicht verfügbar

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.

Task-Status

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

createdqueueddispatchingsubmittedprocessingcompletedfailedcancelledtimeout

Das Ergebnis lesen

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.

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"

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

Idempotenz

Idempotenz erlaubt es dir, eine Einreichung nach einem Netzwerkfehler sicher zu wiederholen, ohne einen doppelten Auftrag zu erzeugen oder doppelt belastet zu werden.

Enterprise-Schlüssel

Sende einen optionalen Idempotency-Key-Header (einen Wert, den du generierst, bis zu 200 Zeichen – eine UUID ist ideal) an /execute-async. Ein erneuter Versuch mit demselben Schlüssel gibt den ursprünglichen Task zurück, anstatt einen neuen zu erstellen. Der Server dedupliziert nur; er generiert den Schlüssel nicht für dich.

Persönliche Schlüssel

Anfragen mit persönlichem API-Schlüssel unterstützen derzeit keinen Idempotenzschlüssel. Wiederhole erst, nachdem du bestätigt hast, dass die vorherige Anfrage keinen Task erstellt hat (frage mit der erhaltenen taskId ab).

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

Webhooks

Statt abzufragen, kannst du VberAI das Ergebnis per POST an deinen Server senden lassen, wenn ein Task einen terminalen Status erreicht.

Einen Webhook konfigurieren

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

Die Signatur verifizieren

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.

Fehlgeschlagene Zustellungen werden einige Male mit Backoff wiederholt. Antworte mit 2xx, um den Empfang zu bestätigen.
json
{
  "input": { "imageUrl": "https://example.com/photo.png" },
  "webhookUrl": "https://your-server.com/hook",
  "webhookSecret": "whsec_your_secret"
}

Einen Webhook verifizieren (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();
});

Credits und Abrechnung

KI-Aufträge kosten Credits. Für persönliche und Enterprise-Schlüssel gilt dieselbe Preisgestaltung – nur die Geldbörse unterscheidet sich: Persönliche Schlüssel schöpfen aus deinen persönlichen Credits, Enterprise-Schlüssel aus dem Pool deiner Organisation.

Reservieren, abrechnen, erstatten

Credits werden reserviert, wenn ein Auftrag angenommen wird, und beim Abschluss auf den genauen Betrag abgerechnet. Schlägt ein Auftrag fehl oder wird abgebrochen, wird die Reservierung vollständig erstattet – für einen fehlgeschlagenen Auftrag wirst du nie belastet.

Wie die Kosten berechnet werden

Die Kosten hängen vom Dienst ab. Manche Dienste berechnen einen festen Betrag pro Anfrage; andere skalieren mit der Ausgabeauflösung (pro Pixel) oder nach der längsten Kante. Rufe den cost-Endpoint auf, um die genaue Gebühr vorab anzuzeigen, bevor du einen Auftrag ausführst.

  • •Pro Anfrage – ein fester Betrag bei jedem Aufruf.
  • •Pro Pixel – skaliert mit width × height der Ausgabe.
  • •Nach Dimension – berechnet nach der längsten Kante der Ausgabe.
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
  }
}

Ratenbegrenzungen

Die Ratenbegrenzung unterscheidet sich je nach Schlüsseltyp. Beide werden pro Dienst im Backend konfiguriert – die Werte unten beschreiben den Mechanismus, keine festen Zahlen.

Persönliche Schlüssel – Anfragerate

Persönliche Schlüssel werden durch Anfragen pro Minute und pro Tag begrenzt, konfiguriert pro Dienst. Jede Antwort trägt die untenstehenden Header, damit du deine Aufrufe takten kannst.

HeaderBeschreibung
X-RateLimit-Limit-MinutePro Minute erlaubte Anfragen.
X-RateLimit-Remaining-MinuteIm aktuellen Minutenfenster verbleibende Anfragen.
X-RateLimit-Limit-DayPro Tag erlaubte Anfragen.
X-RateLimit-Remaining-DayIm aktuellen Tagesfenster verbleibende Anfragen.
Es gibt keinen X-RateLimit-Reset-Header. Bei einem 429 enthält der Antwort-Body retryAfter und resetIn.

Enterprise-Schlüssel – Parallelität

Enterprise-Schlüssel werden nicht durch die Anfragerate begrenzt, sondern dadurch, wie viele Aufträge für deine Organisation gleichzeitig laufen dürfen. Das Limit ist pro Organisation individuell (und kann unbegrenzt sein); eine Überschreitung gibt 429 CONCURRENCY_LIMIT_EXCEEDED zurück. Enterprise-Antworten tragen keine X-RateLimit-Header.

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

Fehler

Jede Antwort enthält success, message und timestamp. Bei einem Fehler identifiziert ein Fehlercode das Problem. Verzweige anhand des Codes, nicht des message-Textes – Meldungen können sich ändern und sind nur auf Englisch.

Wo der Code steht

Enterprise-Fehler sind einheitlich: Authentifizierungsprobleme legen den Code in data.code ab, während Dienst- und Abrechnungsprobleme ihn in den errorCode der obersten Ebene legen. Persönliche Fehler variieren je nach Endpoint (errorCode der obersten Ebene, data.code oder errors.code) – lies das für jeden Code angegebene Feld.

HTTP-Statuscodes

StatusBedeutung
200Erfolg – Ergebnis inline zurückgegeben.
202Akzeptiert – ein asynchroner Task wurde erstellt; frage ab oder warte auf den Webhook.
400Ungültige Anfrage – ungültige Eingabe oder falscher Endpoint für den Ausführungsmodus des Dienstes.
401Nicht autorisiert – API-Schlüssel fehlt, ist fehlerhaft oder vom falschen Typ.
402Zahlung erforderlich – nicht genügend Credits.
403Verboten – der Schlüssel oder das Konto darf diesen Dienst nicht nutzen.
404Nicht gefunden – unbekannter Task oder ein Task, der nicht dir gehört.
429Zu viele Anfragen – Raten- oder Parallelitätslimit überschritten.
500Serverfehler – versuche es erneut; der Auftrag (falls vorhanden) wird erstattet.

Häufige Fehlercodes

CodeOrtBedeutung
INSUFFICIENT_CREDITSerrorCodeNicht genügend persönliche Credits für den Auftrag.
INSUFFICIENT_ORG_CREDITSerrorCodeNicht genügend Organisations-Credits für den Auftrag.
ORG_API_KEY_REQUIREDdata.codeDieser Endpoint benötigt einen Enterprise-API-Schlüssel (X-API-Key).
INVALID_ORG_API_KEYdata.codeDer Enterprise-Schlüssel fehlt, ist fehlerhaft oder wurde widerrufen.
INVALID_API_KEYdata.codeDas Format des API-Schlüssels ist ungültig – oft eine persönliche Route, die mit einem Enterprise-Schlüssel aufgerufen wurde (oder umgekehrt).
API_SERVICE_NOT_ALLOWEDerrorCodeDeine Organisation ist für diesen Dienst nicht freigegeben.
ORG_DISABLEDdata.codeDas Organisationskonto ist deaktiviert.
CONCURRENCY_LIMIT_EXCEEDEDerrorCodeZu viele gleichzeitige Aufträge für deine Organisation.
SERVICE_NOT_EXTERNALLY_ACCESSIBLEerrorCodeDieser Dienst ist über die externe API nicht verfügbar.
TASK_NOT_FOUNDerrorCodeKein solcher Task für diesen Schlüssel.
json
{
  "success": false,
  "errorCode": "INSUFFICIENT_ORG_CREDITS",
  "message": "Insufficient organization credits",
  "timestamp": "2026-01-15T10:30:00.000Z"
}

API-Dokumentation

Konkrete Anfrage- und Antwortdetails pro Dienst. Die Beispiele zeigen beide Schlüsseltypen – wähle den Tab für den Schlüssel, den du hast. Für die zugrunde liegenden Konzepte (Abfragen, Status, Fehler, Abrechnung) siehe die Leitfäden oben.

Verfügbare Dienste

Die beiden folgenden Dienste sind vollständig dokumentiert. Für die vollständige, aktuelle Liste der Dienste, die dein Schlüssel aufrufen kann – und die Parameterspezifikation jedes Dienstes –, frage die Katalog-Endpoints ab. Dies ist die maßgebliche Quelle, da die Verfügbarkeit von deinem Tarif und den Freigaben der Organisation abhängt.

EndpointBeschreibung
GET /ai/servicesListet die Dienste auf, auf die dein Schlüssel zugreifen kann.
GET /ai/external/services/{code}/specRuft die Parameterspezifikation eines Dienstes ab.
bash
curl https://api.vberai.com/api/ai/services \
  -H "X-API-Key: YOUR_API_KEY"