WaterMeter AI
WikaFilipino
Iba pang mga wika

water meter OCR API

water meter OCR API. Ang pahinang ito ay nagdodokumento ng pampublikong HTTP API na inilantad ng backend ng website para sa mga pagsasama ng third-party.

Magsimula sa isang tunay na pag-upload

Magrehistro muna, mag-upload ng sarili mong larawan ng metro ng tubig sa workspace, at pagkatapos ay gumawa ng API key kapag handa ka nang magsama.

Magrehistro at Mag-upload ng LarawanGumawa ng API Key

Pangkalahatang-ideya

  • Gamitin ang backend ng website para sa lahat ng panlabas na pagsasama.
  • Huwag tumawag sa waterMeterAi nang direkta mula sa mga third-party na programa.
  • Ang bukas na API ay nagbabahagi ng parehong mga user, quota, cache, mga gawain, at mga panuntunan sa pag-audit gaya ng web portal.
  • Maaaring mag-target ang backend ng iba't ibang downstream na serbisyo ng AI sa pamamagitan ng deployment config.
  • Kasama na ngayon sa mga tugon sa gawain ang generic na object na result_summary upang makapagpakita ang iba't ibang serbisyo ng iba't ibang uri ng resulta.

Pagpapatunay

  • Mag-sign in sa website at gumawa ng API key sa page na API Keys.
  • Ang buong API key ay ipinapakita nang isang beses lamang kapag ito ay ginawa.
  • Ipadala ang susi sa Authorization header sa bawat kahilingan.
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

Mga Panuntunan sa Pag-upload

  • Pinakamataas na laki ng file: 20MB bawat larawan.
  • Mga sinusuportahang format: JPEG, PNG, WEBP.
  • Ang backend ay nagpapatunay ng aktwal na nilalaman ng file, hindi lamang ang extension ng file.

Pagpapatupad ng Laki ng Upload

  • Ang mga batch na pag-upload ay tumatanggap ng hanggang 8 larawan bilang default, na may 20MB na limitasyon sa bawat larawan at 20MB sa kabuuang limitasyon sa nilalaman ng file.
  • Ang isang file o batch na lumampas sa limitasyon nito ay nagbabalik ng 413 bago ang pagpapatunay ng larawan o paggawa ng gawain; walang partial batch na nalilikha.
  • Ipinapatupad ng backend ang aktwal na natanggap na bilang ng byte kahit na nawawala ang Content-Length o ginagamit ang chunked transfer.

Mga Estado ng Gawain

  • nakapila: tinanggap at naghihintay para sa pagproseso ng AI.
  • tumatakbo: kasalukuyang pinoproseso, o ipinasa na sa dispatcher at pana-panahong sinusuri pa rin para sa huling resulta.
  • batch_waiting_ai: bawat item sa batch ay naghihintay para sa serbisyong AI na bumalik online.
  • batch_running: ang batch ay ipinasa na sa dispatcher at pinoproseso pa rin.
  • tapos na: matagumpay na natapos.
  • nabigo: nabigo ang pagproseso.
  • waiting_ai: nakapila hanggang sa bumalik ang serbisyong AI online, pagkatapos ay awtomatiko itong magpapatuloy.

Mga Pinagmumulan ng Resulta

  • bago: nabuo ng isang bagong AI run.
  • cached_exact: tumugma sa kasalukuyang AI na bersyon ng cache.
  • cached_stale: AI offline, ibinalik ang pinakabagong naka-cache na resulta.
  • nakabinbin: wala pang huling resulta.
  • nabigo: nabigo ang gawain.
  • Kapag ang isang gawain ay hindi pa tapos, suriin ang error_message para sa pinakabagong muling pagsubok o paghihintay na dahilan.

Quota at Pagsingil

  • Gamitin ang `GET /api/open/quota` bago magsumite ng malalaking workload kung kailangan ng iyong integration na maiwasan ang mga pagkabigo sa quota.
  • Ang `fresh` AI lang ang tumatakbo sa quota.
  • Ang mga resulta ng `cached_exact`, `cached_stale`, `pending`, at `failed` ay hindi kumukuha ng quota.
  • Ginagamit muna ng mga libreng account ang pang-araw-araw na quota. Gumagamit ang mga bayad na account ng mga aktibong periodic quota packages, pagkatapos ay pansamantala o fixed quota ayon sa backend policy.
  • Kapag naubos na ang quota, ang pagsusumite ng gawain ay nagbabalik ng `429` at may kasamang mensahe ng error sa halip na gumawa ng bagong gawain.

Cache at pagiging bago ng Resulta

  • Nagka-cache ang backend ng mga matagumpay na resulta ayon sa image hash at bersyon ng AI, kasama ang namespace ng downstream na serbisyo.
  • Ang ibig sabihin ng `cached_exact` ay ang parehong larawan ay mayroon nang matagumpay na resulta para sa kasalukuyang bersyon ng AI, kaya hindi na kailangan ng bagong AI run.
  • Ang ibig sabihin ng `cached_stale` ay offline ang serbisyo ng AI at ibinalik ng backend ang pinakabagong available na makasaysayang resulta.
  • Kapag mali ang `is_latest_ai_version`, iimbak ang resulta bilang magagamit ngunit masusuri na makasaysayang data.
  • Huwag ipagpalagay na ang bawat `done` gawain ay naubos na quota; suriin ang `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

Basahin ang kasalukuyang quota at natitirang paggamit.

Halimbawa ng Kahilingan
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Halimbawa ng Tugon
{
  "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

Basahin ang katayuan ng serbisyong pampubliko para sa pagsusumite ng gawain at fallback ng naka-cache na resulta.

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

Mag-upload ng isang larawan at lumikha ng isang gawain.

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

Basahin ang isang katayuan ng gawain at huling pagbasa.

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

Basahin ang mga kamakailang gawain na pagmamay-ari ng kasalukuyang API key user.

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

Mag-upload ng maraming larawan sa isang kahilingan.

Halimbawa ng Kahilingan
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"
Halimbawa ng Tugon
{
  "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}

Basahin ang pag-unlad ng batch at mga estado ng gawain sa bawat file.

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

Inirerekomendang Daloy

  • Suriin ang `GET /api/open/ai-status` bago magpadala ng malalaking workload.
  • I-store ang `task_id` o `batch_id` sa sarili mong system kaagad pagkatapos isumite.
  • Ituring ang `queued`, `running`, `waiting_ai`, `batch_waiting_ai`, at `batch_running` bilang mga hindi pangwakas na estado at ipagpatuloy ang pana-panahong pagsuri ng katayuan.
  • Gumamit ng mga batch request kapag mataas ang latency ng network path sa backend at sinusuportahan ng na-deploy na serbisyo ang batch mode.
  • Ang mga batch na kahilingan ay kasalukuyang dumadaloy sa `webBackend -> dispatchCenter -> waterMeterAi`.
  • Ang ibig sabihin ng `batch_waiting_ai` ay naghihintay pa rin ang bawat item para sa serbisyong AI, hindi pa aktibong tumatakbo.
  • Kapag ang naka-deploy na serbisyo ay `CAD`, gamitin muna ang `POST /api/open/tasks` at ituring na hindi available ang batch upload.

Mga Tala ng Error

  • 400: di-wastong kahilingan, o hindi sinusuportahan ng naka-deploy na serbisyo ang batch upload.
  • 401: nawawala, di-wasto, nag-expire, o hindi pinagana ang API key.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: hindi nahanap ang gawain o batch, o hindi pagmamay-ari ng kasalukuyang user.
  • 413: masyadong malaki ang file.
  • 415: hindi sinusuportahang uri ng larawan o di-wastong nilalaman ng larawan.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
Hindi available ang 400 batch na pag-upload
{
  "detail": "batch upload is not supported for business: cax"
}
401 nawawala o di-wastong API key
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 file ay masyadong malaki
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 quota naubos
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Handa nang subukan ang daloy ng trabaho?

Gamitin ang web workspace para sa unang larawan, pagkatapos ay lumipat sa API key kapag ang format ng resulta ay umaangkop sa iyong system.

Magrehistro at Mag-upload ng LarawanGumawa ng API Key