API ya OCR ya mita ya maji
API ya OCR ya mita ya maji. Ukurasa huu unaeleza HTTP API ya umma inayotolewa na backend ya tovuti kwa miunganisho ya wahusika wengine.
Anza na upakiaji halisi
Jisajili kwanza, pakia picha yako ya mita ya maji kwenye nafasi ya kazi, kisha uunde ufunguo wa API ukiwa tayari kuunganisha mfumo.
Muhtasari
- Tumia backend ya tovuti kwa miunganisho yote ya nje.
- Usiite waterMeterAi moja kwa moja kutoka kwa programu za wahusika wengine.
- API ya wazi hutumia watumiaji, kiasi, akiba, kazi na sheria za ukaguzi sawa na lango la wavuti.
- Backend inaweza kulenga huduma tofauti za AI za chini kulingana na usanidi wa utekelezaji.
- Majibu ya kazi sasa yana kitu cha jumla cha result_summary ili huduma tofauti ziweze kuonyesha aina tofauti za matokeo.
Uthibitishaji
- Ingia kwenye tovuti na uunde ufunguo wa API kwenye ukurasa wa Funguo za API.
- Ufunguo kamili wa API huonyeshwa mara moja tu unapoundwa.
- Tuma ufunguo katika kichwa cha Authorization kwa kila ombi.
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
Sheria za Kupakia
- Upeo wa ukubwa wa faili: 20MB kwa kila picha.
- Miundo inayotumika: JPEG, PNG, WEBP.
- Backend inathibitisha maudhui halisi ya faili, si kiendelezi cha faili pekee.
Utekelezaji wa Ukubwa wa Upakiaji
- Upakiaji wa kundi hukubali hadi picha 8 kwa chaguo-msingi, zenye kikomo cha MB 20 kwa kila picha na kikomo cha jumla cha maudhui ya faili 20MB.
- Faili au kundi linalozidi kikomo chake hurejesha 413 kabla ya uthibitishaji wa picha au kuunda kazi; hakuna kundi la sehemu linaloundwa.
- Backend hutumia idadi halisi ya baiti zilizopokelewa hata wakati Content-Length haipo au uhamishaji wa vipande unatumiwa.
Hali za Kazi
- queued: imekubaliwa na inasubiri kuchakatwa na AI.
- running: inachakatwa sasa, au tayari imekabidhiwa kwa dispatcher na hali bado inakaguliwa mara kwa mara ili kupata matokeo ya mwisho.
- batch_waiting_ai: kila kipengee kwenye kundi kinasubiri huduma ya AI kurudi mtandaoni.
- batch_running: kundi tayari limekabidhiwa kwa mtumaji na bado linachakatwa.
- done: imekamilika kwa mafanikio.
- failed: uchakataji umeshindwa.
- waiting_ai: imewekwa kwenye foleni hadi huduma ya AI irudi mtandaoni, kisha itaendelea kiotomatiki.
Vyanzo vya Matokeo
- fresh: imetolewa na uchakataji mpya wa AI.
- cached_exact: ililingana na akiba ya toleo la AI la sasa.
- cached_stale: AI nje ya mtandao, matokeo ya hivi punde yaliyoakibishwa yamerejeshwa.
- pending: hakuna matokeo ya mwisho bado.
- failed: kazi imeshindwa.
- Wakati kazi haijafanywa, angalia error_message kwa sababu ya hivi punde ya kujaribu tena au kusubiri.
Kiasi na Malipo
- Tumia `GET /api/open/quota` kabla ya kuwasilisha mzigo mkubwa wa kazi ikiwa ujumuishaji wako unahitaji kuzuia kushindwa kwa mgao.
- Uchakataji wa AI wenye chanzo cha `fresh` pekee ndio hutumia kiasi.
- `cached_exact`, `cached_stale`, `pending`, na `failed` matokeo hayatumii mgao.
- Akaunti zisizolipishwa hutumia kiasi cha kila siku kwanza. Akaunti zinazolipishwa hutumia vifurushi hai vya kiasi cha muda maalum, kisha kiasi cha muda au cha kudumu kulingana na sera ya backend.
- Wakati kiasi kimekwisha, uwasilishaji wa kazi hurejesha `429` na hujumuisha ujumbe wa hitilafu badala ya kuunda kazi mpya.
Akiba na Upya wa Matokeo
- Backend huhifadhi matokeo yaliyofaulu kwa hash ya picha na toleo la AI, ikijumuisha namespace ya huduma ya AI ya chini.
- `cached_exact` inamaanisha kuwa picha ile ile tayari ina tokeo lililofaulu kwa toleo la sasa la AI, kwa hivyo hakuna uendeshaji mpya wa AI uliohitajika.
- `cached_stale` inamaanisha kuwa huduma ya AI iko nje ya mtandao na sehemu ya nyuma ilirudisha matokeo ya hivi punde ya kihistoria.
- Wakati `is_latest_ai_version` ni false, hifadhi matokeo kama data ya kihistoria inayoweza kutumika lakini inayohitaji kukaguliwa.
- Usidhani kila kazi ya `done` ilitumia kiasi; angalia `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
/api/open/quotaSoma kiasi cha sasa na matumizi yaliyosalia.
Ombi Mfano
curl -X GET "https://watermeterai.com/api/open/quota" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Mfano wa Majibu
{
"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
/api/open/ai-statusSoma hali ya huduma ya umma ili kuamua uwasilishaji wa kazi na matumizi ya matokeo ya akiba.
Ombi Mfano
curl -X GET "https://watermeterai.com/api/open/ai-status" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Mfano wa Majibu
{
"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
/api/open/tasksPakia picha moja na uunde kazi moja.
Ombi Mfano
curl -X POST "https://watermeterai.com/api/open/tasks" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \ -F "file=@D:\data\meter_001.jpg"
Mfano wa Majibu
{
"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}
/api/open/tasks/{task_id}Soma hali ya kazi moja na usomaji wa mwisho.
Ombi Mfano
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Mfano wa Majibu
{
"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/open/tasksSoma kazi za hivi majuzi zinazomilikiwa na mtumiaji wa ufunguo wa sasa wa API.
Ombi Mfano
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Mfano wa Majibu
{
"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
/api/open/batchesPakia picha nyingi katika ombi moja.
Ombi Mfano
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"
Mfano wa Majibu
{
"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}
/api/open/batches/{batch_id}Soma maendeleo ya kundi na hali za kazi ya kila faili.
Ombi Mfano
curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Mfano wa Majibu
{
"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": ""
}
]
}Mtiririko Unaopendekezwa
- Angalia `GET /api/open/ai-status` kabla ya kutuma mzigo mkubwa wa kazi.
- Hifadhi `task_id` au `batch_id` katika mfumo wako mara baada ya kuwasilisha.
- Chukulia `queued`, `running`, `waiting_ai`, `batch_waiting_ai` na `batch_running` kama hali zisizo za mwisho na uendelee kukagua hali mara kwa mara.
- Tumia maombi ya kundi wakati njia ya mtandao kwenda backend ina ucheleweshaji mkubwa na huduma iliyotekelezwa inatumia hali ya kundi.
- Maombi ya kundi kwa sasa yanapitia `webBackend -> dispatchCenter -> waterMeterAi`.
- `batch_waiting_ai` inamaanisha kuwa kila kipengee bado kinangojea huduma ya AI, bado haijatekelezwa kikamilifu.
- Wakati huduma iliyotekelezwa ni `CAD`, tumia `POST /api/open/tasks` kwa sasa na uchukulie upakiaji wa kundi kuwa haupatikani.
Vidokezo vya Hitilafu
- 400: ombi batili, au huduma iliyotekelezwa haitumii upakiaji wa kundi.
- 401: ufunguo wa API haupo, ni batili, umeisha muda au umezimwa.
- 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
- 404: kazi au kundi halipatikani, au halimilikiwi na mtumiaji wa sasa.
- 413: faili ni kubwa mno.
- 415: aina ya picha isiyotumika au maudhui batili ya picha.
- 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
Upakiaji wa bechi 400 haupatikani
{
"detail": "batch upload is not supported for business: cax"
}401 inakosekana au ni batili ya ufunguo wa API
{
"ok": false,
"error": "unauthorized",
"message": "Missing or invalid API key."
}413 faili ni kubwa mno
{
"ok": false,
"error": "file_too_large",
"message": "Maximum file size is 20MB."
}Mgawo wa 429 umekamilika
{
"ok": false,
"error": "quota_exhausted",
"message": "Quota exhausted.",
"quota": {
"remaining": 0,
"quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
}
}Je, uko tayari kujaribu mtiririko wa kazi?
Tumia nafasi ya kazi ya wavuti kwa picha ya kwanza, kisha nenda kwenye funguo za API pindi umbizo la matokeo linapofaa mfumo wako.