API для разработчиков VberAI

VberAI предоставляет REST HTTP API, чтобы встраивать AI-возможности (сегодня — AI Super Matting) в приложения, игры и пайплайны. Аутентификация по ключу + подписи, единые коды ошибок, оплата по кредитам.

API v1
Стабильная версия

Документация API

Генерируйте изображения, удаляйте фон и запускайте AI-конвейеры VberAI прямо по HTTP — с личными или корпоративными API-ключами.

Введение

API VberAI открывает те же AI-конвейеры, что работают в studio — удаление фона, super matting, генерацию изображений и другое — в виде простых HTTP-эндпоинтов. Аутентифицируйтесь с помощью API-ключа, отправьте задачу и прочитайте результат обратно или получите его по webhook.

Единая форма запроса

Каждый сервис принимает тело { input } и возвращает задачу, которую можно опрашивать или получить по webhook.

Два типа ключей

Личные ключи для отдельных разработчиков, корпоративные ключи для взаимодействия server-to-server на уровне организации.

Предсказуемая оплата

Кредиты резервируются при отправке и списываются при успехе; неудавшиеся задачи возвращаются автоматически.

Как это работает

  1. 1Аутентифицируйтесь с помощью вашего API-ключа в заголовке X-API-Key.
  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-ключи

Каждый запрос аутентифицируется с помощью API-ключа, отправляемого в заголовке X-API-Key. Существует два вида ключей, и они используют разные маршруты — выбор неверного маршрута для вашего типа ключа является самой частой причиной ошибки 401.

Относитесь к API-ключам как к паролям. Отправляйте их только с вашего бэкенда, меняйте при утечке и ограничивайте корпоративные ключи лимитом расходов.

Личные ключи — 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
Как получитьСамостоятельно, настройки аккаунтаАдминистратор организации, корпоративный портал
Оплачивается изЛичные кредитыКредиты организации
ОграниченияЛимиты запросов в минуту / в деньПараллелизм на организацию (настраиваемый)
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. Опрос не нужен.

Асинхронные сервисы

Более тяжёлые сервисы (генерация изображений, matting, удаление фона) возвращают 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"
  }
}

Идемпотентность

Идемпотентность позволяет безопасно повторить отправку после сетевой ошибки, не создавая дублирующую задачу и не подвергаясь двойному списанию.

Корпоративные ключи

Отправляйте необязательный заголовок Idempotency-Key (значение, которое вы генерируете, до 200 символов — идеально подходит UUID) на /execute-async. Повтор с тем же ключом возвращает исходную задачу вместо создания новой. Сервер только устраняет дубликаты; он не генерирует ключ за вас.

Личные ключи

Запросы с личным API-ключом сейчас не поддерживают ключ идемпотентности. Повторяйте только после подтверждения, что предыдущий запрос не создал задачу (опросив по полученному taskId).

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

Webhook

Вместо опроса вы можете позволить VberAI отправлять результат POST-запросом на ваш сервер, когда задача достигает терминального статуса.

Настройка webhook

Передайте публичный HTTPS webhookUrl (и необязательный webhookSecret) при отправке задачи. Корпоративные ключи читают их из верхнего уровня тела; личные ключи читают их из options.

Проверка подписи

Если вы задали webhookSecret, каждая доставка включает заголовок X-Webhook-Signature — HMAC-SHA256 сырого JSON-payload в шестнадцатеричном представлении. Пересчитайте его с вашим секретом и сравните, прежде чем доверять payload. Доставки также несут 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. При неудаче код ошибки идентифицирует проблему. Ветвитесь по коду, а не по тексту message — сообщения могут меняться и доступны только на английском.

Где находится код

Корпоративные ошибки единообразны: проблемы аутентификации помещают код в 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.codeФормат API-ключа недопустим — часто это личный маршрут, вызванный корпоративным ключом (или наоборот).
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

Конкретные детали запроса и ответа для каждого сервиса. Примеры показывают оба типа ключей — выберите вкладку для того ключа, что у вас есть. Про концепции, на которые они опираются (опрос, статусы, ошибки, оплата), см. руководства выше.

Доступные сервисы

Два сервиса ниже задокументированы полностью. За полным, актуальным списком сервисов, которые может вызывать ваш ключ — и спецификацией параметров каждого сервиса — обращайтесь к эндпоинтам каталога. Это авторитетный источник, поскольку доступность зависит от вашего плана и одобрений организации.

EndpointОписание
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"