API ye-OCR yemitha yamanzi

API ye-OCR yemitha yamanzi. Eli phepha libonisa HTTP API zoluntu zivezwe yiwebhusayithi ye-backend yokudityaniswa komntu wesithathu.

Qala ngokulayisha okwenene

Bhalisa kuqala, ulayishe ifoto yakho yemitha yamanzi kwindawo yokusebenzela, emva koko wenze isitshixo API xa ulungele ukudibanisa.

Bhalisa kwaye ulayishe ifoto Yenza isitshixo se-API

Khangela ii-endpoint

Isishwankathelo

Sebenzisa i-backend yewebhusayithi kuzo zonke izidibaniso zangaphandle.
Musa ukubiza waterMeterAi ngokuthe ngqo kwiinkqubo zomntu wesithathu.
I- API evulekileyo yabelana ngabasebenzisi abafanayo, i-quota, i-cache, imisebenzi, kunye nemithetho yophicotho-zincwadi njenge-portal yewebhu.
I-backend inokusebenzisa iinkonzo ezahlukeneyo ze-AI ezisezantsi ngokwesicwangciso se-deployment.
Iimpendulo zomsebenzi zibandakanya into eqhelekileyo ye-result_summary ukuze iinkonzo ezahlukeneyo zibonise iintlobo ezahlukeneyo zeziphumo.

Ubungqina

Ngena kwiwebhusayithi kwaye wenze isitshixo se-API kwiphepha le-API Keys.
Isitshixo esipheleleyo se-API siboniswa kube kanye kuphela xa senziwe.
Thumela isitshixo kwisihloko se-Authorization kwisicelo ngasinye.

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

Imigaqo yokulayisha

Ubungakanani befayile obuphezulu: 20MB kumfanekiso ngamnye.
Iifomathi ezixhaswayo: JPEG, PNG, WEBP.
I-backend iqinisekisa umxholo wefayile yokwenene, hayi ulwandiso lwefayile kuphela.

Ukunyanzeliswa kobungakanani bokulayisha

Ukulayishwa kwebhetshi kwamkela ukuya kuthi ga kwimifanekiso eyi-8 ngokungagqibekanga, kunye nomda we-20MB womfanekiso ngamnye kunye nomda we-20MB womxholo wefayile.
Ifayile okanye ibhetshi engaphezulu komda wayo ibuyisela 413 ngaphambi kokuqinisekiswa komfanekiso okanye ukudalwa komsebenzi; Akukho nto inxalenye ye-batch eyenziweyo.
I-backend inyanzelisa ukubala kwe-byte efunyenweyo nokuba i-Content-Length ilahlekile okanye ukudluliselwa kwe-chunked kusetyenziswa.

Iimeko zomsebenzi

queued: Wamkelwe kwaye ulinde ukuqhubekekiswa yi-AI.
running: Uyaqhubekekiswa ngoku, okanye sele unikezelwe kwi-dispatcher kwaye imeko isajongwa rhoqo ukuze kufunyanwe isiphumo sokugqibela.
batch_waiting_ai: Yonke into kwibhetshi ilindele inkonzo ye-AI ukuba ibuyele kwi-intanethi.
batch_running: Ibhetshi sele inikezelwe kwi-dispatcher kwaye isaqhubekekiswa.
done: Igqityiwe ngempumelelo.
failed: Ukuqhubekekiswa akuphumelelanga.
waiting_ai: Usemgceni de inkonzo ye-AI ibuyele kwi-intanethi, emva koko uqhubeke ngokuzenzekelayo.

Imithombo yeziphumo

fresh: Yenziwe kukuqhubekekiswa okutsha kwe-AI.
cached_exact: Ihambelana ne-cache yenguqulelo yangoku ye-AI.
cached_stale: I-AI ayikho kwi-intanethi, kubuyiswe isiphumo samva nje esikwi-cache.
pending: Akukho siphumo sokugqibela okwangoku.
failed: Umsebenzi awuphumelelanga.
Xa umsebenzi ungenziwanga okwangoku, khangela error_message ukuzama kwakhona okanye isizathu sokulinda.

I-Quota kunye ne-Billing

Sebenzisa `GET /api/open/quota` ngaphambi kokungenisa imithwalo emikhulu ukuba ukudityaniswa kwakho kufuna ukunqanda ukusilela kwe-quota.
Kukuqhubekekiswa kwe-AI oku-`fresh` kuphela okusebenzisa i-quota.
`cached_exact`, `cached_stale`, `pending`, kunye `failed` iziphumo azidli i-quota.
Iiakhawunti zasimahla zisebenzisa i-quota yemihla ngemihla kuqala. Iiakhawunti ezihlawulelweyo zisebenzisa iiphakheji ze-quota ezisebenzayo zexesha, emva koko i-quota yethutyana okanye emiselweyo ngokwemigaqo-nkqubo yangasemva.
Xa i-quota iphelile, ukungeniswa komsebenzi kubuyela `429` kwaye kubandakanya umyalezo wemposiso endaweni yokudala umsebenzi omtsha.

I-Cache kunye nokuTsha kweZiphumo

I-backend igcina iziphumo eziphumeleleyo ngokwe-hash yomfanekiso nenguqulelo ye-AI, kuquka i-namespace yenkonzo esezantsi.
`cached_exact` kuthetha ukuba umfanekiso ofanayo sele unesiphumo esiphumeleleyo senguqulelo yangoku ye-AI, ngoko ke akufunekanga kuqhutywe i-AI kwakhona.
`cached_stale` kuthetha ukuba inkonzo ye- AI ayixhunyiwe kwi-intanethi kwaye i-backend ibuyisele iziphumo zembali zamva nje ezikhoyo.
Xa `is_latest_ai_version` ingu-false, gcina isiphumo njengedatha yembali esebenzisekayo kodwa efuna ukuphononongwa.
Musa ukucinga yonke `done` yomsebenzi osetyenzisiweyo; Jonga `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`

Funda umlinganiselo wangoku kunye nokusetyenziswa okuseleyo.

Umzekelo wesicelo

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

Umzekelo wempendulo

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

Funda imeko yenkonzo yoluntu ukuze kungeniswe imisebenzi kwaye kubuyelwe kwiziphumo ze-cache xa inkonzo ingafumaneki.

Umzekelo wesicelo

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

Umzekelo wempendulo

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

Layisha umfanekiso omnye kwaye wenze umsebenzi omnye.

Umzekelo wesicelo

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

Umzekelo wempendulo

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

Funda umsebenzi omnye kunye nokufundwa kokugqibela.

Umzekelo wesicelo

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

Umzekelo wempendulo

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

Funda imisebenzi yakutsha nje yomsebenzisi ongumnini wesitshixo se-API sangoku.

Umzekelo wesicelo

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

Umzekelo wempendulo

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

Layisha imifanekiso emininzi kwisicelo esinye.

Umzekelo wesicelo

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"

Umzekelo wempendulo

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

Funda inkqubela phambili yebhetshi kunye neemeko zomsebenzi wefayile nganye.

Umzekelo wesicelo

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

Umzekelo wempendulo

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

Ukuhamba okucetyiswayo

Khangela `GET /api/open/ai-status` phambi kokuthumela imithwalo emikhulu yomsebenzi.
Gcina `task_id` okanye `batch_id` kwinkqubo yakho kwangoko emva kokungenisa.
Phatha `queued`, `running`, `waiting_ai`, `batch_waiting_ai`, kunye `batch_running` njengeemeko ezingekagqitywa kwaye uqhubeke ujonga imeko rhoqo.
Sebenzisa izicelo zebhetshi xa indlela yenethiwekhi eya kwi-backend ine-latency ephezulu kwaye inkonzo ethunyelweyo ixhasa i-batch mode.
Izicelo zeBatch ngoku zihamba nge- `webBackend -> dispatchCenter -> waterMeterAi`.
`batch_waiting_ai` kuthetha ukuba yonke into isalinde inkonzo ye-AI kwaye ayikaqalisi ukuqhubekekiswa.
Xa inkonzo ethunyelweyo iyi-`CAD`, sebenzisa `POST /api/open/tasks` okwangoku kwaye uphathe ukulayishwa kwebhetshi njengento engafumanekiyo.

Amanqaku ephazamisayo

400: isicelo asivumelekanga, okanye inkonzo ethunyelweyo ayixhasi ukulayishwa kwebhetshi.
401: isitshixo se-API silahlekile, asivumelekanga, siphelelwe lixesha, okanye sivaliwe.
403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
404: umsebenzi okanye ibhetshi ayifumaneki, okanye ayingowomsebenzisi wangoku.
413: ifayile inkulu kakhulu.
415: uhlobo lomfanekiso aluxhaswanga okanye isiqulatho somfanekiso asiqinisekiswanga.
429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.

400 ukulayishwa kwebhetshi akufumaneki

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

401 isitshixo se-API silahlekile okanye asivumelekanga

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

413 ifayile inkulu kakhulu

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

429 i-quota iphelile

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

Ngaba ukulungele ukuvavanya ukuhamba komsebenzi?

Sebenzisa indawo yokusebenzela yewebhu kwifoto yokuqala, emva koko uye kwizitshixo ze-API xa ifomathi yeziphumo ilingana nenkqubo yakho.

Bhalisa kwaye ulayishe ifoto Yenza isitshixo se-API

API ye-OCR yemitha yamanzi

Qala ngokulayisha okwenene

Isishwankathelo

Ubungqina

API Key Permissions and Limits

Imigaqo yokulayisha

Ukunyanzeliswa kobungakanani bokulayisha

Iimeko zomsebenzi

Imithombo yeziphumo

I-Quota kunye ne-Billing

I-Cache kunye nokuTsha kweZiphumo

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}

Ukuhamba okucetyiswayo

Amanqaku ephazamisayo

Ngaba ukulungele ukuvavanya ukuhamba komsebenzi?

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