API OCR pou kontè dlo
API OCR pou kontè dlo. Paj sa a esplike API HTTP piblik backend sit entènèt la mete disponib pou entegrasyon ak sistèm ekstèn.
Kòmanse avèk yon imaj reyèl
Enskri anvan, voye pwòp foto kontè dlo pa w nan espas travay la, epi kreye yon kle API lè w pare pou fè entegrasyon an.
Apèsi
- Sèvi ak backend sit entènèt la pou tout entegrasyon ekstèn yo.
- Pwogram ekstèn yo pa dwe rele waterMeterAi dirèkteman.
- API piblik la sèvi ak menm itilizatè, kota, kachèt, travay ak règ odit ak pòtay entènèt la.
- Dapre konfigirasyon deplwaman an, backend la ka dirije demann yo bay diferan sèvis AI anba li.
- Repons travay yo gen yon objè result_summary jeneral pou diferan sèvis ka montre diferan kalite rezilta.
Otantifikasyon
- Konekte sou sit entènèt la epi kreye yon kle API sou paj Kle API a.
- Sistèm nan montre kle API konplè a yon sèl fwa, lè li kreye.
- Voye kle a nan antèt Authorization pou chak demann.
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
Règ pou voye imaj
- Gwosè maksimòm: 20MB pou chak imaj.
- Fòma ki sipòte: JPEG, PNG, WEBP.
- Backend la verifye vrè kontni fichye a, pa sèlman ekstansyon li.
Kontwòl gwosè imaj yo voye
- Pa defo, yon demann an pakèt aksepte jiska 8 imaj, avèk yon limit 20MB pou chak imaj ak 20MB pou kontni tout fichye yo ansanm.
- Si yon fichye oswa yon pakèt depase limit la, sistèm nan retounen 413 anvan li verifye imaj la oswa kreye travay la; li pa kreye yon pakèt pasyèl.
- Backend la aplike limit la sou kantite byte li resevwa toutbon, menm lè Content-Length pa prezan oswa yo itilize transmisyon an moso.
Estati travay yo
- queued: travay la aksepte epi l ap tann tretman AI.
- running: travay la ap trete kounye a, oswa li deja pase bay dispachè a epi sistèm nan toujou ap tcheke rezilta final la.
- batch_waiting_ai: chak eleman nan pakèt la ap tann sèvis AI a retounen sou entènèt; tretman an poko kòmanse.
- batch_running: pakèt la deja pase bay dispachè a epi tretman an ap kontinye.
- done: travay la fini avèk siksè.
- failed: tretman an echwe.
- waiting_ai: travay la rete nan fil datant jiskaske sèvis AI a retounen sou entènèt, apre sa li kontinye otomatikman.
Sous rezilta yo
- fresh: yon nouvo ekzekisyon AI te pwodwi rezilta a.
- cached_exact: imaj la koresponn ak kachèt vèsyon AI aktyèl la.
- cached_stale: AI a offline, epi sistèm nan retounen dènye rezilta ki nan kachèt la.
- pending: pa gen rezilta final pou kounye a.
- failed: travay la echwe.
- Lè yon travay poko fini, tcheke error_message pou wè dènye rezon li t ap tann oswa li t ap eseye ankò.
Kota ak bòdwo
- Sèvi ak `GET /api/open/quota` anvan ou soumèt anpil travay si entegrasyon ou an dwe evite echèk paske kota a fini.
- Se sèlman yon nouvo ekzekisyon AI ki gen sous `fresh` ki itilize kota.
- Rezilta `cached_exact`, `cached_stale`, `pending` ak `failed` pa itilize kota.
- Kont gratis yo itilize kota chak jou anvan. Kont peye yo itilize pakè kota peryodik ki aktif, epi kota tanporè oswa fiks selon règleman backend la.
- Lè kota a fini, soumisyon travay la retounen `429` avèk yon mesaj erè olye li kreye yon nouvo travay.
Kachèt ak aktyalite rezilta
- Backend la mete rezilta ki reyisi yo nan kachèt dapre hash imaj la, vèsyon AI a ak namespace sèvis ki anba li.
- `cached_exact` vle di menm imaj la deja gen yon rezilta ki reyisi pou vèsyon AI aktyèl la, kidonk pa t nesesè pou relanse AI a.
- `cached_stale` vle di sèvis AI a offline epi backend la retounen dènye rezilta istorik ki disponib la.
- Lè `is_latest_ai_version` se false, konsève rezilta a kòm done istorik ki itil men ki bezwen verifikasyon.
- Pa sipoze tout travay `done` te itilize kota; tcheke `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/quotaJwenn kota aktyèl la ak kantite itilizasyon ki rete.
Egzanp demann
curl -X GET "https://watermeterai.com/api/open/quota" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Egzanp repons
{
"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-statusJwenn estati sèvis piblik la pou konnen si w ka soumèt travay oswa retounen sou rezilta ki nan kachèt.
Egzanp demann
curl -X GET "https://watermeterai.com/api/open/ai-status" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Egzanp repons
{
"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/tasksVoye yon imaj epi kreye yon sèl travay.
Egzanp demann
curl -X POST "https://watermeterai.com/api/open/tasks" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \ -F "file=@D:\data\meter_001.jpg"
Egzanp repons
{
"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}Jwenn estati yon travay ak lekti final li.
Egzanp demann
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Egzanp repons
{
"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/tasksJwenn dènye travay itilizatè kle API aktyèl la posede.
Egzanp demann
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Egzanp repons
{
"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/batchesVoye plizyè imaj nan yon sèl demann.
Egzanp demann
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"
Egzanp repons
{
"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}Jwenn pwogrè pakèt la ak estati travay chak fichye.
Egzanp demann
curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Egzanp repons
{
"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": ""
}
]
}Pwosesis rekòmande
- Tcheke `GET /api/open/ai-status` anvan ou voye gwo kantite travay.
- Konsève `task_id` oswa `batch_id` nan pwòp sistèm ou tousuit apre soumisyon an.
- Trete `queued`, `running`, `waiting_ai`, `batch_waiting_ai` ak `batch_running` kòm estati ki pa final epi kontinye tcheke estati a.
- Sèvi ak demann an pakèt lè koneksyon rezo a ak backend la gen anpil reta epi sèvis deplwaye a sipòte mòd pakèt.
- Kounye a, demann an pakèt yo pase nan `webBackend -> dispatchCenter -> waterMeterAi`.
- `batch_waiting_ai` vle di chak eleman toujou ap tann sèvis AI a epi li poko ap fonksyone.
- Lè sèvis deplwaye a se `CAD`, sèvi ak `POST /api/open/tasks` pou kounye a epi konsidere voye imaj an pakèt kòm yon fonksyon ki pa disponib.
Nòt sou erè
- 400: demann lan pa valab oswa sèvis deplwaye a pa sipòte imaj an pakèt.
- 401: kle API a manke, li pa valab, li ekspire oswa li dezaktive.
- 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
- 404: travay oswa pakèt la pa jwenn, oswa li pa pou itilizatè aktyèl la.
- 413: fichye a twò gwo.
- 415: kalite imaj la pa sipòte oswa kontni imaj la pa valab.
- 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 imaj an pakèt pa disponib
{
"detail": "batch upload is not supported for business: cax"
}401 kle API manke oswa pa valab
{
"ok": false,
"error": "unauthorized",
"message": "Missing or invalid API key."
}413 fichye a twò gwo
{
"ok": false,
"error": "file_too_large",
"message": "Maximum file size is 20MB."
}429 kota a fini
{
"ok": false,
"error": "quota_exhausted",
"message": "Quota exhausted.",
"quota": {
"remaining": 0,
"quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
}
}Èske w pare pou teste pwosesis la?
Sèvi ak espas travay entènèt la pou premye foto a, epi pase nan kle API yo lè fòma rezilta a adapte ak sistèm ou an.