የውሃ ቆጣሪ OCR API

የውሃ ቆጣሪ OCR API. ይህ ገጽ ለሶስተኛ ወገን ውህደቶች በድረ ገጹ backend የሚቀርበውን ይፋዊ HTTP API ያብራራል።

በእውነተኛ ሰቀላ ይጀምሩ

መጀመሪያ ይመዝገቡ፣ የራስዎን የውሃ ቆጣሪ ፎቶ በስራ ቦታ ላይ ይስቀሉ እና ከዚያ ለመዋሃድ ዝግጁ ሲሆኑ API ቁልፍ ይፍጠሩ።

ይመዝገቡ እና ፎቶ ይስቀሉ API ቁልፍ ይፍጠሩ

የመጨረሻ ነጥቦችን ይፈልጉ

አጠቃላይ እይታ

ለሁሉም ውጫዊ ውህደቶች የድረ ገጹን backend ይጠቀሙ።
ከሶስተኛ ወገን ፕሮግራሞች በቀጥታ waterMeterAi አይደውሉ።
ክፍት API ከድር ፖርታል ጋር ተመሳሳይ ተጠቃሚዎችን፣ ኮታን፣ መሸጎጫዎችን፣ ተግባራትን እና የኦዲት ህጎችን ይጋራል።
Backend በማሰማራት ውቅር መሠረት የተለያዩ የታችኛው የAI አገልግሎቶችን ማነጣጠር ይችላል።
የተለያዩ አገልግሎቶች የተለያዩ የውጤት ዓይነቶችን ማሳየት እንዲችሉ የተግባር ምላሾች አሁን አጠቃላይ result_summary ነገርን ያካትታሉ።

ማረጋገጫ

በድህረ ገጹ ላይ ይግቡ እና በ API ቁልፎች ገጽ ላይ API ቁልፍ ይፍጠሩ።
ሙሉ API ቁልፍ ሲፈጠር አንድ ጊዜ ብቻ ይታያል.
በእያንዳንዱ ጥያቄ ቁልፉን በAuthorization ራስጌ ውስጥ ይላኩ።

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

የሰቀላ ደንቦች

ከፍተኛው የፋይል መጠን 20 ሜባ በምስል።
የሚደገፉ ቅርጸቶች JPEG፣ PNG፣ WEBP.
Backend የፋይል ቅጥያውን ብቻ ሳይሆን ትክክለኛውን የፋይል ይዘት ያረጋግጣል።

የሰቀላ መጠን ማስፈጸሚያ

የባች ሰቀላዎች በነባሪነት እስከ 8 ምስሎችን ይቀበላሉ፣ በ20ሜባ በምስል ገደብ እና 20ሜባ አጠቃላይ የፋይል-ይዘት ገደብ።
ከገደቡ በላይ የሆነ ፋይል ወይም ባች ምስል ከማረጋገጥ ወይም ተግባር ከመፍጠር በፊት 413 ይመለሳል። ምንም ከፊል ስብስብ አልተፈጠረም።
Content-Length በሌለበት ወይም የተከፋፈለ ዝውውር ጥቅም ላይ በሚውልበት ጊዜ እንኳን backend በትክክል የተቀበለውን የባይት ብዛት ያስፈጽማል።

የተግባር ሁኔታዎች

queued: ተቀብሏል እና የAI ሂደትን እየጠበቀ ነው።
running: አሁን በማስኬድ ላይ ነው፣ ወይም አስቀድሞ ለdispatcher ተላልፎ የመጨረሻ ውጤቱን በየጊዜው እየጠየቀ ነው።
batch_waiting_ai: በቡድኑ ውስጥ ያለው እያንዳንዱ ንጥል የAI አገልግሎት ወደ መስመር እስኪመለስ ድረስ እየጠበቀ ነው።
batch_running: ቡድኑ አስቀድሞ ለdispatcher ተሰጥቷል እና አሁንም በማስኬድ ላይ ነው።
done: በተሳካ ሁኔታ ተጠናቋል።
failed: ሂደቱ አልተሳካም።
waiting_ai: የAI አገልግሎቱ ወደ መስመር እስኪመለስ ድረስ በወረፋ ይጠብቃል፣ ከዚያ በራስ-ሰር ይቀጥላል።

የውጤት ምንጮች

fresh: በአዲስ የAI ሂደት የተፈጠረ።
cached_exact: ከአሁኑ የAI ስሪት መሸጎጫ ጋር ተዛምዷል።
cached_stale: AI ከመስመር ውጭ ሲሆን የቅርብ ጊዜ የተሸጎጠ ውጤት ተመልሷል።
pending: እስካሁን የመጨረሻ ውጤት የለም።
failed: ተግባሩ አልተሳካም።
አንድ ተግባር ገና ሳይጠናቀቅ፣ የቅርብ ጊዜውን የድጋሚ ሙከራ ወይም የጥበቃ ምክንያት ለማግኘት error_message ያረጋግጡ።

ኮታ እና የሂሳብ አከፋፈል

ውህደትዎ የኮታ ውድቀቶችን ማስወገድ ካስፈለገ ትላልቅ የስራ ጫናዎችን ከማስገባትዎ በፊት `GET /api/open/quota` ይጠቀሙ።
ኮታ የሚጠቀሙት የ`fresh` AI ሂደቶች ብቻ ናቸው።
`cached_exact`፣ `cached_stale`፣ `pending`እና `failed` ውጤቶች ኮታ አይበሉም።
ነፃ መለያዎች መጀመሪያ ዕለታዊ ኮታ ይጠቀማሉ። የሚከፈልባቸው መለያዎች ንቁ ወቅታዊ የኮታ ፓኬጆችን፣ ከዚያም ጊዜያዊ ወይም ቋሚ ኮታ በጀርባ ፖሊሲ መሰረት ይጠቀማሉ።
ኮታ ሲያልቅ የተግባር ማስረከቢያ `429` ይመለሳል እና አዲስ ተግባር ከመፍጠር ይልቅ የስህተት መልእክት ያካትታል።

መሸጎጫ እና የውጤት ትኩስነት

Backend ስኬታማ ውጤቶችን በምስል hash እና በAI ስሪት መሸጎጫ ያደርጋል፣ የታችኛውን አገልግሎት namespace ጨምሮ።
`cached_exact` ማለት ተመሳሳይ ምስል ለአሁኑ የAI ስሪት የተሳካ ውጤት አለው ማለት ነው፣ ስለዚህ አዲስ የAI ሂደት አላስፈለገም።
`cached_stale` ማለት AI አገልግሎቱ ከመስመር ውጭ ነው እና የጀርባው የቅርብ ጊዜውን ታሪካዊ ውጤት መልሷል ማለት ነው።
`is_latest_ai_version` false ሲሆን ውጤቱን ጥቅም ላይ ሊውል የሚችል ግን ሊገመገም የሚገባ ታሪካዊ መረጃ አድርገው ያከማቹ።
እያንዳንዱ `done` ተግባር ኮታ እንደተጠቀመ አያስቡ፤ `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`

የአሁኑን ኮታ እና የቀረውን አጠቃቀም ያንብቡ።

የጥያቄ ምሳሌ

curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

የምላሽ ምሳሌ

{
  "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`

ለተግባር ማስረከብ እና ወደ መሸጎጫ ውጤት መመለስ የሚያገለግለውን ይፋዊ የአገልግሎት ሁኔታ ያንብቡ።

የጥያቄ ምሳሌ

curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

የምላሽ ምሳሌ

{
  "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`

አንድ ምስል ይስቀሉ እና አንድ ነጠላ ተግባር ይፍጠሩ።

የጥያቄ ምሳሌ

curl -X POST "https://watermeterai.com/api/open/tasks" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \
  -F "file=@D:\data\meter_001.jpg"

የምላሽ ምሳሌ

{
  "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}`

አንድ የተግባር ሁኔታ እና የመጨረሻ ንባብ ያንብቡ።

የጥያቄ ምሳሌ

curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

የምላሽ ምሳሌ

{
  "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`

አሁን ባለው API ቁልፍ ተጠቃሚ ባለቤትነት የተያዙ የቅርብ ጊዜ ተግባራትን ያንብቡ።

የጥያቄ ምሳሌ

curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

የምላሽ ምሳሌ

{
  "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`

በአንድ ጥያቄ ውስጥ ብዙ ምስሎችን ይስቀሉ።

የጥያቄ ምሳሌ

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"

የምላሽ ምሳሌ

{
  "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}`

የባች ሂደትን እና በፋይል ተግባር ሁኔታዎችን ያንብቡ።

የጥያቄ ምሳሌ

curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

የምላሽ ምሳሌ

{
  "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": ""
    }
  ]
}

የሚመከር ፍሰት

ትላልቅ የስራ ጫናዎችን ከመላክዎ በፊት `GET /api/open/ai-status` ያረጋግጡ.
ከገቡ በኋላ ወዲያውኑ `task_id` ወይም `batch_id` በራስዎ ስርዓት ውስጥ ያከማቹ።
`queued`፣ `running`፣ `waiting_ai`፣ `batch_waiting_ai` እና `batch_running` የመጨረሻ ያልሆኑ ሁኔታዎች ናቸው፤ ሁኔታውን በየጊዜው መጠየቅዎን ይቀጥሉ።
ወደ backend የሚወስደው የአውታረ መረብ መንገድ ከፍተኛ መዘግየት ሲኖረው እና የተሰማራው አገልግሎት የቡድን ሁነታን ሲደግፍ የቡድን ጥያቄዎችን ይጠቀሙ።
ባች ጥያቄዎች በአሁኑ ጊዜ በ `webBackend -> dispatchCenter -> waterMeterAi`በኩል ይፈስሳሉ።
`batch_waiting_ai` ማለት እያንዳንዱ ንጥል አሁንም AI አገልግሎቱን እየጠበቀ ነው፣ ገና በንቃት እየሰራ አይደለም።
የተሰማራው አገልግሎት `CAD` ሲሆን ለአሁኑ `POST /api/open/tasks` ይጠቀሙ እና የቡድን ሰቀላ እንደማይገኝ ይያዙት።

የ ስህተት ማስታወሻዎች

400: ልክ ያልሆነ ጥያቄ፣ ወይም የተሰማራው አገልግሎት የቡድን ሰቀላን አይደግፍም።
401: የጎደለ፣ ልክ ያልሆነ፣ ጊዜው ያለፈበት ወይም የተሰናከለ API ቁልፍ።
403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
404: ተግባር ወይም ቡድን አልተገኘም፣ ወይም የአሁኑ ተጠቃሚ አይደለም።
413: ፋይሉ በጣም ትልቅ ነው።
415: የማይደገፍ የምስል ዓይነት ወይም ልክ ያልሆነ የምስል ይዘት።
429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.

400 ባች ሰቀላ አይገኝም።

{
  "detail": "batch upload is not supported for business: cax"
}

401 የጎደለ ወይንም ልክ ያልሆነ API ቁልፍ

{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}

413 ፋይል በጣም ትልቅ ነው

{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}

429 ኮታ ተዳክሟል

{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

የስራ ሂደቱን ለመሞከር ዝግጁ ነዎት?

ለመጀመሪያው ፎቶ የድር የስራ ቦታን ይጠቀሙ፣ ከዚያ የውጤት ቅርጸቱ ከስርዓትዎ ጋር ከሚስማማ በኋላ ወደ API ቁልፎች ይሂዱ።

ይመዝገቡ እና ፎቶ ይስቀሉ API ቁልፍ ይፍጠሩ

የውሃ ቆጣሪ OCR API

በእውነተኛ ሰቀላ ይጀምሩ

አጠቃላይ እይታ

ማረጋገጫ

API Key Permissions and Limits

የሰቀላ ደንቦች

የሰቀላ መጠን ማስፈጸሚያ

የተግባር ሁኔታዎች

የውጤት ምንጮች

ኮታ እና የሂሳብ አከፋፈል

መሸጎጫ እና የውጤት ትኩስነት

Task completion webhooks

GET/api/open/quota

GET/api/open/ai-status

POST/api/open/tasks

GET/api/open/tasks/{task_id}

GET/api/open/tasks

POST/api/open/batches

GET/api/open/batches/{batch_id}

የሚመከር ፍሰት

የ ስህተት ማስታወሻዎች

የስራ ሂደቱን ለመሞከር ዝግጁ ነዎት?

GET`/api/open/quota`

GET`/api/open/ai-status`

POST`/api/open/tasks`

GET`/api/open/tasks/{task_id}`

GET`/api/open/tasks`

POST`/api/open/batches`

GET`/api/open/batches/{batch_id}`