WaterMeter AI
FitenyMalagasy
Fiteny hafa

API OCR ho an’ny metatra rano

API OCR ho an’ny metatra rano. Ity pejy ity dia mirakitra ny HTTP API ho an'ny daholobe amin'ny alàlan'ny tranonkala backend ho an'ny fampidirana antoko fahatelo.

Atombohy amin'ny fampidirana tena izy

Misoratra anarana aloha, ampidiro ny sarin'ny fandrefesana rano ao amin'ny toeram-piasana, ary avy eo mamorona fanalahidy API rehefa vonona ny hampiditra ianao.

Misoratra anarana ary ampidiro ny saryMamorona fanalahidy API

Topimaso

  • Ampiasao ny backend an'ny tranokala ho an'ny fampidirana ivelany rehetra.
  • Aza miantso waterMeterAi mivantana avy amin'ny programa antoko fahatelo.
  • Ny API misokatra dia mizara ny mpampiasa, quota, cache, asa ary fitsipika fanaraha-maso mitovy amin'ny vavahadin-tserasera.
  • Ny backend dia afaka mifandray amin'ny serivisy AI ambany samihafa arakaraka ny fikirakirana fametrahana.
  • Ny valin'ny asa dia misy zavatra result_summary ankapobeny mba hahafahan'ny serivisy samihafa mampiseho karazana vokatra samihafa.

Fanamarinana

  • Midira ao amin'ny tranokala ary mamorona fanalahidy API ao amin'ny pejy API Keys.
  • Ny fanalahidin'ny API feno dia aseho indray mandeha ihany rehefa noforonina.
  • Alefaso ao amin'ny lohateny Authorization ny fanalahidy isaky ny fangatahana.
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

Fitsipika fampidirana

  • Haben'ny rakitra ambony indrindra: 20MB isaky ny sary.
  • Format tohana: JPEG, PNG, WEBP.
  • Ny backend dia manamarina ny votoatin'ny rakitra tena izy, fa tsy ny fanitarana rakitra fotsiny.

Fampiharana ny haben'ny fampidirana

  • Ny fampiakarana andiany dia manaiky hatramin'ny sary 8 amin'ny alàlan'ny default, miaraka amin'ny fetra 20MB isaky ny sary ary fetran'ny votoatin'ny rakitra 20MB.
  • Ny rakitra na andiany izay mihoatra ny fetrany dia miverina 413 alohan'ny fanamarinana sary na famoronana asa; Tsy misy ampahany amin'ny andiany noforonina.
  • Ny backend dia mampihatra ny isan'ny byte voaray na dia tsy hita aza ny Content-Length na ny famindrana chunked ampiasaina.

Satan'ny asa

  • queued: Nekena ary miandry ny fanodinana AI.
  • running: Eo am-panodinana izao, na efa natolotra ny dispatcher ary mbola jerena tsy tapaka ny sata hahazoana ny vokatra farany.
  • batch_waiting_ai: Ny singa rehetra ao amin'ny andiany dia miandry ny fiverenan'ny serivisy AI an-tserasera.
  • batch_running: Efa natolotra ny dispatcher ny andiany ary mbola eo am-panodinana.
  • done: Vita soa aman-tsara.
  • failed: Tsy nahomby ny fanodinana.
  • waiting_ai: Milahatra mandra-piverin'ny serivisy AI an-tserasera, avy eo mitohy ho azy.

Loharanon'ny vokatra

  • fresh: Noforonin'ny fanodinana AI vaovao.
  • cached_exact: Mifanaraka amin'ny cache an'ny kinova AI ankehitriny.
  • cached_stale: Tsy an-tserasera ny AI ka naverina ny vokatra farany voatahiry.
  • pending: Mbola tsy misy vokatra farany.
  • failed: Tsy nahomby ny asa.
  • Rehefa mbola tsy vita ny asa iray dia jereo error_message ho an'ny antony farany amin'ny fanandramana na ny fiandrasana.

quota sy faktiora

  • Ampiasao `GET /api/open/quota` alohan'ny handefasana asa lehibe raha mila misoroka ny tsy fahombiazan'ny quota ny fampidiranao.
  • Ny `fresh` AI ihany no mandany quota.
  • `cached_exact`, `cached_stale`, `pending`, ary `failed` vokatra dia tsy mandany quota.
  • Ny kaonty maimaim-poana dia mampiasa ny quota isan'andro aloha. Ny kaonty karama dia mampiasa fonosana quota ara-potoana mavitrika, avy eo quota vonjimaika na raikitra araka ny politika backend.
  • Rehefa lany ny quota, dia miverina `429` ny fandefasana asa ary misy hafatra diso fa tsy mamorona asa vaovao.

Cache sy vokatra vaovao

  • Ny backend dia mitahiry vokatra mahomby araka ny hash-n'ny sary sy ny kinova AI, anisan'izany ny namespace an'ny serivisy ambany.
  • `cached_exact` dia midika fa efa manana vokatra mahomby amin'ny kinova AI ankehitriny ilay sary mitovy, ka tsy nilaina ny fanodinana AI vaovao.
  • `cached_stale` midika izany fa ny serivisy AI dia ivelan'ny aterineto ary ny backend dia namerina ny vokatra ara-tantara farany misy.
  • Raha false ny `is_latest_ai_version`, tehirizo ho angona ara-tantara azo ampiasaina nefa mbola mila dinihina ilay vokatra.
  • Aza mihevitra ny quota lany amin'ny asa `done` rehetra; jereo `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

Vakio ny quota amin'izao fotoana izao sy ny fampiasana sisa.

Fangatahana ohatra
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Ohatra valinteny
{
  "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

Vakio ny satan'ny serivisy ho an'ny daholobe mba handefasana asa sy hampiasana vokatra voatahiry rehefa tsy misy ny serivisy.

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

Ampidiro ny sary iray ary mamorona asa tokana.

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

Vakio ny satan'ny asa iray sy ny famakiana farany.

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

Vakio ny asa vao haingana an'ny mpampiasa tompon'ny fanalahidy API ankehitriny.

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

Ampidiro sary maromaro ao anatin'ny fangatahana iray.

Fangatahana ohatra
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"
Ohatra valinteny
{
  "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}

Vakio ny fandrosoan'ny andiany sy ny toe-javatra isaky ny rakitra.

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

Fizotran'asa atolotra

  • Jereo `GET /api/open/ai-status` alohan'ny handefasana asa lehibe.
  • Tehirizo `task_id` na `batch_id` ao amin'ny rafitrao avy hatrany aorian'ny fandefasana.
  • Raiso ho sata mbola tsy farany ny `queued`, `running`, `waiting_ai`, `batch_waiting_ai`, ary `batch_running`, ary tohizo ny fanamarinana tsy tapaka ny sata.
  • Ampiasao ny fangatahana batch rehefa avo ny fahataran'ny tambajotra mankany amin'ny backend ary manohana ny fomba batch ny serivisy napetraka.
  • Ny fangatahana batch amin'izao fotoana izao dia mivezivezy amin'ny `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` dia midika fa mbola miandry ny serivisy AI ny singa rehetra, fa tsy mbola eo am-panodinana.
  • Rehefa `CAD` ny serivisy napetraka, ampiasao aloha ny `POST /api/open/tasks` ary raiso ho tsy misy ny fampidirana batch.

Fanamarihana momba ny fahadisoana

  • 400: fangatahana tsy manan-kery, na tsy manohana ny fampidirana batch ny serivisy napetraka.
  • 401: fanalahidy API tsy hita, tsy manan-kery, lany andro, na najanona.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: asa na andiany tsy hita, na tsy an'ny mpampiasa ankehitriny.
  • 413: rakitra lehibe loatra.
  • 415: karazana sary tsy tohanana na votoatin'ny sary tsy manan-kery.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 tsy misy ny fampidirana andiany
{
  "detail": "batch upload is not supported for business: cax"
}
401 famaha API tsy hita na tsy manan-kery
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 rakitra lehibe loatra
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 lany ny quota
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Vonona ny hizaha toetra ny fizotran'ny asa?

Ampiasao ny sehatr'asa amin'ny tranonkala ho an'ny sary voalohany, avy eo mifindra any amin'ny fanalahidy API raha vao mifanaraka amin'ny rafitrao ny endrika vokatra.

Misoratra anarana ary ampidiro ny saryMamorona fanalahidy API