API OCR למד מים

API OCR למד מים. דף זה מתעד את HTTP API הציבורי שנחשף על ידי קצה העורפי של האתר עבור אינטגרציות של צד שלישי.

התחל בהעלאה אמיתית

הירשם תחילה, העלה תמונת מד מים משלך בסביבת העבודה, ולאחר מכן צור מפתח API כשתהיה מוכן לשילוב.

הירשם והעלה תמונה צור מפתח API

חפש נקודות קצה

סקירה כללית

השתמש ב-backend של האתר עבור כל האינטגרציות החיצוניות.
אל תתקשר ל-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.
הקצה האחורי מאמת את תוכן הקובץ בפועל, לא רק את סיומת הקובץ.

אכיפת גודל העלאה

העלאות אצווה מקבלות עד 8 תמונות כברירת מחדל, עם מגבלה של 20MB לתמונה ומגבלה של 20MB הכולל של תוכן קבצים.
קובץ או אצווה שחורגים מהמגבלה שלו מחזירים 413 לפני אימות תמונה או יצירת משימה; לא נוצרת אצווה חלקית.
הקצה האחורי אוכף את ספירת הבתים שהתקבלה בפועל גם כאשר Content-Length חסר או בשימוש בהעברה של חלקים.

מצבי משימה

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` וכוללת הודעת שגיאה במקום יצירת משימה חדשה.

מטמון ורעננות התוצאה

הקצה האחורי מאחסן תוצאות מוצלחות לפי 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

API OCR למד מים

התחל בהעלאה אמיתית

סקירה כללית

אימות

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