API для разработчиков VberAI
VberAI предоставляет REST HTTP API, чтобы встраивать AI-возможности (сегодня — AI Super Matting) в приложения, игры и пайплайны. Аутентификация по ключу + подписи, единые коды ошибок, оплата по кредитам.
VberAI предоставляет REST HTTP API, чтобы встраивать AI-возможности (сегодня — AI Super Matting) в приложения, игры и пайплайны. Аутентификация по ключу + подписи, единые коды ошибок, оплата по кредитам.
Генерируйте изображения, удаляйте фон и запускайте AI-конвейеры VberAI прямо по HTTP — с личными или корпоративными API-ключами.
API VberAI открывает те же AI-конвейеры, что работают в studio — удаление фона, super matting, генерацию изображений и другое — в виде простых HTTP-эндпоинтов. Аутентифицируйтесь с помощью API-ключа, отправьте задачу и прочитайте результат обратно или получите его по webhook.
Единая форма запроса
Каждый сервис принимает тело { input } и возвращает задачу, которую можно опрашивать или получить по webhook.
Два типа ключей
Личные ключи для отдельных разработчиков, корпоративные ключи для взаимодействия server-to-server на уровне организации.
Предсказуемая оплата
Кредиты резервируются при отправке и списываются при успехе; неудавшиеся задачи возвращаются автоматически.
# 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. Существует два вида ключей, и они используют разные маршруты — выбор неверного маршрута для вашего типа ключа является самой частой причиной ошибки 401.
Личные ключи — vber_sk_
Для отдельных разработчиков. Создаются самостоятельно на странице API-ключей вашего аккаунта (требуется план с доступом к API). Оплачиваются из ваших личных кредитов. Используйте маршруты /ai/services и /ai/tasks.
Корпоративные ключи — vber_org_sk_
Для взаимодействия server-to-server от имени организации. Выпускаются администратором организации в корпоративном портале и ограничены сервисами, для которых ваша организация одобрена. Оплачиваются из кредитного пула вашей организации. Используйте маршруты /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. Опрос не нужен.
Асинхронные сервисы
Более тяжёлые сервисы (генерация изображений, matting, удаление фона) возвращают 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"
}
}Идемпотентность позволяет безопасно повторить отправку после сетевой ошибки, не создавая дублирующую задачу и не подвергаясь двойному списанию.
Корпоративные ключи
Отправляйте необязательный заголовок Idempotency-Key (значение, которое вы генерируете, до 200 символов — идеально подходит UUID) на /execute-async. Повтор с тем же ключом возвращает исходную задачу вместо создания новой. Сервер только устраняет дубликаты; он не генерирует ключ за вас.
Личные ключи
Запросы с личным API-ключом сейчас не поддерживают ключ идемпотентности. Повторяйте только после подтверждения, что предыдущий запрос не создал задачу (опросив по полученному taskId).
Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000Вместо опроса вы можете позволить VberAI отправлять результат POST-запросом на ваш сервер, когда задача достигает терминального статуса.
Передайте публичный HTTPS webhookUrl (и необязательный webhookSecret) при отправке задачи. Корпоративные ключи читают их из верхнего уровня тела; личные ключи читают их из options.
Если вы задали webhookSecret, каждая доставка включает заголовок X-Webhook-Signature — HMAC-SHA256 сырого JSON-payload в шестнадцатеричном представлении. Пересчитайте его с вашим секретом и сравните, прежде чем доверять payload. Доставки также несут 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. При неудаче код ошибки идентифицирует проблему. Ветвитесь по коду, а не по тексту message — сообщения могут меняться и доступны только на английском.
Где находится код
| Статус | Значение |
|---|---|
| 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"
}Конкретные детали запроса и ответа для каждого сервиса. Примеры показывают оба типа ключей — выберите вкладку для того ключа, что у вас есть. Про концепции, на которые они опираются (опрос, статусы, ошибки, оплата), см. руководства выше.
ai-video-genSuper Mattingsuper-mattingУдаление фонаai-image-bg-removeРазбор на слоиai-layer-splitДва сервиса ниже задокументированы полностью. За полным, актуальным списком сервисов, которые может вызывать ваш ключ — и спецификацией параметров каждого сервиса — обращайтесь к эндпоинтам каталога. Это авторитетный источник, поскольку доступность зависит от вашего плана и одобрений организации.
| Endpoint | Описание |
|---|---|
GET /ai/services | Перечислить сервисы, к которым имеет доступ ваш ключ. |
GET /ai/external/services/{code}/spec | Получить спецификацию параметров для одного сервиса. |
curl https://api.vberai.com/api/ai/services \
-H "X-API-Key: YOUR_API_KEY"