WaterMeter AI
UlimiisiZulu
Ezinye izilimi

Imitha yamanzi OCR API

Imitha yamanzi OCR API. Leli khasi libhala HTTP API yomphakathi evezwe yi-backend yewebhusayithi yokuhlanganiswa kweqembu lesithathu.

Qala ngokulayisha kwangempela

Bhalisa kuqala, ulayishe isithombe sakho semitha yamanzi endaweni yokusebenzela, bese udala ukhiye we- API lapho usukulungele ukuhlanganisa.

Bhalisa bese ulayisha isithombeYakha ukhiye API

Ukubuka konke

  • Sebenzisa iwebhusayithi ye-backend kukho konke ukuhlanganiswa kwangaphandle.
  • Ungashayeli waterMeterAi ngqo kusuka ezinhlelweni zeqembu lesithathu.
  • I- API evulekile yabelana ngabasebenzisi abafanayo, i-quota, i-cache, imisebenzi, nemithetho yokucwaninga kwewebhu njenge-portal yewebhu.
  • I-backend ingasebenzisa amasevisi e-AI ahlukene angezansi ngokusekelwe ku-deployment config.
  • Izimpendulo zomsebenzi zifaka into ejwayelekile ye-result_summary ukuze amasevisi ahlukene akwazi ukubonisa izinhlobo ezahlukene zemiphumela.

Ukuqinisekiswa

  • Ngena ngemvume kuwebhusayithi bese udala ukhiye we- API ekhasini le- API Keys.
  • Ukhiye ophelele we- API uboniswa kanye kuphela lapho udalwa.
  • Thumela ukhiye esihlokweni se-Authorization kuso sonke isicelo.
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

Imithetho yokulayisha

  • Usayizi wefayela eliphezulu: 20MB ngesithombe ngasinye.
  • Amafomethi asekelwe: JPEG, PNG, WEBP.
  • I-backend iqinisekisa okuqukethwe kwefayela langempela, hhayi nje isalulo sefayela.

Ukulayisha Usayizi Wokuphoqelelwa

  • Ukulayishwa kwe-batch kwamukela izithombe ezifinyelela ku-8 ngokuzenzakalelayo, ngomkhawulo we-20MB wesithombe ngasinye kanye nomkhawulo we-20MB ophelele wokuqukethwe kwefayela.
  • Ifayela noma i-batch edlula umkhawulo wayo ibuyisela 413 ngaphambi kokuqinisekiswa kwesithombe noma ukudalwa komsebenzi; Ayikho i-batch engxenyeni eyenziwe.
  • I-backend iphoqelela ukubalwa kwe-byte yangempela etholwe ngisho nalapho i-Content-Length ilahlekile noma ukudluliswa kwe-chunked kusetshenziswa.

Izimo Zomsebenzi

  • queued: Kwamukelwe futhi kulinde ukucutshungulwa yi-AI.
  • running: Kuyacutshungulwa manje, noma sekunikezwe i-dispatcher futhi isimo sisahlolwa njalo ukuze kutholakale umphumela wokugcina.
  • batch_waiting_ai: Yonke into eku-batch ilindele isevisi ye-AI ukuthi ibuyele ku-inthanethi.
  • batch_running: I-batch isivele inikezwe i-dispatcher futhi isacutshungulwa.
  • done: Kuqedwe ngempumelelo.
  • failed: Ukucutshungulwa kwehlulekile.
  • waiting_ai: Kusemgqeni kuze kube yilapho isevisi ye-AI ibuya ku-inthanethi, bese kuqhubeka ngokuzenzakalelayo.

Imithombo Yemiphumela

  • fresh: Kukhiqizwe ukucutshungulwa okusha kwe-AI.
  • cached_exact: Kuhambisana ne-cache yenguqulo ye-AI yamanje.
  • cached_stale: I-AI ayixhunyiwe ku-inthanethi, ngakho kubuyiswe umphumela wakamuva ogcinwe ku-cache.
  • pending: Awukho umphumela wokugcina okwamanje.
  • failed: Umsebenzi wehlulekile.
  • Uma umsebenzi ungakaqedwa, hlola error_message wokuzama kabusha kwakamuva noma isizathu sokulinda.

I-Quota kanye nokukhokhiswa

  • Sebenzisa `GET /api/open/quota` ngaphambi kokuhambisa imithwalo emikhulu uma ukuhlanganiswa kwakho kudinga ukugwema ukwehluleka kwe-quota.
  • Ama-runs `fresh` AI kuphela adla i-quota.
  • `cached_exact`, `cached_stale`, `pending`, futhi imiphumela `failed` ayidli i-quota.
  • Ama-akhawunti wamahhala asebenzisa i-quota yansuku zonke kuqala. Ama-akhawunti akhokhelwayo asebenzisa amaphakheji we-quota asebenzayo ngezikhathi ezithile, bese kuthi i-quota yesikhashana noma ehleliwe ngokuya ngenqubomgomo ye-backend.
  • Lapho isilinganiso sesiphelile, ukulethwa komsebenzi kubuyela `429` futhi kufaka umyalezo wephutha esikhundleni sokudala umsebenzi omusha.

I-Cache Nobusha Bomphumela

  • I-backend igcina imiphumela ephumelelayo ngokwe-hash yesithombe nenguqulo ye-AI, kufaka phakathi i-namespace yesevisi engezansi.
  • `cached_exact` kusho ukuthi isithombe esifanayo sesivele sinomphumela ophumelelayo wenguqulo yamanje ye-AI, ngakho ukucutshungulwa okusha kwe-AI akudingekanga.
  • `cached_stale` kusho ukuthi isevisi ye- AI ayixhunyiwe ku-inthanethi futhi i-backend ibuyisele umphumela wakamuva womlando otholakalayo.
  • Lapho `is_latest_ai_version` kungu-false, gcina umphumela njengedatha yomlando esebenzisekayo kodwa edinga ukubuyekezwa.
  • Ungacabangi wonke umsebenzi `done` okudliwe quota; hlola `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 i-quota yamanje nokusetshenziswa okusele.

Isibonelo sokucela
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Isibonelo sempendulo
{
  "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 isimo sesevisi yomphakathi ukuze kuthunyelwe imisebenzi futhi kusetshenziswe imiphumela ye-cache uma isevisi ingatholakali.

Isibonelo sokucela
curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Isibonelo sempendulo
{
  "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 isithombe esisodwa bese udala umsebenzi owodwa.

Isibonelo sokucela
curl -X POST "https://watermeterai.com/api/open/tasks" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \
  -F "file=@D:\data\meter_001.jpg"
Isibonelo sempendulo
{
  "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 isimo somsebenzi owodwa nokufundwa kokugcina.

Isibonelo sokucela
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Isibonelo sempendulo
{
  "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 yakamuva yomsebenzisi ophethe ukhiye we-API wamanje.

Isibonelo sokucela
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Isibonelo sempendulo
{
  "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 izithombe eziningi ngesicelo esisodwa.

Isibonelo sokucela
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"
Isibonelo sempendulo
{
  "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 inqubekela phambili ye-batch kanye nezimo zomsebenzi wefayela ngalinye.

Isibonelo sokucela
curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Isibonelo sempendulo
{
  "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": ""
    }
  ]
}

Ukugeleza Okunconyiwe

  • Hlola `GET /api/open/ai-status` ngaphambi kokuthumela imithwalo emikhulu yomsebenzi.
  • Gcina `task_id` noma `batch_id` ohlelweni lwakho ngokushesha ngemuva kokuthunyelwa.
  • Phatha `queued`, `running`, `waiting_ai`, `batch_waiting_ai`, kanye `batch_running` njengezimo ezingakapheli futhi uqhubeke uhlola isimo njalo.
  • Sebenzisa izicelo ze-batch lapho indlela yenethiwekhi eya ku-backend ine-latency ephezulu futhi isevisi esetshenzisiwe isekela i-batch mode.
  • Izicelo ze-batch njengamanje zihamba nge- `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` kusho ukuthi yonke into isalinde isevisi ye-AI futhi ayikaqali ukucutshungulwa.
  • Lapho isevisi ethunyelwe ingu-`CAD`, sebenzisa `POST /api/open/tasks` okwamanje futhi uphathe ukulayishwa kwe-batch njengokungatholakali.

Amanothi wephutha

  • 400: isicelo asivumelekile, noma isevisi ethunyelwe ayisekeli ukulayishwa kwe-batch.
  • 401: ukhiye we-API ulahlekile, awuvumelekile, uphelelwe yisikhathi, noma ukhutshaziwe.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: umsebenzi noma i-batch ayitholakali, noma akuyona eyomsebenzisi wamanje.
  • 413: ifayela likhulu kakhulu.
  • 415: uhlobo lwesithombe olungaxhasiwe noma okuqukethwe kwesithombe okungaqinisekisiwe.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 ukulayishwa kweqoqo akutholakali
{
  "detail": "batch upload is not supported for business: cax"
}
401 ukhiye we-API ulahlekile noma awuvumelekile
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 ifayela likhulu kakhulu
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 i-quota isiphelile
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Ukulungele ukuhlola ukugeleza komsebenzi?

Sebenzisa indawo yokusebenzela yewebhu esithombeni sokuqala, bese udlulela kokhiye be-API uma ifomethi yomphumela ilingana nesistimu yakho.

Bhalisa bese ulayisha isithombeYakha ukhiye API