VberAI API — RESTful Reference for Developers

The VberAI API is a RESTful HTTP API for embedding VberAI's AI capabilities (today: AI Super Matting) into your apps, games, and automation pipelines. Authentication uses API keys with signature-based requests; common error codes are standardised; per-call billing is paid in VberAI credits.

API v1
Stable

API Docs

Generate images, remove backgrounds, and run VberAI's AI pipelines directly over HTTP — with personal or enterprise API keys.

Introduction

The VberAI API exposes the same AI pipelines that power the studio — background removal, super matting, image generation and more — as simple HTTP endpoints. Authenticate with an API key, submit a job, and read the result back or receive it on a webhook.

One request shape

Every service takes an { input } body and returns a task you can poll or receive by webhook.

Two key types

Personal keys for individual developers, enterprise keys for server-to-server org usage.

Predictable billing

Credits are reserved on submit and settled on success; failed jobs are refunded automatically.

How it works

  1. 1Authenticate with your API key in the X-API-Key header.
  2. 2Submit a job to a service with a JSON { input } body.
  3. 3Read the result inline (sync services) or poll the task / receive a webhook (async services).
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"

Authentication & API keys

Every request is authenticated with an API key sent in the X-API-Key header. There are two kinds of key, and they use different routes — choosing the wrong route for your key type is the most common cause of a 401.

Treat API keys like passwords. Send them only from your backend, rotate them if leaked, and scope enterprise keys with a spending cap.

Personal keys — vber_sk_

For individual developers. Created self-service from your account's API keys page (requires a plan with API access). Billed against your personal credits. Use the /ai/services and /ai/tasks routes.

Enterprise keys — vber_org_sk_

For server-to-server use by an organization. Issued by an organization admin in the enterprise portal, and limited to the services your organization is approved for. Billed against your organization's credit pool. Use the /ai/org-services routes.

AspectPersonal keyEnterprise key
Key prefixvber_sk_vber_org_sk_
Route prefix/ai/services, /ai/tasks/ai/org-services
How to obtainSelf-service, account settingsOrg admin, enterprise portal
Billed toPersonal creditsOrganization credits
LimitsPer-minute / per-day request limitsPer-organization concurrency (custom)
http
X-API-Key: vber_sk_...        # personal key
X-API-Key: vber_org_sk_...    # enterprise key

Base URL

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

Requests & execution modes

Every service takes a JSON body with an input object holding the service's parameters. How you get the result depends on the service's execution mode.

Synchronous services

Fast services (for example chat or text translation) return their result inline in the same response with HTTP 200. No polling needed.

Asynchronous services

Heavier services (image generation, matting, background removal) return HTTP 202 with a taskId. Poll the task or receive the result on a webhook when it finishes.

Personal key

Personal keys use a single endpoint per service: POST /ai/services/{code}/execute. It returns the result inline (200) for sync services, or a task (202) for async ones — the same endpoint either way.

Enterprise key

Enterprise keys use two endpoints: /execute for sync services and /execute-async for async ones. Calling the wrong one returns 400 telling you which endpoint to use.
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" }

Polling & results

Asynchronous jobs return a taskId. Poll the task until its status is a terminal value, then read the result. The route you poll depends on your key type — this is the single most important thing to get right.

Which route to poll

ActionPersonal keyEnterprise key
Poll task statusGET /ai/tasks/{taskId}GET /ai/org-services/tasks/{taskId}
Re-sign fresh download URLsRead from the status responseGET /ai/org-services/tasks/{taskId}/outputs
Cancel a taskPOST /ai/tasks/{taskId}/cancelNot available
Batch statusGET /ai/tasks/batch-statusNot available

Enterprise keys must poll the /ai/org-services route

An enterprise key (vber_org_sk_) sent to a personal /ai/tasks route returns 401 INVALID_API_KEY — the personal routes only accept personal keys. Always poll enterprise jobs at /ai/org-services/tasks/{taskId}. Cancel and batch-status are personal-key only.

Task statuses

A task moves through these values. Stop polling once you reach a terminal status: completed, failed, cancelled or timeout.

createdqueueddispatchingsubmittedprocessingcompletedfailedcancelledtimeout

Reading the result

When status is completed, result.assets holds the output images. Each asset has a url (a pre-signed download link that expires), a mimeType and an index; width, height, size and expiresAt appear when available. Fetch the URLs promptly — enterprise keys can re-request fresh links from the /outputs endpoint.

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"

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

Idempotency

Idempotency lets you safely retry a submission after a network error without creating a duplicate job or being charged twice.

Enterprise keys

Send an optional Idempotency-Key header (a value you generate, up to 200 characters — a UUID is ideal) on /execute-async. Retrying with the same key returns the original task instead of creating a new one. The server only deduplicates; it does not generate the key for you.

Personal keys

Personal API-key requests do not currently support an idempotency key. Retry only after confirming the previous request did not create a task (poll by the taskId you received).

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

Webhooks

Instead of polling, you can have VberAI POST the result to your server when a task reaches a terminal status.

Configuring a webhook

Pass a public HTTPS webhookUrl (and an optional webhookSecret) when you submit the job. Enterprise keys read these from the top level of the body; personal keys read them from options.

Verifying the signature

If you set a webhookSecret, each delivery includes an X-Webhook-Signature header — an HMAC-SHA256 of the raw JSON payload, hex-encoded. Recompute it with your secret and compare before trusting the payload. Deliveries also carry an X-Idempotency-Key (taskId + status) so you can ignore duplicates.

Failed deliveries are retried a few times with backoff. Respond with 2xx to acknowledge.
json
{
  "input": { "imageUrl": "https://example.com/photo.png" },
  "webhookUrl": "https://your-server.com/hook",
  "webhookSecret": "whsec_your_secret"
}

Verify a webhook (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 & billing

AI jobs cost credits. The same pricing applies to personal and enterprise keys — only the wallet differs: personal keys draw on your personal credits, enterprise keys on your organization's pool.

Reserve, settle, refund

Credits are reserved when a job is accepted and settled to the exact amount when it completes. If a job fails or is cancelled, the reservation is refunded in full — you are never charged for a failed job.

How cost is calculated

Cost depends on the service. Some services charge a flat amount per request; others scale with output resolution (per-pixel) or by the longest edge. Call the cost endpoint to preview the exact charge before you run a job.

  • •Per request — a fixed amount each call.
  • •Per pixel — scales with output width × height.
  • •By dimension — priced by the longest edge of the output.
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
  }
}

Rate limits

Rate limiting differs by key type. Both are configured per service in the backend — the values below describe the mechanism, not fixed numbers.

Personal keys — request rate

Personal keys are limited by requests per minute and per day, configured per service. Each response carries the headers below so you can pace your calls.

HeaderDescription
X-RateLimit-Limit-MinuteRequests allowed per minute.
X-RateLimit-Remaining-MinuteRequests remaining in the current minute window.
X-RateLimit-Limit-DayRequests allowed per day.
X-RateLimit-Remaining-DayRequests remaining in the current day window.
There is no X-RateLimit-Reset header. On a 429, the response body includes retryAfter and resetIn.

Enterprise keys — concurrency

Enterprise keys are not limited by request rate but by how many jobs may run concurrently for your organization. The limit is custom per organization (and may be unlimited); exceeding it returns 429 CONCURRENCY_LIMIT_EXCEEDED. Enterprise responses do not carry X-RateLimit headers.

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

Errors

Every response includes success, message and timestamp. On failure, an error code identifies the problem. Switch on the code, not the message text — messages may change and are English-only.

Where the code lives

Enterprise errors are consistent: authentication problems put the code in data.code, while service and billing problems put it in the top-level errorCode. Personal errors vary by endpoint (top-level errorCode, data.code, or errors.code) — read the field noted for each code.

HTTP status codes

StatusMeaning
200Success — result returned inline.
202Accepted — an async task was created; poll or await the webhook.
400Bad request — invalid input, or the wrong endpoint for the service's execution mode.
401Unauthorized — missing, malformed, or wrong-type API key.
402Payment required — not enough credits.
403Forbidden — the key or account may not use this service.
404Not found — unknown task, or a task that isn't yours.
429Too many requests — rate or concurrency limit exceeded.
500Server error — try again; the job (if any) is refunded.

Common error codes

CodeLocationMeaning
INSUFFICIENT_CREDITSerrorCodeNot enough personal credits for the job.
INSUFFICIENT_ORG_CREDITSerrorCodeNot enough organization credits for the job.
ORG_API_KEY_REQUIREDdata.codeThis endpoint needs an enterprise API key (X-API-Key).
INVALID_ORG_API_KEYdata.codeThe enterprise key is missing, malformed, or revoked.
INVALID_API_KEYdata.codeThe API key format is invalid — often a personal route called with an enterprise key (or vice versa).
API_SERVICE_NOT_ALLOWEDerrorCodeYour organization is not approved for this service.
ORG_DISABLEDdata.codeThe organization account is disabled.
CONCURRENCY_LIMIT_EXCEEDEDerrorCodeToo many concurrent jobs for your organization.
SERVICE_NOT_EXTERNALLY_ACCESSIBLEerrorCodeThis service is not available over the external API.
TASK_NOT_FOUNDerrorCodeNo such task for this key.
json
{
  "success": false,
  "errorCode": "INSUFFICIENT_ORG_CREDITS",
  "message": "Insufficient organization credits",
  "timestamp": "2026-01-15T10:30:00.000Z"
}

API Docs

Concrete request and response details per service. The examples show both key types — pick the tab for the key you have. For the concepts they rely on (polling, statuses, errors, billing), see the guides above.

Available services

The two services below are documented in full. For the complete, live list of services your key can call — and each service's parameter spec — query the catalog endpoints. This is the authoritative source, since availability depends on your plan and organization approvals.

EndpointDescription
GET /ai/servicesList the services your key can access.
GET /ai/external/services/{code}/specFetch the parameter spec for one service.
bash
curl https://api.vberai.com/api/ai/services \
  -H "X-API-Key: YOUR_API_KEY"