WaterMeter AI
LuqaddaSoomaali
Luqado kale

API-ga OCR ee mitirka biyaha

API-ga OCR ee mitirka biyaha. Boggan wuxuu diiwaangelinayaa HTTP API dadweynaha ee ay soo bandhigto dhinaca dambe ee website-ka si loo helo isku-darka dhinac saddexaad.

Bilow soo gelin dhab ah

Iska diiwaangeli marka hore, sawirkaaga cabbirka biyaha geli goobta shaqada, kadibna samee furaha API markaad diyaar u tahay inaad isku darto.

Iska diiwaangeli oo sawir geliSamee furaha API

Guudmar

  • Isticmaal dhinaca dambe ee website-ka dhammaan isku-darka dibadda.
  • Ha wicin waterMeterAi si toos ah barnaamijyada dhinac saddexaad.
  • Furan API waxay wadaagaan isla isticmaalayaasha, quota, cache, hawlaha, iyo xeerarka kormeerka sida web-portal-ka.
  • Backend-ku wuxuu la xiriiri karaa adeegyo kala duwan oo AI ah oo hoose iyadoo lagu salaynayo deployment configuration.
  • Jawaabaha hawluhu waxay leeyihiin shay result_summary guud si adeegyo kala duwan ay u muujiyaan noocyo natiijo oo kala duwan.

Xaqiijinta

  • Gali website-ka oo samee furaha API bogga API Keys.
  • Furaha buuxa ee API waxaa la tusayaa hal mar oo kaliya marka la abuuro.
  • U dir furaha cinwaanka Authorization codsi kasta.
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

Xeerarka Soo Dirista

  • Cabbirka ugu badan ee faylka: 20MB sawirkiiba.
  • Qaababka la taageeray: JPEG, PNG, WEBP.
  • Backend-ku wuxuu xaqiijiyaa waxa dhabta ah ee faylka, ma aha oo kaliya file extension-ka.

Kormeerka Cabbirka Soo Dirista

  • Soo gelinta xirmooyinka waxay aqbalaan ilaa 8 sawir sida caadiga ah, iyadoo xaddidan 20MB sawir kasta iyo xad guud oo faylka ah 20MB.
  • Fayl ama xirmo ka badan xadka uu leeyahay wuxuu soo celiyaa 413 ka hor xaqiijinta sawirka ama abuurista hawsha; Qayb qayb ah lama sameeyo.
  • Backend-ku wuxuu ku qasbaa tirada byte-yada la helay xitaa marka Content-Length maqan yahay ama la isticmaalo chunked transfer.

Xaaladaha Hawsha

  • queued: Waa la aqbalay oo waxay sugaysaa habaynta AI.
  • running: Hadda waa la habaynayaa, ama hore ayaa loogu wareejiyay dispatcher-ka iyadoo weli xaaladda si joogto ah loo hubinayo si loo helo natiijada ugu dambaysa.
  • batch_waiting_ai: Shay kasta oo xirmada ku jira wuxuu sugayaa adeegga AI inuu dib ugu soo laabto online.
  • batch_running: Xirmada hore ayaa loogu wareejiyay dispatcher-ka welina waa la habaynayaa.
  • done: Si guul leh ayay u dhammaatay.
  • failed: Habayntu way fashilantay.
  • waiting_ai: Waxay ku jirtaa saf ilaa adeegga AI uu dib ugu soo laabto online, ka dibna si toos ah ayay u sii socotaa.

Ilo Natiijooyin

  • fresh: Waxaa soo saaray habayn cusub oo AI ah.
  • cached_exact: Waxay la mid tahay cache-ka nooca AI ee hadda.
  • cached_stale: AI-gu waa offline, waxaana la soo celiyay natiijadii ugu dambaysay ee cache-ka.
  • pending: Weli ma jirto natiijo kama dambays ah.
  • failed: Hawshu way fashilantay.
  • Marka hawl aan weli la dhammeeyo, error_message eeg sababta ugu dambeysay ee dib loo isku dayo ama sugitaanka.

Quota iyo Biilasha

  • Isticmaal `GET /api/open/quota` ka hor intaadan gudbin shaqo weyn haddii isku-darkaagu u baahan yahay inuu ka fogaado fashilka quota-ga.
  • Kaliya `fresh` AI orod ayaa isticmaala quota.
  • `cached_exact`, `cached_stale`, `pending`, iyo natiijooyinka `failed` ma isticmaalaan quota.
  • Akoonnada bilaashka ah marka hore isticmaal qiyaasta maalinlaha ah. Akoonnada lacagta la bixiyay waxay isticmaalaan xirmooyin kooban oo firfircoon oo joogto ah, kadibna quota ku-meel-gaar ah ama go'an sida ku cad siyaasadda backend-ka.
  • Marka quota la dhammeeyo, soo gudbinta hawsha waxay soo `429` waxayna ku dartaa fariin qalad ah halkii laga abuuri lahaa hawl cusub.

Kaydka iyo Cusbaynaanta Natiijada

  • Backend-ku wuxuu kaydiyaa natiijooyinka guulaystay iyadoo lagu salaynayo hash-ka sawirka iyo nooca AI, oo ay ku jirto namespace-ka adeegga hoose.
  • `cached_exact` waxay ka dhigan tahay in isla sawirkaasi hore u lahaa natiijo guul leh oo nooca AI ee hadda ah, sidaas darteed habayn cusub oo AI ah looma baahnayn.
  • `cached_stale` macnaheedu yahay in adeegga AI uu offline yahay, backend-kuna wuxuu soo celiyay natiijada taariikhiga ah ee ugu dambeysay ee la heli karo.
  • Marka `is_latest_ai_version` ay tahay false, natiijada u kaydi xog taariikheed la isticmaali karo balse dib loo eegi karo.
  • Ha u maleynin in hawl kasta oo `done` uu qaato qiyaasta; hubi `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

Akhri qiyaasta hadda iyo isticmaalka hadhay.

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

Akhri xaaladda adeegga dadweynaha si hawlo loo gudbiyo, looguna noqdo natiijooyinka cache-ka marka adeeggu maqan yahay.

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

Soo geli hal sawir oo samee hal hawl.

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

Akhri hal hawl iyo akhrinta ugu dambeysa.

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

Akhri hawlaha ugu dambeeyay ee uu leeyahay isticmaalaha hadda ee furaha API .

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

Soo geli sawirro badan hal codsi gudaheed.

Tusaalaha codsiga
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"
Tusaalaha Jawaabta
{
  "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}

Akhri horumarka batch-ka iyo xaaladaha hawlaha faylka kasta.

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

Socodka Lagu Taliyay

  • Hubi `GET /api/open/ai-status` ka hor intaadan dirin shaqo badan.
  • Kaydi `task_id` ama `batch_id` nidaamkaaga isla markiiba kadib gudbinta.
  • U tixgeli `queued`, `running`, `waiting_ai`, `batch_waiting_ai`, iyo `batch_running` xaalado aan dhammaad ahayn, xaaladdana si joogto ah u hubi.
  • Isticmaal codsiyada batch-ka marka waddada shabakadda ee backend-ku leedahay latency sare oo adeegga la dejiyay uu taageero batch mode.
  • Codsiyada xirmada hadda waxay maraan `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` waxay ka dhigan tahay in shay kasta weli sugayo adeegga AI oo aanu weli si firfircoon u socon.
  • Marka adeegga la hawlgeliyay uu yahay `CAD`, isticmaal `POST /api/open/tasks` hadda oo u tixgeli soo gelinta xirmada mid aan la heli karin.

Xusuus-qorka Khaladaadka

  • 400: codsi khaldan, ama adeegga la dejiyay ma taageerayo soo gelinta xirmada.
  • 401: furaha API waa maqan yahay, ma saxna, wuu dhacay, ama waa la damiyay.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: hawsha ama xirmada lama helin, ama ma laha isticmaalaha hadda.
  • 413: fayl aad u weyn.
  • 415: nooc sawir aan la taageerin ama sawir aan sax ahayn.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 soo gelinta xirmada lama heli karo
{
  "detail": "batch upload is not supported for business: cax"
}
401 furaha maqan ama aan sax ahayn API
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 fayl aad u weyn
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 dhammaatay
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Diyaar ma u tahay inaad tijaabiso habka shaqada?

Isticmaal web workspace sawirka koowaad, kadibna u guur API furayaasha marka qaabka natiijada uu ku habboon yahay nidaamkaaga.

Iska diiwaangeli oo sawir geliSamee furaha API