API ya OCR ya metero y’amazi

API ya OCR ya metero y’amazi. Uru rupapuro rusobanura HTTP API rusange itangwa na backend y'urubuga kugira ngo sisitemu z'abandi ziyikoreshe.

Tangira wohereza ifoto nyayo

Banza wiyandikishe, wohereze ifoto ya metero y'amazi yawe mu mwanya w'akazi, hanyuma ukore urufunguzo rwa API igihe witeguye kuyihuza na sisitemu yawe.

Iyandikishe kandi wohereze Ifoto Kora urufunguzo rwa API

Shakisha endpoints

Incamake

Koresha backend y'urubuga ku mikoranire yose yo hanze.
Ntugahamagare waterMeterAi mu buryo butaziguye ukoresheje porogaramu z'indi sosiyete.
API ifunguye isangira n'urubuga abakoresha, quota, cache, imirimo, n'amabwiriza y'igenzura amwe.
Backend ishobora guhuza serivisi zitandukanye za AI zo hasi hakurikijwe igenamiterere rya deployment.
Ibisubizo by'imirimo birimo ikintu rusange cya result_summary kugira ngo serivisi zitandukanye zerekane ubwoko butandukanye bw'ibisubizo.

Kwemeza

Injira ku rubuga hanyuma ukore urufunguzo rwa API ku rupapuro rwa API Keys.
Urufunguzo rwa API rwuzuye rwerekanwa rimwe gusa igihe rukozwe.
Ohereza urufunguzo mu mutwe wa Authorization kuri buri busabe.

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

Amabwiriza yo kohereza

Ubunini bwa dosiye: 20MB kuri buri shusho.
Imiterere ishyigikiwe: JPEG, PNG, WEBP.
Backend igenzura ibiri muri dosiye koko, ntabwo ireba umugereka wa dosiye gusa.

Igenzura ry'ingano y'ibyoherezwa

Kohereza batch byemera amashusho agera kuri 8 ku buryo busanzwe, buri shusho ntirenge 20MB kandi ibiri muri dosiye zose hamwe ntibirenge 20MB.
Dosiye cyangwa batch irenze igipimo isubiza 413 mbere yo kugenzura ishusho cyangwa gukora umurimo; nta gice cya batch gikorwa.
Backend yubahiriza umubare nyawo wa bytes yakiriwe n'iyo Content-Length ibuze cyangwa hakoreshejwe chunked transfer.

Imiterere y'imirimo

queued: Byakiriwe kandi bitegereje gutunganywa na AI.
running: Birimo gutunganywa, cyangwa byamaze guhabwa dispatcher kandi imiterere ikomeje kugenzurwa kugeza ku gisubizo cya nyuma.
batch_waiting_ai: Buri kintu muri batch gitegereje ko serivisi ya AI isubira online.
batch_running: Batch yamaze guhabwa dispatcher kandi iracyatunganywa.
done: Byarangiye neza.
failed: Gutunganya byanze.
waiting_ai: Bitegereza ku murongo kugeza serivisi ya AI isubiye online, hanyuma bigakomeza byikora.

Inkomoko y'ibisubizo

fresh: Byakozwe n'itunganywa rishya rya AI.
cached_exact: Byahuye na cache ya verisiyo ya AI iriho.
cached_stale: AI iri offline, hasubijwe igisubizo giheruka kubikwa muri cache.
pending: Nta gisubizo cya nyuma kiraboneka.
failed: Umurimo wanze.
Mu gihe igikorwa kitarakorwa, jya ugenzura error_message kugira ngo ubone impamvu ziheruka gukorwa cyangwa gutegereza ko ubikora.

Quota na fagitire

Koresha `GET /api/open/quota` mbere yo kohereza imirimo myinshi niba sisitemu yawe igomba kwirinda kubura quota.
Gusa `fresh` AI ikoresha kwota.
`cached_exact`, `cached_stale`, `pending`, na `failed` ibisubizo ntibikoresha kwota.
Konti yubuntu koresha kwota ya buri munsi mbere. Konti yishyuwe ikoresha igenamigambi ryigihe gikoreshwa, hanyuma igipimo cyigihe gito cyangwa cyagenwe ukurikije politiki yinyuma.
Iyo quota irangiye, kohereza umurimo bisubiza `429` n'ubutumwa bw'ikosa aho gukora umurimo mushya.

Cache nibisubizo bishya

Backend ibika ibisubizo byagenze neza hakurikijwe hash y'ishusho na verisiyo ya AI, harimo namespace ya serivisi yo hasi.
`cached_exact` bisobanura ko iyo foto isanzwe ifite igisubizo cyiza kuri verisiyo ya AI iriho, bityo gutunganya AI bundi bushya ntibyari bikenewe.
`cached_stale` bivuze ko serivisi ya AI iri offline kandi backend yasubije ibisubizo by'amateka biheruka kuboneka.
Iyo `is_latest_ai_version` ari false, bika igisubizo nk'amakuru y'amateka akoreshwa ariko agomba kongera gusuzumwa.
Ntugatekereze ko buri `done` igikorwa cyakoreshejwe; reba `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`

Soma ibipimo biriho hamwe nibisigaye bikoreshwa.

Gusaba Urugero

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

Urugero rw'igisubizo

{
  "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`

Soma imiterere ya serivisi rusange kugira ngo wohereze imirimo kandi ukoreshe cache igihe serivisi itaboneka.

Gusaba Urugero

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

Urugero rw'igisubizo

{
  "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`

Shyiramo ifoto imwe hanyuma ukore igikorwa kimwe.

Gusaba Urugero

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

Urugero rw'igisubizo

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

Soma imiterere imwe yumurimo no gusoma byanyuma.

Gusaba Urugero

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

Urugero rw'igisubizo

{
  "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`

Soma imirimo iheruka y'umukoresha ufite urufunguzo rwa API ruriho.

Gusaba Urugero

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

Urugero rw'igisubizo

{
  "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`

Kuramo amashusho menshi mubisabwa kimwe.

Gusaba Urugero

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"

Urugero rw'igisubizo

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

Soma ibyiciro byiterambere hamwe na dosiye yibikorwa.

Gusaba Urugero

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

Urugero rw'igisubizo

{
  "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": ""
    }
  ]
}

Imigendekere y'akazi isabwa

Banza ugenzure `GET /api/open/ai-status` mbere yo kohereza imirimo myinshi.
Bika `task_id` cyangwa `batch_id` muri sisitemu yawe ako kanya nyuma yo kohereza.
Fata `queued`, `running`, `waiting_ai`, `batch_waiting_ai`, na `batch_running` nk'imiterere itararangira kandi ukomeze kugenzura imiterere kenshi.
Koresha batch requests igihe inzira y'urusobe igana kuri backend itinda cyane kandi serivisi yoherejwe ishyigikira batch mode.
Batch requests ubu zinyura muri `webBackend -> dispatchCenter -> waterMeterAi`.
`batch_waiting_ai` bisobanura ko buri kintu kigitegereje serivisi ya AI kandi kitaratangira gutunganywa.
Iyo serivisi yoherejwe ari `CAD`, koresha `POST /api/open/tasks` ubu kandi ufate kohereza batch nk'ukutaboneka.

Inyandiko Ikosa

400: ubusabe ntibwemewe, cyangwa serivisi yoherejwe ntishyigikira kohereza batch.
401: urufunguzo rwa API rurabuze, ntirwemewe, rwararengeje igihe, cyangwa rwarahagaritswe.
403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
404: umurimo cyangwa icyiciro nticyabonetse, cyangwa ntigifitwe numukoresha uriho.
413: dosiye nini cyane.
415: ubwoko bw'ishusho ntibushyigikiwe cyangwa ibiri mu ishusho ntibyemewe.
429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.

400 icyiciro cyoherejwe kidashoboka

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

401 urufunguzo rwa API rurabuze cyangwa ntirwemewe

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

413 dosiye nini cyane

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

429 quota yararangiye

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

Witeguye kugerageza imigendekere y'akazi?

Koresha umwanya w'akazi wo ku rubuga ku ifoto ya mbere, hanyuma ukoreshe API keys igihe imiterere y'ibisubizo ihuye na sisitemu yawe.

Iyandikishe kandi wohereze Ifoto Kora urufunguzo rwa API

API ya OCR ya metero y’amazi

Tangira wohereza ifoto nyayo

Incamake

Kwemeza

API Key Permissions and Limits

Amabwiriza yo kohereza

Igenzura ry'ingano y'ibyoherezwa

Imiterere y'imirimo

Inkomoko y'ibisubizo

Quota na fagitire

Cache nibisubizo bishya

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}

Imigendekere y'akazi isabwa

Inyandiko Ikosa

Witeguye kugerageza imigendekere y'akazi?

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