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 DocsSuper Matting

Super Matting

super-matting

High-quality cutout that separates a subject from its background and returns a clean matting result. Asynchronous — submit, then poll or await a webhook.

Pricing

Priced by the longest output edge (dimension tiers — e.g. 512 px is 2 credits, 1024 px is 10). Call the /cost endpoint for the exact amount before running a job.

Parameters

ParameterTypeRequiredDescription
source_typestringYesOne of "url" (input_value is a public http(s) image URL) or "base64" (input_value is a base64 string or data: URL).
input_valuestringYesThe source image: an http(s) URL when source_type is "url", or base64 image data when source_type is "base64".
widthnumberYesTarget width in pixels (64–2048).
heightnumberYesTarget height in pixels (64–2048).
seednumberNoOptional. Fixed integer seed for reproducible output; a random seed is used when omitted.

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 matting output image(s).

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

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/super-matting/execute
bash
curl -X POST https://api.vberai.com/api/ai/services/super-matting/execute \
  -H "X-API-Key: vber_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "source_type": "url",
      "input_value": "https://example.com/photo.png",
      "width": 1024,
      "height": 768
    }
  }'
bash
curl https://api.vberai.com/api/ai/tasks/{taskId} \
  -H "X-API-Key: vber_sk_YOUR_KEY"