واٹر میٹر OCR API

واٹر میٹر OCR API. یہ صفحہ عوامی HTTP API کو دستاویز کرتا ہے جسے تیسرے فریق کے انضمام کے لیے ویب سائٹ کے بیک اینڈ کے ذریعے بے نقاب کیا گیا ہے۔

ایک حقیقی اپ لوڈ کے ساتھ شروع کریں۔

پہلے رجسٹر کریں، ورک اسپیس میں اپنی واٹر میٹر کی تصویر اپ لوڈ کریں، اور پھر جب آپ انضمام کے لیے تیار ہوں تو ایک API کلید بنائیں۔

رجسٹر کریں اور ایک تصویر اپ لوڈ کریں۔ایک API کلید بنائیں

اختتامی مقامات تلاش کریں۔

جائزہ

تمام بیرونی انضمام کے لیے ویب سائٹ کا بیک اینڈ استعمال کریں۔
تھرڈ پارٹی پروگراموں سے براہ راست waterMeterAi پر کال نہ کریں۔
اوپن API وہی صارفین، کوٹہ، کیشے، کاموں، اور آڈٹ کے قواعد کو ویب پورٹل کی طرح شیئر کرتا ہے۔
بیک اینڈ تعیناتی کی ترتیب کے ذریعے مختلف ڈاؤن اسٹریم 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

اپ لوڈ کے قواعد

فائل کا زیادہ سے زیادہ سائز: 20MB فی تصویر۔
تعاون یافتہ فارمیٹس: JPEG, PNG, WEBP۔
پسدید اصل فائل مواد کی توثیق کرتا ہے، نہ صرف فائل کی توسیع۔

اپ لوڈ سائز انفورسمنٹ

بیچ اپ لوڈز 20MB فی تصویر کی حد اور 20MB فائل کے مواد کی کل حد کے ساتھ، ڈیفالٹ کے طور پر 8 تصاویر تک قبول کرتے ہیں۔
ایک فائل یا بیچ جو اپنی حد سے زیادہ ہے تصویر کی توثیق یا ٹاسک بنانے سے پہلے 413 لوٹاتا ہے۔ کوئی جزوی بیچ نہیں بنایا گیا ہے۔
بیک اینڈ اصل موصول ہونے والی بائٹ گنتی کو نافذ کرتا ہے یہاں تک کہ جب Content-Length غائب ہو یا chunked ٹرانسفر استعمال کیا جاتا ہو۔

ٹاسک ریاستیں۔

queued: قبول ہو چکا ہے اور AI پروسیسنگ کا انتظار کر رہا ہے۔
running: اس وقت پروسیسنگ جاری ہے، یا ڈسپیچر کے حوالے کیے جانے کے بعد حتمی نتیجے کی حالت وقتاً فوقتاً جانچی جا رہی ہے۔
batch_waiting_ai: بیچ میں موجود ہر آئٹم AI سروس کے آن لائن واپس آنے کا انتظار کر رہا ہے۔
batch_running: بیچ پہلے ہی ڈسپیچر کے حوالے کر دیا گیا ہے اور ابھی تک کارروائی ہو رہی ہے۔
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` لوٹاتا ہے اور نیا ٹاسک بنانے کے بجائے ایک غلطی کا پیغام شامل کرتا ہے۔

کیش اور نتیجہ کی تازگی

بیک اینڈ امیج ہیش اور 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` کو غیر حتمی حالتیں سمجھیں اور حالت کی وقفے وقفے سے جانچ جاری رکھیں۔
بیچ درخواستیں اس وقت استعمال کریں جب بیک اینڈ تک نیٹ ورک راستے میں زیادہ تاخیر ہو اور تعینات سروس بیچ موڈ کی سہولت دیتی ہو۔
بیچ کی درخواستیں فی الحال `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}`