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

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

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

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

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

Super Matting

super-matting

Высококачественная вырезка, которая отделяет объект от фона и возвращает чистый результат matting. Асинхронный — отправьте, затем опрашивайте или ждите webhook.

Цены

Цена определяется самой длинной выходной стороной (уровни по размеру — например, 512 px это 2 кредита, 1024 px это 10). Вызовите эндпоинт /cost, чтобы узнать точную сумму, прежде чем запускать задачу.

Параметры

ПараметрТипОбязательныйОписание
source_typestringДаОдно из "url" (input_value — публичный http(s) image URL) или "base64" (input_value — строка base64 или data: URL).
input_valuestringДаИсходное изображение: http(s) URL, когда source_type равен "url", или данные изображения base64, когда source_type равен "base64".
widthnumberДаЦелевая ширина в пикселях (64–2048).
heightnumberДаЦелевая высота в пикселях (64–2048).
seednumberНетНеобязательный. Фиксированный целочисленный seed для воспроизводимого вывода; при отсутствии используется случайный seed.

Опрос и результаты

Асинхронные задачи возвращают 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.

При completed result.assets содержит выходное(ые) изображение(я) matting.

Завершённая задача

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 — HMAC-SHA256 сырого JSON-payload в шестнадцатеричном представлении. Пересчитайте его с вашим секретом и сравните, прежде чем доверять payload. Доставки также несут 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"