VberAI 开发者 API

VberAI 提供 RESTful HTTP API,把 AI 超强抠图等能力嵌入到你的应用、游戏与自动化流程。使用 API Key + 签名鉴权,统一错误码,按积分按次计费。

API v1
稳定版

API 文档

通过 HTTP 直接调用 VberAI 的 AI 能力——生成图片、去除背景、运行各类 AI 管线,支持个人与企业 API 密钥。

超级抠图

super-matting

高质量抠图,把主体从背景中分离,返回干净的抠图结果。异步服务——提交后轮询或等待 webhook。

价格

按输出最长边分档计价(例如 512 px 为 2 积分,1024 px 为 10)。运行前请调用 /cost 端点获取精确金额。

参数

参数类型必填说明
source_typestring是取 "url"(input_value 为公网 http(s) 图片 URL)或 "base64"(input_value 为 base64 字符串或 data: URL)之一。
input_valuestring是源图片:source_type 为 "url" 时填 http(s) URL,为 "base64" 时填 base64 图片数据。
widthnumber是目标宽度(像素,64–2048)。
heightnumber是目标高度(像素,64–2048)。
seednumber否可选。固定整数种子以复现输出;省略时随机。

轮询与结果

异步任务返回一个 taskId。轮询任务直到状态进入终态,再读取结果。轮询哪条路由取决于你的密钥类型——这一点最关键,务必用对。

操作个人密钥企业密钥
轮询任务状态GET /ai/tasks/{taskId}GET /ai/org-services/tasks/{taskId}
重新签发新鲜下载 URL从状态响应中读取GET /ai/org-services/tasks/{taskId}/outputs

企业密钥必须轮询 /ai/org-services 路由

企业密钥(vber_org_sk_)发到个人 /ai/tasks 路由会返回 401 INVALID_API_KEY——个人路由只接受个人密钥。企业任务请始终在 /ai/org-services/tasks/{taskId} 轮询。取消与批量状态查询仅个人密钥可用。

任务会在这些状态间流转。一旦进入终态即停止轮询:completed、failed、cancelled 或 timeout。

createdqueueddispatchingsubmittedprocessingcompletedfailedcancelledtimeout

当状态为 completed 时,result.assets 承载输出图片。每个 asset 含 url(预签名下载链接,会过期)、mimeType 与 index;width、height、size、expiresAt 在可得时才有。请及时获取 URL——企业密钥可从 /outputs 端点重新申请新鲜链接。

完成后 result.assets 承载抠图输出图片。

已完成的任务

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

Webhook

提交任务时传入一个公网 HTTPS 的 webhookUrl(以及可选的 webhookSecret)。企业密钥从请求体顶层读取这两个字段;个人密钥从 options 中读取。

若设置了 webhookSecret,每次投递都带一个 X-Webhook-Signature 头——对原始 JSON 负载做 HMAC-SHA256 并十六进制编码。用你的 secret 重新计算并比对,通过后再信任负载。投递还带 X-Idempotency-Key(taskId + status),便于忽略重复。

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"