WaterMeter AI
ЈазикМакедонски
Други јазици

API за OCR на водомери

API за OCR на водомери. Оваа страница ги документира јавните HTTP API изложени од задниот дел на веб-страницата за интеграции од трети страни.

Започнете со вистинско качување

Прво регистрирајте се, поставете ваша фотографија од водомерот во работниот простор, а потоа креирајте API клуч кога ќе бидете подготвени за интеграција.

Регистрирајте се и поставете фотографијаКреирајте API клуч

Преглед

  • Користете го бекендот на веб-страницата за сите надворешни интеграции.
  • Не се јавувај директно waterMeterAi од трети страни.
  • Отворениот API ги дели истите корисници, квота, кеш, задачи и ревизорски правила како веб-порталот.
  • Backend може да таргетира различни бизниси во долниот 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 слики, со ограничување од 20MB по слика и вкупно 20MB ограничување на содржината на датотеки.
  • Датотека или серија што ја надминува својата граница враќа 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` резултатите не трошат квота.
  • Бесплатните сметки прво ја користат дневната квота. Платените сметки користат активни периодични квотни пакети, а потоа привремена или фиксна квота според backend политиката.
  • Кога квотата ќе се исцрпи, поднесувањето на задача се враќа `429` и вклучува порака за грешка наместо да се креира нова задача.

Свежина на кешот и резултатите

  • Бекендот кешира успешни резултати преку хеш на слика и AI верзија, вклучувајќи го и downstream бизнис просторот на имиња.
  • `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}

Прочитајте го прогресот на batch и состојбите на задачите по датотека.

Пример за барање
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` како неконечни состојби и продолжете со анкети.
  • Користете batch барања кога мрежниот пат до backend има висока латентност и распоредениот бизнис поддржува batch режим.
  • Пакетните барања моментално течат низ `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` значи дека секој артикл сè уште чека на AI услугата, сè уште не работи активно.
  • Кога распоредениот бизнис ќе биде `CAD`, користи `POST /api/open/tasks` засега и третирај пакетно качување како недостапен.

Белешки за грешки

  • 400: невалиден барање, или распоредениот бизнис не поддржува batch upload.
  • 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 клуч