Суу эсептегич OCR API

Суу эсептегич OCR API. Бул барак веб-сайттын арткы бөлүгү үчүнчү тараптын интеграциялары үчүн ачык HTTP API коомчулукту документтейт.

Чыныгы жүктөөдөн баштаңыз

Алгач катталып, жумуш жайына өзүңүздүн суу өлчөгүчтүн сүрөтүн жүктөп, интеграцияга даяр болгондо API ачкычын түзүңүз.

Катталып, сүрөттү жүктө API ачкычын түзүңүз

API интерфейстерин издөө

Кыскача маалымат

Бардык тышкы интеграциялар үчүн сайттын backend'ин колдонуңуз.
Үчүнчү тарап программаларынан waterMeterAi кызматын түз колдонбоңуз.
Ачык API веб-портал менен бирдей колдонуучуларды, квоталарды, кэшти, тапшырмаларды жана аудит эрежелерин бөлүшөт.
Backend жайгаштыруу конфигурациясы аркылуу ар кандай төмөнкү AI бизнесин бутага ала алат.
Тапшырма жооптору эми жалпы result_summary объектин камтыйт, ошондуктан ар кандай ишканалар ар кандай натыйжа түрлөрүн көрсөтө алышат.

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

Веб-сайтка кирип, API Keys барагында API ачкычын түзүңүз.
Толук API ачкычы түзүлгөндө бир гана жолу көрсөтүлөт.
Ар бир өтүнүчтө ачкычты Authorization башында жөнөтүңүз.

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.
Backend файлдын чыныгы мазмунун текшерет, файл кеңейтүүсүн гана эмес.

Жүктөө көлөмүн көзөмөлдөө

Топтук жүктөөлөр демейки боюнча 8 сүрөткө чейин кабыл алат, ар бир сүрөт үчүн 20MB жана жалпы файл мазмуну 20MB чектөөсү бар.
Чектен ашкан файл же пакет сүрөттү текшерүүдөн же тапшырма түзүүдөн мурун 413 кайтарат; Жарым-жартылай партия түзүлбөйт.
Backend Content-Length жок болсо же бөлүктөргө бөлүнгөн өткөрүү колдонулса да, кабыл алынган байттардын чыныгы санын камсыздайт.

Тапшырма абалдары

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

Натыйжа булактары

fresh: AI жаңы иштетилгенде түзүлдү.
cached_exact: учурдагы AI версиясынын кэшине дал келди.
cached_stale: AI оффлайн, акыркы кэштелген натыйжа кайтарылды.
pending: акыркы жыйынтык азырынча жок.
failed: тапшырма ишке ашкан жок.
Тапшырма бүткөн жок болсо, error_message акыркы кайра аракет кылуу же күтүү себебин текшериңиз.

Квота жана эсептөө

Интеграцияңыз квота жетишсиздигинен чыккан катаны болтурбашы керек болсо, көп тапшырма жөнөтүүдөн мурда `GET /api/open/quota` колдонуңуз.
Квотаны `fresh` AI аркылуу жаңы таануу гана сарптайт.
`cached_exact`, `cached_stale`, `pending` жана `failed` жыйынтыктары квотаны колдонбойт.
Акысыз эсептер биринчи күнүмдүк квотаны колдонушат. Төлөнүүчү эсептер активдүү периоддук квота пакеттерин колдонушат, андан кийин арткы саясатка ылайык убактылуу же туруктуу квота берилет.
Квота түгөнгөндө, тапшырма тапшыруу `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": ""
    }
  ]
}

Сунушталган агым

Чоң жүктөмдөрдү жөнөтүүдөн мурун `GET /api/open/ai-status` текшериңиз.
Жөнөтүлгөндөн кийин дароо `task_id` же `batch_id` өз системаңызда сактаңыз.
`queued`, `running`, `waiting_ai`, `batch_waiting_ai` жана `batch_running` абалдарын акыркы эмес деп эсептеп, абалды мезгил-мезгили менен текшерүүнү улантыңыз.
Backendге тармак жолу жогорку кечигүү болгондо жана жайгаштырылган бизнес пакеттик режимди колдогондо пакеттик сурамдарды колдонуңуз.
Топтомдук сурамдар учурда `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}`