WaterMeter AI
ΓλώσσαΕλληνικά
Άλλες γλώσσες

API OCR μετρητή νερού

API OCR μετρητή νερού. Αυτή η σελίδα τεκμηριώνει το δημόσιο HTTP API που εκτίθεται από το backend του ιστότοπου για ενσωματώσεις τρίτων.

Ξεκινήστε με μια πραγματική μεταφόρτωση

Εγγραφείτε πρώτα, ανεβάστε τη δική σας φωτογραφία μετρητή νερού στον χώρο εργασίας και, στη συνέχεια, δημιουργήστε ένα κλειδί API όταν είστε έτοιμοι να ενσωματώσετε.

Εγγραφείτε και ανεβάστε μια φωτογραφίαΔημιουργήστε ένα κλειδί API

Επισκόπηση

  • Χρησιμοποιήστε το backend του ιστότοπου για όλες τις εξωτερικές ενσωματώσεις.
  • Μην καλείτε waterMeterAi απευθείας από προγράμματα τρίτων.
  • Το ανοιχτό API μοιράζεται τους ίδιους χρήστες, όριο, προσωρινή μνήμη, εργασίες και κανόνες ελέγχου με την πύλη Ιστού.
  • Το backend μπορεί να στοχεύει διαφορετικές επιχειρήσεις κατάντη AI με διαμόρφωση ανάπτυξης.
  • Οι αποκρίσεις εργασιών περιλαμβάνουν πλέον ένα γενικό αντικείμενο result_summary, έτσι ώστε διαφορετικές επιχειρήσεις να μπορούν να εμφανίζουν διαφορετικούς τύπους αποτελεσμάτων.

Έλεγχος ταυτότητας

  • Συνδεθείτε στον ιστότοπο και δημιουργήστε ένα κλειδί API στη σελίδα API Keys.
  • Το πλήρες κλειδί 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.
  • Το backend επικυρώνει το πραγματικό περιεχόμενο του αρχείου, όχι μόνο την επέκταση αρχείου.

Επιβολή μεγέθους μεταφόρτωσης

  • Οι μαζικές μεταφορτώσεις δέχονται έως και 8 εικόνες από προεπιλογή, με όριο 20 MB ανά εικόνα και όριο συνολικού περιεχομένου αρχείου 20 MB.
  • Ένα αρχείο ή παρτίδα που υπερβαίνει το όριο επιστρέφει 413 πριν από την επικύρωση εικόνας ή τη δημιουργία εργασίας. δεν δημιουργείται μερική παρτίδα.
  • Το backend επιβάλλει τον πραγματικό αριθμό ληφθέντων byte ακόμη και όταν λείπει το Content-Length ή χρησιμοποιείται τεμαχισμένη μεταφορά.

Καθήκοντα

  • ουρά: αποδεκτή και αναμονή για επεξεργασία AI.
  • τρέχει: βρίσκεται υπό επεξεργασία ή έχει ήδη παραδοθεί στον αποστολέα και εξακολουθεί να ψηφίζει για το τελικό αποτέλεσμα.
  • batch_waiting_ai: κάθε στοιχείο της παρτίδας περιμένει να επιστρέψει η υπηρεσία AI στο διαδίκτυο.
  • batch_running: η παρτίδα έχει ήδη παραδοθεί στον αποστολέα και βρίσκεται ακόμη σε επεξεργασία.
  • έγινε: ολοκληρώθηκε με επιτυχία.
  • απέτυχε: απέτυχε η επεξεργασία.
  • wait_ai: βρίσκεται σε ουρά έως ότου η υπηρεσία AI επανέλθει στο διαδίκτυο και, στη συνέχεια, συνεχίζει αυτόματα.

Πηγές αποτελεσμάτων

  • φρέσκο: δημιουργήθηκε από μια νέα εκτέλεση AI.
  • cached_exact: ταιριάζει με την τρέχουσα κρυφή μνήμη της έκδοσης AI.
  • cached_stale: AI εκτός σύνδεσης, επιστράφηκε το πιο πρόσφατο αποθηκευμένο αποτέλεσμα.
  • εκκρεμεί: δεν υπάρχει ακόμη τελικό αποτέλεσμα.
  • απέτυχε: η εργασία απέτυχε.
  • Όταν μια εργασία δεν έχει ολοκληρωθεί ακόμη, ελέγξτε το error_message για την πιο πρόσφατη επανάληψη ή τον λόγο αναμονής.

Ποσόστωση και χρέωση

  • Χρησιμοποιήστε `GET /api/open/quota` πριν υποβάλετε μεγάλους φόρτους εργασίας, εάν η ενσωμάτωσή σας χρειάζεται να αποφύγει αποτυχίες ορίου.
  • Μόνο οι εκτελέσεις `fresh` AI καταναλώνουν όριο.
  • Τα αποτελέσματα `cached_exact`, `cached_stale`, `pending` και `failed` δεν καταναλώνουν το όριο.
  • Οι δωρεάν λογαριασμοί χρησιμοποιούν πρώτα το ημερήσιο όριο. Οι λογαριασμοί επί πληρωμή χρησιμοποιούν ενεργά περιοδικά πακέτα ορίων και, στη συνέχεια, προσωρινό ή σταθερό όριο σύμφωνα με την πολιτική υποστήριξης.
  • Όταν εξαντληθεί το όριο, η υποβολή εργασίας επιστρέφει `429` και περιλαμβάνει ένα μήνυμα σφάλματος αντί να δημιουργήσει μια νέα εργασία.

Προσωρινή μνήμη και φρεσκάδα αποτελεσμάτων

  • Το backend αποθηκεύει στην προσωρινή μνήμη επιτυχημένα αποτελέσματα κατά κατακερματισμό εικόνας και έκδοση AI, συμπεριλαμβανομένου του χώρου ονομάτων της επιχείρησης κατάντη.
  • Το `cached_exact` σημαίνει ότι η ίδια εικόνα έχει ήδη ένα επιτυχημένο αποτέλεσμα για την τρέχουσα έκδοση AI, επομένως δεν χρειαζόταν νέα εκτέλεση AI.
  • Το `cached_stale` σημαίνει ότι η υπηρεσία AI είναι εκτός σύνδεσης και το backend επέστρεψε το πιο πρόσφατο διαθέσιμο ιστορικό αποτέλεσμα.
  • Όταν το `is_latest_ai_version` είναι ψευδές, αποθηκεύστε το αποτέλεσμα ως δεδομένα ιστορικού που μπορούν να χρησιμοποιηθούν αλλά μπορούν να ελεγχθούν.
  • Μην υποθέτετε κάθε ποσό κατανάλωσης `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