Watermeter OCR API
Watermeter OCR API. Hierdie bladsy dokumenteer die openbare HTTP API wat deur die webwerf se agterkant blootgestel is vir derdeparty-integrasies.
Begin met 'n regte oplaai
Registreer eers, laai jou eie watermeterfoto in die werksruimte op en skep dan 'n API-sleutel wanneer jy gereed is om te integreer.
Oorsig
- Gebruik die webwerf se agterkant vir alle eksterne integrasies.
- Moet waterMeterAi nie direk van derdeparty-programme af bel nie.
- Die oop API deel dieselfde gebruikers, kwota, kas, take en ouditreëls as die webportaal.
- Die agterkant kan volgens ontplooiingskonfigurasie verskillende afwaartse AI-dienste teiken.
- Taakantwoorde sluit nou 'n generiese result_summary-objek in sodat verskillende dienste verskillende resultatetipes kan vertoon.
Verifikasie
- Teken op die webwerf aan en skep 'n API-sleutel op die API-sleutels-bladsy.
- Die volledige API-sleutel word slegs een keer gewys wanneer dit geskep word.
- Stuur die sleutel in die Authorization-kopskrif by elke versoek.
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
Oplaaireëls
- Maksimum lêergrootte: 20MB per beeld.
- Ondersteunde formate: JPEG, PNG, WEBP.
- Die agterkant valideer werklike lêerinhoud, nie net die lêeruitbreiding nie.
Oplaaigrootte-handhawing
- Bondeloplaaie aanvaar standaard tot 8 beelde, met 'n limiet van 20MB per beeld en 'n totale lêerinhoudslimiet van 20MB.
- 'n Lêer of bondel wat sy limiet oorskry, gee 413 terug voor beeldvalidering of taakskepping; Geen gedeeltelike bondel word geskep nie.
- Die agterkant handhaaf die werklike aantal ontvangde grepe selfs wanneer Content-Length ontbreek of stuk-oordrag gebruik word.
Taakstate
- queued: aanvaar en wag vir AI-verwerking.
- running: word tans verwerk, of is reeds aan die dispatcher oorhandig en doen steeds statusnavrae vir die finale resultaat.
- batch_waiting_ai: elke item in die bondel wag vir die AI diens om weer aanlyn te kom.
- batch_running: die bondel word reeds aan die verspreider oorhandig en is steeds besig om te verwerk.
- done: suksesvol voltooi.
- failed: verwerking het misluk.
- waiting_ai: in die tou totdat die AI diens weer aanlyn is, dan hervat dit outomaties.
Resultaatbronne
- fresh: deur 'n nuwe AI-uitvoering gegenereer.
- cached_exact: het ooreenstem met die huidige AI -weergawe se kas.
- cached_stale: AI vanlyn, het die nuutste kasresultaat teruggegee.
- pending: nog geen finale resultaat nie.
- failed: die taak het misluk.
- Wanneer 'n taak nog nie voltooi is nie, kyk error_message vir die nuutste herpoging of wagrede.
Kwota en Fakturering
- Gebruik `GET /api/open/quota` voordat jy groot werkslading indien as jou integrasie kwota-mislukkings moet vermy.
- Slegs `fresh` AI lopies verbruik kwota.
- `cached_exact`, `cached_stale`, `pending`, en `failed` resultate verbruik nie kwota nie.
- Gratis rekeninge gebruik eers die daaglikse kwota. Betaalde rekeninge gebruik aktiewe periodieke kwotapakkette, dan tydelike of vaste kwota volgens agterkantbeleid.
- Wanneer kwota uitgeput is, gee taakindiening `429` terug en sluit 'n foutboodskap in in plaas daarvan om 'n nuwe taak te skep.
Cache en Resultaatvarsheid
- Die agterkant kas suksesvolle resultate volgens beeldhash en AI-weergawe, insluitend die namespace van die afwaartse diens.
- `cached_exact` beteken dieselfde beeld het reeds 'n suksesvolle resultaat vir die huidige AI-weergawe, dus was geen nuwe AI-uitvoering nodig nie.
- `cached_stale` beteken die AI diens is vanlyn en die agterkant het die nuutste beskikbare historiese resultaat teruggegee.
- Wanneer `is_latest_ai_version` false is, stoor die resultaat as bruikbare maar hersienbare historiese data.
- Moenie aanneem dat elke `done`-taak kwota verbruik het nie; kyk na `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/quotaLees huidige kwota en oorblywende gebruik.
Versoekvoorbeeld
curl -X GET "https://watermeterai.com/api/open/quota" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Reaksievoorbeeld
{
"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-statusLees die openbare diensstatus vir taakindiening en gekas-resultaat-terugval.
Versoekvoorbeeld
curl -X GET "https://watermeterai.com/api/open/ai-status" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Reaksievoorbeeld
{
"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/tasksLaai een beeld op en skep 'n enkele taak.
Versoekvoorbeeld
curl -X POST "https://watermeterai.com/api/open/tasks" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \ -F "file=@D:\data\meter_001.jpg"
Reaksievoorbeeld
{
"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}Lees die status van een taak en die finale lesing.
Versoekvoorbeeld
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Reaksievoorbeeld
{
"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/tasksLees onlangse take wat aan die huidige API sleutelgebruiker behoort.
Versoekvoorbeeld
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Reaksievoorbeeld
{
"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/batchesLaai verskeie beelde in een versoek op.
Versoekvoorbeeld
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"
Reaksievoorbeeld
{
"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}Lees bondelvordering en per-lêer taaktoestande.
Versoekvoorbeeld
curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Reaksievoorbeeld
{
"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": ""
}
]
}Aanbevole vloei
- Kontroleer `GET /api/open/ai-status` voordat jy groot werkslading stuur.
- Stoor `task_id` of `batch_id` onmiddellik na indiening in jou eie stelsel.
- Behandel `queued`, `running`, `waiting_ai`, `batch_waiting_ai` en `batch_running` as nie-finale toestande en hou aan om statusnavrae te doen.
- Gebruik bondelversoeke wanneer die netwerkpad na die agterkant hoë latensie het en die ontplooide diens bondelmodus ondersteun.
- Bondelversoeke vloei tans deur `webBackend -> dispatchCenter -> waterMeterAi`.
- `batch_waiting_ai` beteken elke item wag steeds vir die AI diens, en is nog nie aktief aan die gang nie.
- Wanneer die ontplooide diens `CAD` is, gebruik voorlopig `POST /api/open/tasks` en behandel bondeloplaai as onbeskikbaar.
Foutnotas
- 400: ongeldige versoek, of die ontplooide diens ondersteun nie bondeloplaai nie.
- 401: ontbreek, ongeldig, verval, of API sleutel gedeaktiveer.
- 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
- 404: taak of bondel nie gevind nie, of nie besit deur die huidige gebruiker nie.
- 413: lê te groot.
- 415: nie-ondersteunde beeldtipe of ongeldige beeldinhoud.
- 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 bondel-oplaai nie beskikbaar nie
{
"detail": "batch upload is not supported for business: cax"
}401 ontbreek of ongeldig API sleutel
{
"ok": false,
"error": "unauthorized",
"message": "Missing or invalid API key."
}413 lêer te groot
{
"ok": false,
"error": "file_too_large",
"message": "Maximum file size is 20MB."
}429 kwota uitgeput
{
"ok": false,
"error": "quota_exhausted",
"message": "Quota exhausted.",
"quota": {
"remaining": 0,
"quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
}
}Gereed om die werkvloei te toets?
Gebruik die webwerkspasie vir die eerste foto en beweeg dan na API-sleutels sodra die resultaatformaat by jou stelsel pas.