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

REST API для AI-стейджинга фотографий недвижимости. Отправляете фото — получаете профессионально обработанное изображение. Интегрируется в любую CRM за один день.

Введение

API асинхронный: вы создаёте задачу, получаете job_id, а готовый результат забираете по webhook'у или опросом. Базовый URL:

https://aistaging.ru/api/v1

Все ответы — JSON. Все запросы — по HTTPS. Биллинг: 1 кредит = 1 обработанное фото, из предоплаченного пакета (кредиты не сгорают).

Авторизация

Каждый запрос авторизуется API-ключом в заголовке Authorization. Ключи создаются в личном кабинете (раздел «API») и показываются один раз — храните в секрете, не публикуйте в клиентском коде.

Authorization: Bearer ak_live_xxxxxxxxxxxxxxxxxxxxxxxx

Быстрый старт

Отправьте фото на обработку:

curl -X POST https://aistaging.ru/api/v1/staging \
  -H "Authorization: Bearer $AGENTLENS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image_url": "https://your-crm.example/photos/room.jpg",
    "style": "classic",
    "callback_url": "https://your-crm.example/webhooks/agentlens"
  }'

# → 202
# { "job_id": "9f4b25a2-1847-14aa-eb5d-d72a1343db20", "status": "pending" }

Через ~1 минуту заберите результат (опросом или по webhook'у):

curl https://aistaging.ru/api/v1/staging/9f4b25a2-1847-14aa-eb5d-d72a1343db20 \
  -H "Authorization: Bearer $AGENTLENS_KEY"

# → { "job_id": "...", "status": "completed",
#     "result_url": "https://.../full.jpg?...", "style": "classic" }

POST /v1/staging — обработать фото

Создаёт задачу обработки. Списывает 1 кредит (возвращается, если фото не удалось скачать или поставить в очередь).

Тело запроса

Ответ 202 Accepted

{ "job_id": "9f4b25a2-1847-14aa-eb5d-d72a1343db20", "status": "pending" }

GET /v1/staging/{job_id} — статус

Возвращает текущий статус. status ∈ pending · processing · completed · failed.

{
  "job_id": "9f4b25a2-1847-14aa-eb5d-d72a1343db20",
  "status": "completed",
  "style": "classic",
  "result_url": "https://home-staging-images.../full.jpg?X-Amz-...",
  "created_at": "2026-06-25T16:40:20.455Z",
  "completed_at": "2026-06-25T16:41:18.270Z"
}

result_url — прямая ссылка на результат, действует 7 дней. Скачайте файл к себе для постоянного хранения.

GET /v1/balance — баланс

curl https://aistaging.ru/api/v1/balance -H "Authorization: Bearer $AGENTLENS_KEY"
# → { "client": "Моё агентство", "credits": 9876 }

POST /api/v1/payments — создать платёж

Создаёт одноразовый платёж для пополнения баланса API-клиента и возвращает ссылку на защищённую платёжную форму ЮKassa. Плательщик подтверждает оплату через СБП — автоматического списания нет. Цена одного кредита и итоговая сумма рассчитываются на сервере для владельца API-ключа: передавать client_id или сумму платежа не нужно.

Тело запроса

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

Для каждого нового заказа передавайте уникальный заголовокIdempotency-Keyдлиной до 64 символов; рекомендуемый формат — UUID v4. Повтор запроса с тем же ключом и теми же параметрами вернёт уже созданный платёж, не создавая второй. Если параметры отличаются, API вернёт409 idempotency_conflict. Для новой попытки после отменённого платежа используйте новый ключ и, если заданexternal_reference, новый номер или суффикс попытки.

curl -X POST https://aistaging.ru/api/v1/payments \
  -H "Authorization: Bearer $AGENTLENS_KEY" \
  -H "Idempotency-Key: 4670c3c6-6d34-4e4a-817d-9fa3f71d1d8b" \
  -H "Content-Type: application/json" \
  -d '{
    "credits": 1000,
    "external_reference": "agency-42/order-1847",
    "return_url": "https://your-crm.example/billing/complete",
    "receipt_email": "payments@agency-42.example"
  }'

# → 201 Created
{
  "payment_id": "e642cc98-3c63-4a86-941f-90fc109492d0",
  "status": "pending",
  "credits": 1000,
  "amount": { "value": "6000.00", "currency": "RUB" },
  "confirmation_url": "https://yoomoney.ru/checkout/...",
  "external_reference": "agency-42/order-1847",
  "created_at": "2026-07-23T12:45:00.000Z"
}

Откройте confirmation_url в браузере плательщика. Ссылка относится только к этому платежу; не сохраняйте её в публичных логах. Новый запрос возвращает 201 Created, идемпотентный повтор — 200 OK. При неопределённом ответе платёжного провайдера API вернёт 502 и уже зарезервированныйpayment_id; в ответе GET поле confirmation_url может временно бытьnull. Безопасно повторите POST с тем же ключом идемпотентности.

GET /api/v1/payments/{payment_id} — статус платежа

Возвращает платёж только того API-клиента, которому принадлежит ключ. Неизвестный или чужойpayment_id возвращает 404. Переход пользователя на return_url не подтверждает оплату — проверяйте этот метод до терминального статуса.

curl https://aistaging.ru/api/v1/payments/e642cc98-3c63-4a86-941f-90fc109492d0 \
  -H "Authorization: Bearer $AGENTLENS_KEY"

# → 200 OK
{
  "payment_id": "e642cc98-3c63-4a86-941f-90fc109492d0",
  "status": "paid",
  "credits": 1000,
  "amount": { "value": "6000.00", "currency": "RUB" },
  "confirmation_url": "https://yoomoney.ru/checkout/...",
  "external_reference": "agency-42/order-1847",
  "created_at": "2026-07-23T12:45:00.000Z",
  "paid_at": "2026-07-23T12:46:18.270Z",
  "cancelled_at": null,
  "refunded_at": null
}

Рекомендуемый интервал опроса — 3–5 секунд до paid, cancelled илиrefunded. После paid актуальный общий остаток можно получить черезGET /v1/balance. Поля paid_at, cancelled_at и refunded_atзаполняются при соответствующем терминальном статусе.

Сценарий для CRM с несколькими агентствами

1. Создайте заказ в своей базе и привяжите его к агентству. Передайте этот номер в external_reference, а уникальный UUID заказа — в Idempotency-Key.
2. Вызовите POST /api/v1/payments с backend-сервера CRM, сохраните полученный payment_id и перенаправьте плательщика на confirmation_url.
3. После возврата в CRM опрашивайте GET /api/v1/payments/{payment_id}. Не доверяйте только открытию return_url.
4. При статусе paid начислите внутренние токены нужному агентству ровно один раз. Используйте payment_id как уникальный ключ операции в своём журнале.
5. Кредиты Agent Lens зачисляются на единый API-баланс владельца ключа. Распределение собственных токенов между агентствами и их остатки ведёт ваша CRM.

Стили обработки

Webhooks

Если задан callback_url, мы отправим POST на него при завершении задачи:

POST {callback_url}
X-Signature: <hmac_sha256_hex>
Content-Type: application/json

{ "job_id": "9f4b...", "status": "completed",
  "result_url": "https://.../full.jpg?...", "timestamp": 1782405481479 }

Проверяйте подпись X-Signature = HMAC-SHA256(тело, ваш webhook secret):

// Node.js
import { createHmac, timingSafeEqual } from 'node:crypto'
function verify(rawBody, signature, secret) {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex')
  return timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
}

Webhook — best-effort. Надёжный канал — опрос GET /v1/staging/{job_id} (рекомендуем опрашивать раз в 5–10 сек до completed/failed).

Ошибки

Лимиты и биллинг

• 1 кредит = 1 обработанное фото. Списывается при создании задачи, возвращается при ошибке скачивания/постановки в очередь или провале обработки.
• Кредиты предоплаченные и не сгорают. Пополнение — в кабинете или через API по СБП, либо по счёту на юрлицо.
• Время обработки — обычно 40–90 секунд на фото.
• Если результат провалился у всех AI-провайдеров — задача становится failed, кредит возвращается.