VberAI 开发者 API

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

API v1
稳定版

API 文档

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

简介

VberAI API 把驱动 studio 的 AI 管线——去背景、超级抠图、图片生成等——以简单的 HTTP 端点开放出来。用 API 密钥鉴权、提交任务,然后轮询取回结果或经 webhook 接收。

统一请求形状

每个服务都接收 { input } 请求体,返回一个可轮询或经 webhook 接收的任务。

两类密钥

个人密钥面向单个开发者,企业密钥面向组织的服务器到服务器调用。

可预期的计费

提交时预扣积分、成功时按实结算;失败任务自动全额退款。

工作原理

  1. 1在 X-API-Key 头中携带你的 API 密钥进行鉴权。
  2. 2以 JSON { input } 请求体向某个服务提交任务。
  3. 3同步服务内联返回结果;异步服务则轮询任务或经 webhook 接收。
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"

鉴权与 API 密钥

每个请求都通过 X-API-Key 头携带 API 密钥鉴权。密钥分两类,各走不同路由——为你的密钥类型选错路由,是导致 401 最常见的原因。

把 API 密钥当作密码。只从你的后端发送,泄漏后立即轮换,并给企业密钥设置消费上限。

个人密钥 —— vber_sk_

面向单个开发者。在账号的 API 密钥页自助创建(需订阅计划开启 API 访问)。从个人积分扣费。使用 /ai/services 与 /ai/tasks 路由。

企业密钥 —— vber_org_sk_

面向组织的服务器到服务器调用。由组织管理员在企业门户签发,且仅限组织已获批的服务。从组织积分池扣费。使用 /ai/org-services 路由。

对比项个人密钥企业密钥
密钥前缀vber_sk_vber_org_sk_
路由前缀/ai/services, /ai/tasks/ai/org-services
获取方式自助创建,账号设置组织管理员,企业门户
扣费对象个人积分组织积分
限制每分钟 / 每日请求数限制按组织的并发数(定制)
http
X-API-Key: vber_sk_...        # personal key
X-API-Key: vber_org_sk_...    # enterprise key

基础 URL

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

请求与执行模式

每个服务都接收一个 JSON 请求体,其中 input 对象承载该服务的参数。如何取回结果,取决于服务的执行模式。

同步服务

快速服务(如对话、文本翻译)在同一响应中以 HTTP 200 内联返回结果,无需轮询。

异步服务

较重的服务(图片生成、抠图、去背景)返回 HTTP 202 与一个 taskId。任务完成后轮询任务或经 webhook 接收结果。

个人密钥

个人密钥每个服务只用一个端点:POST /ai/services/{code}/execute。同步服务内联返回结果(200),异步服务返回任务(202)——同一个端点即可。

企业密钥

企业密钥用两个端点:同步服务走 /execute,异步服务走 /execute-async。调错端点会返回 400 并告知应使用哪个端点。
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" }

轮询与结果

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

该轮询哪条路由

操作个人密钥企业密钥
轮询任务状态GET /ai/tasks/{taskId}GET /ai/org-services/tasks/{taskId}
重新签发新鲜下载 URL从状态响应中读取GET /ai/org-services/tasks/{taskId}/outputs
取消任务POST /ai/tasks/{taskId}/cancel不提供
批量状态GET /ai/tasks/batch-status不提供

企业密钥必须轮询 /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 端点重新申请新鲜链接。

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"

已完成的任务

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

幂等

幂等让你在网络错误后可以安全重试提交,而不会创建重复任务或被重复扣费。

企业密钥

在 /execute-async 上可选携带 Idempotency-Key 头(由你生成、至多 200 字符,建议用 UUID)。用相同的键重试会返回原任务,而非新建任务。服务端只做去重,不替你生成该键。

个人密钥

个人 API 密钥请求目前不支持幂等键。请在确认上一个请求未创建任务后(用你收到的 taskId 轮询)再重试。

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

Webhook

除了轮询,你也可以让 VberAI 在任务进入终态时把结果 POST 到你的服务器。

配置 Webhook

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

校验签名

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

投递失败会带退避重试若干次。请以 2xx 响应确认接收。
json
{
  "input": { "imageUrl": "https://example.com/photo.png" },
  "webhookUrl": "https://your-server.com/hook",
  "webhookSecret": "whsec_your_secret"
}

校验 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();
});

积分与计费

AI 任务消耗积分。个人与企业密钥采用同一套计价——只是钱包不同:个人密钥扣个人积分,企业密钥扣组织积分池。

预扣、结算、退款

任务被接受时预扣积分,完成时按精确金额结算。任务失败或取消时,预扣全额退回——失败任务绝不扣费。

费用如何计算

费用取决于服务。有的按次固定收费;有的随输出分辨率(按像素)或按最长边缩放。运行任务前可调用 cost 端点预览精确费用。

  • •按次——每次调用固定金额。
  • •按像素——随输出 宽×高 缩放。
  • •按尺寸——以输出的最长边计价。
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
  }
}

限流

限流方式因密钥类型而异。两者都在后台按服务配置——下文描述的是机制,而非固定数值。

个人密钥 —— 请求速率

个人密钥按每分钟、每日请求数限流,按服务配置。每个响应都带下列头,便于你控制调用节奏。

响应头说明
X-RateLimit-Limit-Minute每分钟允许的请求数。
X-RateLimit-Remaining-Minute当前分钟窗口内剩余的请求数。
X-RateLimit-Limit-Day每日允许的请求数。
X-RateLimit-Remaining-Day当前日窗口内剩余的请求数。
没有 X-RateLimit-Reset 头。触发 429 时,响应体包含 retryAfter 与 resetIn。

企业密钥 —— 并发

企业密钥不按请求速率限制,而是按组织可同时运行的任务数限制。该上限按组织定制(可为不限);超出返回 429 CONCURRENCY_LIMIT_EXCEEDED。企业响应不带 X-RateLimit 头。

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

错误

每个响应都含 success、message 与 timestamp。失败时由错误码标识问题。请按错误码而非文案分支——文案可能变动且仅英文。

错误码的位置

企业错误规整:鉴权问题的码在 data.code,服务与计费问题的码在顶层 errorCode。个人错误因端点而异(顶层 errorCode、data.code 或 errors.code)——请按每个码标注的字段读取。

HTTP 状态码

状态码含义
200成功——结果内联返回。
202已接受——已创建异步任务;请轮询或等待 webhook。
400请求错误——输入无效,或对该服务执行模式用错了端点。
401未授权——API 密钥缺失、格式错误或类型不对。
402需付费——积分不足。
403禁止——该密钥或账号无权使用此服务。
404未找到——任务不存在,或不属于你。
429请求过多——超出速率或并发上限。
500服务器错误——请重试;任务(若有)会退款。

常见错误码

错误码位置含义
INSUFFICIENT_CREDITSerrorCode个人积分不足以运行该任务。
INSUFFICIENT_ORG_CREDITSerrorCode组织积分不足以运行该任务。
ORG_API_KEY_REQUIREDdata.code该端点需要企业 API 密钥(X-API-Key)。
INVALID_ORG_API_KEYdata.code企业密钥缺失、格式错误或已吊销。
INVALID_API_KEYdata.codeAPI 密钥格式无效——通常是用企业密钥调了个人路由(或反之)。
API_SERVICE_NOT_ALLOWEDerrorCode你的组织未获批使用此服务。
ORG_DISABLEDdata.code组织账号已被停用。
CONCURRENCY_LIMIT_EXCEEDEDerrorCode组织的并发任务数过多。
SERVICE_NOT_EXTERNALLY_ACCESSIBLEerrorCode该服务不对外部 API 开放。
TASK_NOT_FOUNDerrorCode该密钥下不存在此任务。
json
{
  "success": false,
  "errorCode": "INSUFFICIENT_ORG_CREDITS",
  "message": "Insufficient organization credits",
  "timestamp": "2026-01-15T10:30:00.000Z"
}

API 文档

各服务的具体请求与响应细节。示例同时给出两类密钥——选择你所持密钥对应的标签。至于它们依赖的概念(轮询、状态、错误、计费),见上方指南。

可用服务

下面两个服务有完整文档。你的密钥可调用的完整实时服务清单——以及每个服务的参数规格——请查询目录端点。这是权威来源,因为可用性取决于你的计划与组织获批情况。

端点说明
GET /ai/services列出你的密钥可访问的服务。
GET /ai/external/services/{code}/spec获取某个服务的参数规格。
bash
curl https://api.vberai.com/api/ai/services \
  -H "X-API-Key: YOUR_API_KEY"