VberAI 开发者 API
VberAI 提供 RESTful HTTP API,把 AI 超强抠图等能力嵌入到你的应用、游戏与自动化流程。使用 API Key + 签名鉴权,统一错误码,按积分按次计费。
VberAI 提供 RESTful HTTP API,把 AI 超强抠图等能力嵌入到你的应用、游戏与自动化流程。使用 API Key + 签名鉴权,统一错误码,按积分按次计费。
通过 HTTP 直接调用 VberAI 的 AI 能力——生成图片、去除背景、运行各类 AI 管线,支持个人与企业 API 密钥。
VberAI API 把驱动 studio 的 AI 管线——去背景、超级抠图、图片生成等——以简单的 HTTP 端点开放出来。用 API 密钥鉴权、提交任务,然后轮询取回结果或经 webhook 接收。
统一请求形状
每个服务都接收 { input } 请求体,返回一个可轮询或经 webhook 接收的任务。
两类密钥
个人密钥面向单个开发者,企业密钥面向组织的服务器到服务器调用。
可预期的计费
提交时预扣积分、成功时按实结算;失败任务自动全额退款。
# 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"每个请求都通过 X-API-Key 头携带 API 密钥鉴权。密钥分两类,各走不同路由——为你的密钥类型选错路由,是导致 401 最常见的原因。
个人密钥 —— 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 |
| 获取方式 | 自助创建,账号设置 | 组织管理员,企业门户 |
| 扣费对象 | 个人积分 | 组织积分 |
| 限制 | 每分钟 / 每日请求数限制 | 按组织的并发数(定制) |
X-API-Key: vber_sk_... # personal key
X-API-Key: vber_org_sk_... # enterprise key基础 URL
https://api.vberai.com/api每个服务都接收一个 JSON 请求体,其中 input 对象承载该服务的参数。如何取回结果,取决于服务的执行模式。
同步服务
快速服务(如对话、文本翻译)在同一响应中以 HTTP 200 内联返回结果,无需轮询。
异步服务
较重的服务(图片生成、抠图、去背景)返回 HTTP 202 与一个 taskId。任务完成后轮询任务或经 webhook 接收结果。
个人密钥
企业密钥
{
"input": {
"imageUrl": "https://example.com/photo.png"
},
"webhookUrl": "https://your-server.com/hook"
}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 路由
任务会在这些状态间流转。一旦进入终态即停止轮询:completed、failed、cancelled 或 timeout。
当状态为 completed 时,result.assets 承载输出图片。每个 asset 含 url(预签名下载链接,会过期)、mimeType 与 index;width、height、size、expiresAt 在可得时才有。请及时获取 URL——企业密钥可从 /outputs 端点重新申请新鲜链接。
# 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"已完成的任务
{
"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 轮询)再重试。
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000除了轮询,你也可以让 VberAI 在任务进入终态时把结果 POST 到你的服务器。
提交任务时传入一个公网 HTTPS 的 webhookUrl(以及可选的 webhookSecret)。企业密钥从请求体顶层读取这两个字段;个人密钥从 options 中读取。
若设置了 webhookSecret,每次投递都带一个 X-Webhook-Signature 头——对原始 JSON 负载做 HMAC-SHA256 并十六进制编码。用你的 secret 重新计算并比对,通过后再信任负载。投递还带 X-Idempotency-Key(taskId + status),便于忽略重复。
{
"input": { "imageUrl": "https://example.com/photo.png" },
"webhookUrl": "https://your-server.com/hook",
"webhookSecret": "whsec_your_secret"
}校验 webhook(Node.js)
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 端点预览精确费用。
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}}'{
"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 | 当前日窗口内剩余的请求数。 |
企业密钥不按请求速率限制,而是按组织可同时运行的任务数限制。该上限按组织定制(可为不限);超出返回 429 CONCURRENCY_LIMIT_EXCEEDED。企业响应不带 X-RateLimit 头。
X-RateLimit-Limit-Minute: 60
X-RateLimit-Remaining-Minute: 59
X-RateLimit-Limit-Day: 2000
X-RateLimit-Remaining-Day: 1997每个响应都含 success、message 与 timestamp。失败时由错误码标识问题。请按错误码而非文案分支——文案可能变动且仅英文。
错误码的位置
| 状态码 | 含义 |
|---|---|
| 200 | 成功——结果内联返回。 |
| 202 | 已接受——已创建异步任务;请轮询或等待 webhook。 |
| 400 | 请求错误——输入无效,或对该服务执行模式用错了端点。 |
| 401 | 未授权——API 密钥缺失、格式错误或类型不对。 |
| 402 | 需付费——积分不足。 |
| 403 | 禁止——该密钥或账号无权使用此服务。 |
| 404 | 未找到——任务不存在,或不属于你。 |
| 429 | 请求过多——超出速率或并发上限。 |
| 500 | 服务器错误——请重试;任务(若有)会退款。 |
| 错误码 | 位置 | 含义 |
|---|---|---|
INSUFFICIENT_CREDITS | errorCode | 个人积分不足以运行该任务。 |
INSUFFICIENT_ORG_CREDITS | errorCode | 组织积分不足以运行该任务。 |
ORG_API_KEY_REQUIRED | data.code | 该端点需要企业 API 密钥(X-API-Key)。 |
INVALID_ORG_API_KEY | data.code | 企业密钥缺失、格式错误或已吊销。 |
INVALID_API_KEY | data.code | API 密钥格式无效——通常是用企业密钥调了个人路由(或反之)。 |
API_SERVICE_NOT_ALLOWED | errorCode | 你的组织未获批使用此服务。 |
ORG_DISABLED | data.code | 组织账号已被停用。 |
CONCURRENCY_LIMIT_EXCEEDED | errorCode | 组织的并发任务数过多。 |
SERVICE_NOT_EXTERNALLY_ACCESSIBLE | errorCode | 该服务不对外部 API 开放。 |
TASK_NOT_FOUND | errorCode | 该密钥下不存在此任务。 |
{
"success": false,
"errorCode": "INSUFFICIENT_ORG_CREDITS",
"message": "Insufficient organization credits",
"timestamp": "2026-01-15T10:30:00.000Z"
}各服务的具体请求与响应细节。示例同时给出两类密钥——选择你所持密钥对应的标签。至于它们依赖的概念(轮询、状态、错误、计费),见上方指南。
下面两个服务有完整文档。你的密钥可调用的完整实时服务清单——以及每个服务的参数规格——请查询目录端点。这是权威来源,因为可用性取决于你的计划与组织获批情况。
| 端点 | 说明 |
|---|---|
GET /ai/services | 列出你的密钥可访问的服务。 |
GET /ai/external/services/{code}/spec | 获取某个服务的参数规格。 |
curl https://api.vberai.com/api/ai/services \
-H "X-API-Key: YOUR_API_KEY"