API OCR для лічыльнікаў вады

API OCR для лічыльнікаў вады. Гэтая старонка дакументуе публічны HTTP API , адкрыты бэкендам сайта для інтэграцыі трэціх бакоў.

Пачніце з сапраўднай загрузкі

Спачатку зарэгіструйцеся, загрузіце сваю ўласную фатаграфію воднага лічыльніка ў працоўнае месца, а потым стварыце API ключ, калі будзеце гатовыя да інтэграцыі.

Зарэгістравацца і загрузіць фота Стварыце API ключ

Канчатковыя пункты пошуку

Агляд

Выкарыстоўвайце бэкенд сайта для ўсіх знешніх інтэграцый.
Не тэлефануйце 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 да праверкі выявы або стварэння задачы; частковая партыя не ствараецца.
Бэкэнд кантралюе фактычную колькасць прынятых байтаў нават калі адсутнічае даўжыня змесціва або выкарыстоўваецца перадача ў частках.

Штаты-задачы

У чарзе: прынята і чакаю AI апрацоўкі.
Бяжыць: зараз апрацоўваецца, або ўжо перададзена дыспетчару і ўсё яшчэ праводзіць апытанне для канчатковага выніку.
batch_waiting_ai: кожны тавар у партыі чакае, пакуль сэрвіс AI адновіць працу.
batch_running: партыя ўжо перададзена дыспетчару і яшчэ апрацоўваецца.
Гатова: Завершана паспяхова.
Няўдача: апрацоўка не атрымалася.
waiting_ai: стаяць у чарзе, пакуль сэрвіс AI не адновіць працу, пасля чаго аўтаматычна аднаўляецца.

Крыніцы вынікаў

Fresh: генеруецца новым праходжаннем AI .
cached_exact: супадаў з актуальным кэшам версіі AI .
cached_stale: AI афлайн, апошні кэшаваны вынік вярнуты.
У чаканні: Канчатковага выніку пакуль няма.
Няўдача: Задача правалілася.
Калі задача яшчэ не завершана, правярайце error_message апошняе паўторнае паспрабаванне або прычыну чакання.

Квота і рахункі

Выкарыстоўвайце `GET /api/open/quota` перад падачай вялікіх нагрузак, калі ваша інтэграцыя павінна пазбегнуць парушэнняў квот.
Толькі `fresh` AI прабежкі спажываюць квоту.
`cached_exact`, `cached_stale`, `pending`і `failed` вынікі не спажываюць квоту.
Бясплатныя рахункі спачатку выкарыстоўваюць штодзённую квоту. Платныя рахункі выкарыстоўваюць актыўныя перыядычныя квотныя пакеты, а затым часовыя або фіксаваныя квоты ў адпаведнасці з палітыкай бэкэнду.
Калі квота скончылася, падача задачы вяртае `429` і ўключае паведамленне пра памылку замест стварэння новай задачы.

Свежасць кэша і вынікаў

Бэкэнд кэшуе паспяховыя вынікі па хэшы малюнка і AI версіі, уключаючы прастору імёнаў ніжэй па патоцы бізнесу.
`cached_exact` азначае, што той жа малюнак ужо мае паспяховы вынік для бягучай версіі AI , таму новы запуск AI не быў патрэбны.
`cached_stale` азначае, што сэрвіс AI не працуе, а бэкенд вяртаў апошні даступны гістарычны вынік.
Калі `is_latest_ai_version` няпраўда, захоўвайце вынік як карысныя, але праглядальныя гістарычныя дадзеныя.
Не лічыце, што кожная `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": ""
    }
  ]
}

Рэкамендаваны паток

Праверце `GET /api/open/ai-status` перад тым, як адпраўляць вялікія нагрузкі.
Захоўвайце `task_id` або `batch_id` ў сваёй сістэме адразу пасля адпраўкі.
Разглядайце `queued`, `running`, `waiting_ai`, `batch_waiting_ai`і `batch_running` як неканчатковыя штаты і працягвайце праводзіць апытанні.
Выкарыстоўвайце пакетныя запыты, калі сеткавы шлях да бэкенда мае высокую затрымку і разгортваны бізнес падтрымлівае пакетны рэжым.
Пакетныя запыты цяпер праходзяць праз `webBackend -> dispatchCenter -> waterMeterAi`.
`batch_waiting_ai` азначае, што кожны тавар усё яшчэ чакае сэрвісу AI і яшчэ не працуе актыўна.
Калі разгортваная кампанія будзе `CAD`, выкарыстоўвайце `POST /api/open/tasks` пакуль і лічыце пакетную загрузку недаступнай.

Памылковыя заўвагі

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."
  }
}

Гатовыя пратэставаць працоўны працэс?

Выкарыстоўвайце вэб-прастору для першага фота, а потым пераходзьце да клавіш API , калі фармат выніку падыходзіць для вашай сістэмы.

Зарэгістравацца і загрузіць фота Стварыце API ключ

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}

Рэкамендаваны паток

Памылковыя заўвагі

Гатовыя пратэставаць працоўны працэс?

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}`