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.
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.
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.
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.
# 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"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.
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.
| Aspekt | Persönlicher Schlüssel | Enterprise-Schlüssel |
|---|---|---|
| Schlüsselpräfix | vber_sk_ | vber_org_sk_ |
| Routenpräfix | /ai/services, /ai/tasks | /ai/org-services |
| Bezug | Self-Service, Kontoeinstellungen | Organisationsadministrator, Enterprise-Portal |
| Abgebucht von | Persönliche Credits | Organisations-Credits |
| Limits | Anfragelimits pro Minute / pro Tag | Parallelität pro Organisation (individuell) |
X-API-Key: vber_sk_... # personal key
X-API-Key: vber_org_sk_... # enterprise keyBasis-URL
https://api.vberai.com/apiJeder 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
Enterprise-Schlüssel
{
"input": {
"imageUrl": "https://example.com/photo.png"
},
"webhookUrl": "https://your-server.com/hook"
}HTTP 200 # sync: result inline
HTTP 202 # async: { "taskId": "...", "status": "queued" }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.
| Aktion | Persönlicher Schlüssel | Enterprise-Schlüssel |
|---|---|---|
| Task-Status abfragen | GET /ai/tasks/{taskId} | GET /ai/org-services/tasks/{taskId} |
| Neue Download-URLs neu signieren | Aus der Status-Antwort gelesen | GET /ai/org-services/tasks/{taskId}/outputs |
| Einen Task abbrechen | POST /ai/tasks/{taskId}/cancel | Nicht verfügbar |
| Batch-Status | GET /ai/tasks/batch-status | Nicht verfügbar |
Enterprise-Schlüssel müssen die Route /ai/org-services abfragen
Ein Task durchläuft diese Werte. Höre auf abzufragen, sobald du einen terminalen status erreichst: completed, failed, cancelled oder timeout.
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.
# 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
{
"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 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).
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000Statt abzufragen, kannst du VberAI das Ergebnis per POST an deinen Server senden lassen, wenn ein Task einen terminalen Status erreicht.
Ü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.
{
"input": { "imageUrl": "https://example.com/photo.png" },
"webhookUrl": "https://your-server.com/hook",
"webhookSecret": "whsec_your_secret"
}Einen Webhook verifizieren (Node.js)
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();
});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.
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.
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.
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}}'{
"success": true,
"data": {
"estimatedCredits": 10,
"pricingType": "custom",
"pricingMode": "dimension",
"sufficient": true
}
}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 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.
| Header | Beschreibung |
|---|---|
X-RateLimit-Limit-Minute | Pro Minute erlaubte Anfragen. |
X-RateLimit-Remaining-Minute | Im aktuellen Minutenfenster verbleibende Anfragen. |
X-RateLimit-Limit-Day | Pro Tag erlaubte Anfragen. |
X-RateLimit-Remaining-Day | Im aktuellen Tagesfenster verbleibende Anfragen. |
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.
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 59
X-RateLimit-Limit-Day: 2000
X-RateLimit-Remaining-Day: 1997Jede 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
| Status | Bedeutung |
|---|---|
| 200 | Erfolg – Ergebnis inline zurückgegeben. |
| 202 | Akzeptiert – ein asynchroner Task wurde erstellt; frage ab oder warte auf den Webhook. |
| 400 | Ungültige Anfrage – ungültige Eingabe oder falscher Endpoint für den Ausführungsmodus des Dienstes. |
| 401 | Nicht autorisiert – API-Schlüssel fehlt, ist fehlerhaft oder vom falschen Typ. |
| 402 | Zahlung erforderlich – nicht genügend Credits. |
| 403 | Verboten – der Schlüssel oder das Konto darf diesen Dienst nicht nutzen. |
| 404 | Nicht gefunden – unbekannter Task oder ein Task, der nicht dir gehört. |
| 429 | Zu viele Anfragen – Raten- oder Parallelitätslimit überschritten. |
| 500 | Serverfehler – versuche es erneut; der Auftrag (falls vorhanden) wird erstattet. |
| Code | Ort | Bedeutung |
|---|---|---|
INSUFFICIENT_CREDITS | errorCode | Nicht genügend persönliche Credits für den Auftrag. |
INSUFFICIENT_ORG_CREDITS | errorCode | Nicht genügend Organisations-Credits für den Auftrag. |
ORG_API_KEY_REQUIRED | data.code | Dieser Endpoint benötigt einen Enterprise-API-Schlüssel (X-API-Key). |
INVALID_ORG_API_KEY | data.code | Der Enterprise-Schlüssel fehlt, ist fehlerhaft oder wurde widerrufen. |
INVALID_API_KEY | data.code | Das 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_ALLOWED | errorCode | Deine Organisation ist für diesen Dienst nicht freigegeben. |
ORG_DISABLED | data.code | Das Organisationskonto ist deaktiviert. |
CONCURRENCY_LIMIT_EXCEEDED | errorCode | Zu viele gleichzeitige Aufträge für deine Organisation. |
SERVICE_NOT_EXTERNALLY_ACCESSIBLE | errorCode | Dieser Dienst ist über die externe API nicht verfügbar. |
TASK_NOT_FOUND | errorCode | Kein solcher Task für diesen Schlüssel. |
{
"success": false,
"errorCode": "INSUFFICIENT_ORG_CREDITS",
"message": "Insufficient organization credits",
"timestamp": "2026-01-15T10:30:00.000Z"
}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.
ai-video-genErweitertes Freistellensuper-mattingHintergrundentfernungai-image-bg-removeEbenentrennungai-layer-splitDie 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.
| Endpoint | Beschreibung |
|---|---|
GET /ai/services | Listet die Dienste auf, auf die dein Schlüssel zugreifen kann. |
GET /ai/external/services/{code}/spec | Ruft die Parameterspezifikation eines Dienstes ab. |
curl https://api.vberai.com/api/ai/services \
-H "X-API-Key: YOUR_API_KEY"