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.
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
1Authenticate with your API key in the X-API-Key header.
2Submit a job to a service with a JSON { input } body.
3Read the result inline (sync services) or poll the task / receive a webhook (async services).
bash
# 1. Submit a jobcurl-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.
Aspect
Personal key
Enterprise key
Key prefix
vber_sk_
vber_org_sk_
Route prefix
/ai/services, /ai/tasks
/ai/org-services
How to obtain
Self-service, account settings
Org admin, enterprise portal
Billed to
Personal credits
Organization credits
Limits
Per-minute / per-day request limits
Per-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.
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
Action
Personal key
Enterprise key
Poll task status
GET /ai/tasks/{taskId}
GET /ai/org-services/tasks/{taskId}
Re-sign fresh download URLs
Read from the status response
GET /ai/org-services/tasks/{taskId}/outputs
Cancel a task
POST /ai/tasks/{taskId}/cancel
Not available
Batch status
GET /ai/tasks/batch-status
Not 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.
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.
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).
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.
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.
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.
Header
Description
X-RateLimit-Limit-Minute
Requests allowed per minute.
X-RateLimit-Remaining-Minute
Requests remaining in the current minute window.
X-RateLimit-Limit-Day
Requests allowed per day.
X-RateLimit-Remaining-Day
Requests 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.
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
Status
Meaning
200
Success — result returned inline.
202
Accepted — an async task was created; poll or await the webhook.
400
Bad request — invalid input, or the wrong endpoint for the service's execution mode.
401
Unauthorized — missing, malformed, or wrong-type API key.
402
Payment required — not enough credits.
403
Forbidden — the key or account may not use this service.
404
Not found — unknown task, or a task that isn't yours.
429
Too many requests — rate or concurrency limit exceeded.
500
Server error — try again; the job (if any) is refunded.
Common error codes
Code
Location
Meaning
INSUFFICIENT_CREDITS
errorCode
Not enough personal credits for the job.
INSUFFICIENT_ORG_CREDITS
errorCode
Not enough organization credits for the job.
ORG_API_KEY_REQUIRED
data.code
This endpoint needs an enterprise API key (X-API-Key).
INVALID_ORG_API_KEY
data.code
The enterprise key is missing, malformed, or revoked.
INVALID_API_KEY
data.code
The API key format is invalid — often a personal route called with an enterprise key (or vice versa).
API_SERVICE_NOT_ALLOWED
errorCode
Your organization is not approved for this service.
ORG_DISABLED
data.code
The organization account is disabled.
CONCURRENCY_LIMIT_EXCEEDED
errorCode
Too many concurrent jobs for your organization.
SERVICE_NOT_EXTERNALLY_ACCESSIBLE
errorCode
This service is not available over the external API.
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.
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.