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 DocsBackground Removal

Background Removal

ai-image-bg-remove

Remove the background from an image and return a transparent-background cutout. Asynchronous — submit, then poll or await a webhook.

Pricing

A flat charge per image. Call the /cost endpoint for the exact amount.

Parameters

ParameterTypeRequiredDescription
imageUrlstringYesPublic http(s) URL of the image to process. This is the only input the service takes — it does not accept base64 or a source_type.
widthnumberNoOptional. Only used as a billing-area fallback when the source resolution can't be detected; it does not change the output.
heightnumberNoOptional. Only used as a billing-area fallback when the source resolution can't be detected; it does not change the output.

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.

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

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.

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

createdqueueddispatchingsubmittedprocessingcompletedfailedcancelledtimeout

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.

When completed, result.assets holds the transparent-background cutout image.

Completed task

json
{
  "success": true,
  "data": {
    "taskId": "6a97e277a148c970dd545f40",
    "serviceCode": "ai-image-bg-remove",
    "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

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.

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.

POST/ai/services/ai-image-bg-remove/execute
bash
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"}}'
bash
curl https://api.vberai.com/api/ai/tasks/{taskId} \
  -H "X-API-Key: vber_sk_YOUR_KEY"