WaterMeter AI
ChiyankhuloChichewa
Zinenero zina

API ya OCR ya mita ya madzi

API ya OCR ya mita ya madzi. Tsambali lili ndi zolemba za anthu HTTP API zowululidwa ndi tsamba lawebusayiti kuti ziphatikizidwe ndi gulu lina.

Yambani ndi kukweza kwenikweni

Lembani choyamba, kwezani chithunzi chanu cha mita ya madzi pamalo ogwirira ntchito, kenako pangani API kiyi mukakonzeka kuphatikiza.

Lembani ndi Kwezani ChithunziPangani API Kiyi

Mwachidule

  • Gwiritsani ntchito tsamba lakumbuyo la webusayiti pazophatikiza zonse zakunja.
  • Musayimbire waterMeterAi mwachindunji kuchokera ku mapulogalamu ena.
  • Kutsegula API kumagawana ogwiritsa ntchito omwewo, quota, cache, ntchito, ndi malamulo owerengera ngati tsamba lawebusayiti.
  • Backend ikhoza kulunjika ku masevisi osiyanasiyana a AI akumunsi malinga ndi kasinthidwe ka deployment.
  • Mayankho a ntchito ali ndi chinthu cha result_summary kuti masevisi osiyanasiyana athe kuwonetsa mitundu yosiyanasiyana ya zotsatira.

Kutsimikizira

  • Lowani pa webusayiti ndikupanga API kiyi pa API Makiyi atsamba.
  • Kiyi yonse API imawonetsedwa kamodzi kokha ikapangidwa.
  • Tumizani kiyi pamutu wa Authorization pa chilichonse chomwe mukufuna.
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

Malamulo Okwezera

  • Kukula kwakukulu kwa fayilo: 20MB pachithunzi chilichonse.
  • Mitundu yothandizidwa: JPEG, PNG, WEBP.
  • Kumbuyo kumatsimikizira zomwe zili mufayilo, osati kuwonjezera mafayilo.

Kwezani Kulimbikitsa Kukula

  • Kukwezedwa kwamagulu kumavomereza mpaka zithunzi 8 mwachisawawa, zokhala ndi malire a 20MB pachithunzi chilichonse komanso 20MB pazonse zomwe zili mufayilo.
  • Fayilo kapena batchi yomwe idutsa malire ake imabwezeretsa 413 chithunzi chisanatsitsidwe kapena kupanga ntchito; palibe gulu lopangidwa.
  • Kumbuyoku kumakakamiza kuwerengera kwenikweni komwe kwalandilidwa ngakhale Content-Length ikusowa kapena kusamutsa kwachunked kukugwiritsidwa ntchito.

Mikhalidwe ya Ntchito

  • queued: Yavomerezedwa ndipo ikudikirira kukonzedwa ndi AI.
  • running: Ikukonzedwa pano, kapena yaperekedwa kale kwa dispatcher ndipo ikuyang'anabe pafupipafupi kuti ipeze zotsatira zomaliza.
  • batch_waiting_ai: Chinthu chilichonse m'gulu chikudikirira sevisi ya AI kuti ibwerenso pa intaneti.
  • batch_running: Gulu laperekedwa kale kwa dispatcher ndipo likukonzedwabe.
  • done: Yatha bwino.
  • failed: Kukonza kwalephera.
  • waiting_ai: Ili pamzere mpaka sevisi ya AI ibwerenso pa intaneti, kenako ipitiriza yokha.

Zotsatira

  • fresh: Zapangidwa ndi kukonza kwatsopano kwa AI.
  • cached_exact: Zafanana ndi cache ya mtundu wa AI wapano.
  • cached_stale: AI ilibe intaneti, ndipo zotsatira zaposachedwa zosungidwa zabwezedwa.
  • pending: Palibe zotsatira zomaliza panobe.
  • failed: Ntchitoyo yalephera.
  • Ntchito ikakhala kuti sinachitike, yang'anani error_message kuti muyesenso kapena chifukwa chodikirira.

Gawo ndi Kulipira

  • Gwiritsani ntchito `GET /api/open/quota` musanatumize ntchito zazikulu ngati kuphatikiza kwanu kuyenera kupewa kulephera kwa magawo.
  • `fresh` AI ndiyomwe imagwiritsa ntchito chiwerengero.
  • `cached_exact`, `cached_stale`, `pending`, ndi `failed` zotsatira sizimatengera gawo.
  • Maakaunti aulere amagwiritsa ntchito kuchuluka kwatsiku ndi tsiku poyamba. Maakaunti olipidwa amagwiritsa ntchito paketi yanthawi ndi nthawi, kenako magawo osakhalitsa kapena okhazikika malinga ndi mfundo za backend.
  • Chigawo chikatha, kutumiza ntchito kumabweza `429` ndipo kumaphatikizapo uthenga wolakwika m'malo mopanga ntchito yatsopano.

Cache ndi Zotsatira Zatsopano

  • Backend imasunga zotsatira zopambana molingana ndi hash ya chithunzi ndi mtundu wa AI, kuphatikizapo namespace ya sevisi yakumunsi.
  • `cached_exact` zikutanthauza kuti chithunzi chomwechi chili kale ndi zotsatira zopambana za mtundu wa AI wapano, choncho kukonza kwatsopano kwa AI sikunafunike.
  • `cached_stale` zikutanthauza kuti sevisi ya AI ilibe intaneti ndipo backend yabweza zotsatira zaposachedwa za m'mbuyomu.
  • Pamene `is_latest_ai_version` ndi false, sungani zotsatira ngati mbiri yogwiritsidwa ntchito koma yofunika kuunikanso.
  • Osatengera `done` ntchito iliyonse yomwe mwatenga; onani `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

Werengani kuchuluka komwe kulipo komanso kugwiritsa ntchito kotsala.

Funsani Chitsanzo
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Yankho Chitsanzo
{
  "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

Werengani momwe sevisi ya anthu onse ilili kuti mutumize ntchito ndi kugwiritsa ntchito zotsatira zosungidwa ngati sevisi palibe.

Funsani Chitsanzo
curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Yankho Chitsanzo
{
  "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

Kwezani chithunzi chimodzi ndikupanga ntchito imodzi.

Funsani Chitsanzo
curl -X POST "https://watermeterai.com/api/open/tasks" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \
  -F "file=@D:\data\meter_001.jpg"
Yankho Chitsanzo
{
  "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}

Werengani ntchito imodzi ndikuwerenga komaliza.

Funsani Chitsanzo
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Yankho Chitsanzo
{
  "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

Werengani ntchito zaposachedwa za wogwiritsa ntchito yemwe ali ndi API key yapano.

Funsani Chitsanzo
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Yankho Chitsanzo
{
  "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

Kwezani zithunzi zingapo mukupempha kumodzi.

Funsani Chitsanzo
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"
Yankho Chitsanzo
{
  "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}

Werengani momwe gulu likuyendera komanso momwe fayilo ikuyendera.

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

Mayendedwe Ovomerezeka

  • Yang'anani `GET /api/open/ai-status` musanatumize ntchito zazikulu.
  • Sungani `task_id` kapena `batch_id` m'dongosolo lanu mukangotumiza.
  • Onani `queued`, `running`, `waiting_ai`, `batch_waiting_ai`, ndi `batch_running` ngati mikhalidwe yosamaliza ndipo pitirizani kuyang'ana momwe zilili pafupipafupi.
  • Gwiritsani ntchito zopempha za batch pamene njira ya netiweki yopita ku backend ili ndi latency yayikulu ndipo sevisi yomwe yatumizidwa imathandizira batch mode.
  • Zopempha zamagulu zimadutsa pa `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` zikutanthauza kuti chinthu chilichonse chikudikirirabe sevisi ya AI ndipo sichinayambe kukonzedwa.
  • Pamene sevisi yomwe yatumizidwa ili `CAD`, gwiritsani ntchito `POST /api/open/tasks` pakalipano ndipo onani kukweza batch ngati kosapezeka.

Zolemba Zolakwika

  • 400: pempho lolakwika, kapena sevisi yomwe yatumizidwa siyithandizira kukweza batch.
  • 401: API key ikusowa, ndi yolakwika, yatha ntchito, kapena yayimitsidwa.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: ntchito kapena gulu silinapezeke, kapena si la wogwiritsa ntchito pano.
  • 413: fayilo yayikulu kwambiri.
  • 415: mtundu wazithunzi zosagwiritsidwa ntchito kapena zithunzi zolakwika.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 kukwezedwa kwamagulu sikukupezeka
{
  "detail": "batch upload is not supported for business: cax"
}
401 makiyi akusowa kapena osalondola API
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 fayilo ndi yayikulu kwambiri
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 gawo latha
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Mwakonzeka kuyesa kayendedwe ka ntchito?

Gwiritsani ntchito tsamba lawebusayiti pachithunzi choyambirira, kenako sunthirani ku API makiyi akapeza mtundu wazotsatira wanu.

Lembani ndi Kwezani ChithunziPangani API Kiyi