API OCR счетчиков воды

API OCR счетчиков воды. На этой странице документируются общедоступные HTTP API, предоставляемые серверной частью веб-сайта для сторонней интеграции.

Начните с реальной загрузки

Сначала зарегистрируйтесь, загрузите собственное фото водомера в workspace, затем создайте API key, когда будете готовы к интеграции.

Зарегистрироваться и загрузить фото Создать API key

Поиск конечных точек

Обзор

Используйте серверную часть веб-сайта для всех внешних интеграций.
Не вызывайте waterMeterAi напрямую из сторонних программ.
Открытый API использует тех же пользователей, квоту, кэш, задачи и правила аудита, что и веб-портал.
Серверная часть может быть ориентирована на различные нижестоящие предприятия AI в зависимости от конфигурации развертывания.
Ответы на задачи теперь включают общий объект result_summary, поэтому разные компании могут отображать разные типы результатов.

Аутентификация

Войдите на сайт и создайте ключ API на странице «Ключи API».
Полный ключ API отображается только один раз при его создании.
Отправляйте ключ в заголовке авторизации при каждом запросе.

Authorization: Bearer wm_xxxxxxxxxxxxxxxxx

API Key Permissions and Limits

Each API key can have independent scopes, an IPv4/IPv6/CIDR allowlist, a total requests-per-minute limit, and a task submissions-per-minute limit.
A valid key without the required scope or outside its source IP allowlist returns 403.
Every valid-key request consumes the total request limit, including requests rejected by scope, IP, or submission policy.
Batch requests consume one total request unit and one submission unit per uploaded file.
Rate-limited responses return 429 with Retry-After and both X-RateLimit-* and X-SubmissionLimit-* headers.
Task creation also has a per-key concurrency limit and returns X-ConcurrencyLimit-* headers; a concurrency rejection uses 429.
For batch concurrency, only files that pass image validation reserve slots, and success headers report the actual active slots after task binding.

Retry-After: 30
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1785902400
X-SubmissionLimit-Limit: 10
X-SubmissionLimit-Remaining: 9
X-ConcurrencyLimit-Limit: 3
X-ConcurrencyLimit-Active: 1
X-ConcurrencyLimit-Remaining: 2

Правила загрузки

Максимальный размер файла: 20MB на изображение.
Поддерживаемые форматы: JPEG, PNG, WEBP.
Серверная часть проверяет фактическое содержимое файла, а не только расширение файла.

Контроль размера загрузки

По умолчанию при пакетной загрузке допускается до 8 изображений с ограничением размера каждого изображения в 20 МБ и общим ограничением размера файла в 20 МБ.
Файл или пакет, превышающий лимит, возвращает 413 перед проверкой изображения или созданием задачи; частичная партия не создается.
Серверная часть обеспечивает фактическое количество полученных байтов, даже если Content-Length отсутствует или используется фрагментированная передача.

Состояния задачи

queued: принят и ожидает обработки AI.
running: в настоящее время обрабатывается или уже передан диспетчеру и все еще запрашивает окончательный результат.
batch_waiting_ai: каждый элемент в пакете ожидает возобновления работы службы AI.
batch_running: пакет уже передан диспетчеру и еще обрабатывается.
done: завершено успешно.
failed: обработка failed.
waiting_ai: queued до тех пор, пока служба AI не вернется в режим онлайн, затем она возобновляется автоматически.

Источники результатов

fresh: создан при новом запуске AI.
cached_exact: соответствует текущему кэшу версии AI.
cached_stale: AI не в сети, возвращен последний кэшированный результат.
pending: окончательного результата пока нет.
failed: задача failed.
Если задача еще не done, проверьте error_message на предмет последней причины повтора или ожидания.

Квота и тарификация

Используйте `GET /api/open/quota` перед отправкой больших нагрузок, если интеграции нужно избежать ошибок квоты.
Квоту расходуют только AI-запуски `fresh`.
Результаты `cached_exact`, `cached_stale`, `pending` и `failed` не расходуют квоту.
Бесплатные аккаунты сначала используют дневную квоту. Платные аккаунты используют активные периодические пакеты квоты, затем временную или фиксированную квоту согласно политике backend.
Когда квота исчерпана, отправка задачи возвращает `429` и сообщение об ошибке вместо создания новой задачи.

Кэш и актуальность результата

Backend кэширует успешные результаты по хэшу изображения и версии AI, включая namespace нижестоящего бизнеса.
`cached_exact` означает, что для того же изображения уже есть успешный результат текущей версии AI, поэтому новый AI-запуск не потребовался.
`cached_stale` означает, что AI-сервис офлайн, и backend вернул последний доступный исторический результат.
Когда `is_latest_ai_version` равно false, храните результат как пригодные к использованию, но требующие проверки исторические данные.
Не считайте, что каждая задача `done` расходовала квоту; проверяйте `result_source`.

Task completion webhooks

Send signed task completion events to your HTTPS endpoint with automatic retries.
This API key is inactive. Existing records remain available, but new, enabled, test, and secret-rotation operations are blocked.

X-WaterMeter-Webhook-Id: whev_new_event
X-WaterMeter-Webhook-Replay-Of: whev_original_event
replay_of_event_id: whev_original_event
blocked endpoint management: HTTP 409
canceled delivery status: canceled

GET`/api/open/quota`

Прочтите текущую квоту и оставшееся использование.

Пример запроса

curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

Пример ответа

{
  "ok": true,
  "email": "[email protected]",
  "quota": {
    "account_type": "free",
    "daily_limit": 20,
    "used": 3,
    "remaining": 17,
    "day_tag": "2026-06-01",
    "is_unlimited": false,
    "monthly_remaining": 0,
    "monthly_bonus_remaining": 0,
    "fixed_remaining": 0,
    "nearest_expire_at": null,
    "quota_summary_text": "Free daily quota: 3/20 used today. Remaining: 17."
  }
}

GET`/api/open/ai-status`

Прочтите статус общедоступной службы для отправки задач и возврата к кэшированным результатам.

Пример запроса

curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

Пример ответа

{
  "ok": true,
  "is_online": true,
  "busy": false,
  "active_jobs": 0,
  "public_status": "online",
  "public_status_label": "online",
  "public_status_reason": "ready",
  "accepts_new_tasks": true,
  "can_return_cached_result": true,
  "queue_state": "idle",
  "queue_count": 0,
  "current_ai_version": "water_v2:wm-ai-v2-2026-06-01",
  "last_checked_at": "2026-06-01T06:15:30Z"
}

POST`/api/open/tasks`

Загрузите одно изображение и создайте одну задачу.

Пример запроса

curl -X POST "https://watermeterai.com/api/open/tasks" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \
  -F "file=@D:\data\meter_001.jpg"

Пример ответа

{
  "ok": true,
  "task_id": "8e6c4d1f8f8348c0bc53e2e39d2dc111",
  "status": "queued",
  "result_source": "pending",
  "visibility": "private",
  "ai_online": true,
  "is_latest_ai_version": false,
  "final_reading": "-",
  "result_summary": {
    "resultKind": "unknown",
    "primaryLabel": "Result",
    "primaryValue": "-",
    "secondaryLabel": "Detail",
    "secondaryValue": "-",
    "summaryText": "No result is available yet."
  },
  "error_message": "",
  "created_at": "2026-06-01T06:16:10Z"
}

GET`/api/open/tasks/{task_id}`

Прочтите один статус задачи и окончательное чтение.

Пример запроса

curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

Пример ответа

{
  "ok": true,
  "task_id": "8e6c4d1f8f8348c0bc53e2e39d2dc111",
  "status": "done",
  "result_source": "fresh",
  "ai_online": true,
  "is_latest_ai_version": true,
  "final_reading": "123.45",
  "meter_type": "pointer",
  "success": "yes",
  "result_summary": {
    "resultKind": "water_meter",
    "primaryLabel": "Final Reading",
    "primaryValue": "123.45",
    "secondaryLabel": "Meter Type",
    "secondaryValue": "pointer",
    "summaryText": "Water meter recognition finished."
  },
  "error_message": "",
  "created_at": "2026-06-01T06:16:10Z"
}

GET`/api/open/tasks`

Прочтите последние задачи, принадлежащие текущему ключевому пользователю API.

Пример запроса

curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

Пример ответа

{
  "ok": true,
  "items": [
    {
      "task_id": "8e6c4d1f8f8348c0bc53e2e39d2dc111",
      "status": "done",
      "result_source": "cached_exact",
      "final_reading": "123.45",
      "meter_type": "pointer",
      "success": "yes",
      "result_summary": {},
      "ai_online": true,
      "is_latest_ai_version": true,
      "created_at": "2026-06-01T06:16:10Z",
      "error_message": ""
    }
  ]
}

POST`/api/open/batches`

Загрузите несколько изображений в одном запросе.

Пример запроса

curl -X POST "https://watermeterai.com/api/open/batches" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \
  -F "files=@D:\data\meter_001.jpg" \
  -F "files=@D:\data\meter_002.jpg"

Пример ответа

{
  "ok": true,
  "batch_id": "5a14f4e5f6d34fdabce00e62c0dd0001",
  "status": "batch_running",
  "total_count": 2,
  "done_count": 0,
  "failed_count": 0,
  "pending_count": 2,
  "items": [
    {
      "index": 0,
      "file_name": "meter_001.jpg",
      "task_id": "task_a",
      "status": "queued",
      "result_source": "pending",
      "final_reading": "-",
      "failure_kind": "",
      "error_message": ""
    },
    {
      "index": 1,
      "file_name": "meter_002.jpg",
      "task_id": "task_b",
      "status": "queued",
      "result_source": "pending",
      "final_reading": "-",
      "failure_kind": "",
      "error_message": ""
    }
  ]
}

GET`/api/open/batches/{batch_id}`

Чтение хода выполнения пакета и состояний задач для каждого файла.

Пример запроса

curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

Пример ответа

{
  "ok": true,
  "batch_id": "5a14f4e5f6d34fdabce00e62c0dd0001",
  "status": "batch_done",
  "total_count": 2,
  "done_count": 2,
  "failed_count": 0,
  "pending_count": 0,
  "items": [
    {
      "index": 0,
      "file_name": "meter_001.jpg",
      "task_id": "task_a",
      "status": "done",
      "result_source": "fresh",
      "final_reading": "123.45",
      "failure_kind": "",
      "error_message": ""
    },
    {
      "index": 1,
      "file_name": "meter_002.jpg",
      "task_id": "task_b",
      "status": "done",
      "result_source": "cached_exact",
      "final_reading": "456.78",
      "failure_kind": "",
      "error_message": ""
    }
  ]
}

Примечания об ошибках

400: неверный запрос или развернутая компания не поддерживает пакетную загрузку.
401: ключ API отсутствует, недействителен, срок действия истек или отключен.
403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
404: задача или пакет не найдены или не принадлежат текущему пользователю.
413: файл слишком большой.
415: неподдерживаемый тип изображения или недопустимое содержимое изображения.
429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.

Пакетная загрузка 400 недоступна

{
  "detail": "batch upload is not supported for business: cax"
}

401 отсутствует или недействителен ключ API

{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}

413 файл слишком большой

{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}

429 квота исчерпана

{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Готовы протестировать workflow?

Используйте web workspace для первого фото, затем переходите к API keys, когда формат результата подойдет вашей системе.

Зарегистрироваться и загрузить фото Создать API key

API OCR счетчиков воды

Начните с реальной загрузки

Обзор

Аутентификация

API Key Permissions and Limits

Правила загрузки

Контроль размера загрузки

Состояния задачи

Источники результатов

Квота и тарификация

Кэш и актуальность результата

Task completion webhooks

GET/api/open/quota

GET/api/open/ai-status

POST/api/open/tasks

GET/api/open/tasks/{task_id}

GET/api/open/tasks

POST/api/open/batches

GET/api/open/batches/{batch_id}

Рекомендуемый расход

Примечания об ошибках

Готовы протестировать workflow?

GET`/api/open/quota`

GET`/api/open/ai-status`

POST`/api/open/tasks`

GET`/api/open/tasks/{task_id}`

GET`/api/open/tasks`

POST`/api/open/batches`

GET`/api/open/batches/{batch_id}`