Водомер OCR API

Водомер OCR API. Ова страница документује јавност 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

Правила отпремања

Максимална величина датотеке: 20 МБ по слици.
Подржани формати: JPEG, PNG, WEBP.
Позадина потврђује стварни садржај датотеке, а не само екстензију датотеке.

Примена величине отпремања

Групно отпремање подразумевано прихвата до 8 слика, са ограничењем од 20 МБ по слици и ограничењем укупног садржаја датотеке од 20 МБ.
Датотека или серија која премашује своје ограничење враћа 413 пре валидације слике или креирања задатка; не ствара се делимична серија.
Позадинска страна намеће стварни број примљених бајтова чак и када Цонтент-Ленгтх недостаје или се користи пренос у комадима.

Стање задатака

у реду чекања: прихваћено и чека на обраду AI.
у току: тренутно се обрађује или се већ предаје диспечеру и још увек тражи коначни резултат.
batch_waiting_ai: свака ставка у групи чека да се услуга AI врати на мрежу.
batch_running: серија је већ предата диспечеру и још се обрађује.
урађено: успешно завршено.
није успело: обрада није успела.
waiting_ai: у реду чекања док се услуга AI не врати на мрежу, а затим се аутоматски наставља.

Извори резултата

свеже: генерисано новим 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

Водомер OCR API

Почните са правим отпремањем

Преглед

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

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