WaterMeter AI
BahasaBahasa Melayu
Bahasa lain

API OCR meter air

API OCR meter air. Halaman ini mendokumenkan HTTP API orang awam yang didedahkan oleh bahagian belakang tapak web untuk penyepaduan pihak ketiga.

Mulakan dengan muat naik sebenar

Daftar dahulu, muat naik foto meter air anda sendiri di ruang kerja, dan kemudian buat kunci API apabila anda sudah bersedia untuk menyepadukan.

Daftar dan Muat Naik FotoCipta Kunci API

Gambaran keseluruhan

  • Gunakan bahagian belakang tapak web untuk semua penyepaduan luaran.
  • Jangan panggil waterMeterAi terus daripada program pihak ketiga.
  • API terbuka berkongsi pengguna, kuota, cache, tugas dan peraturan audit yang sama seperti portal web.
  • Bahagian belakang boleh menyasarkan perkhidmatan AI hiliran yang berbeza mengikut konfigurasi penggunaan.
  • Respons tugasan kini termasuk objek umum result_summary supaya perkhidmatan yang berbeza boleh memaparkan jenis hasil yang berbeza.

Pengesahan

  • Log masuk di tapak web dan buat kunci API pada halaman Kunci API.
  • Kekunci API penuh ditunjukkan sekali sahaja apabila ia dicipta.
  • Hantar kunci dalam pengepala Authorization pada setiap permintaan.
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

Peraturan Muat Naik

  • Saiz fail maksimum: 20MB setiap imej.
  • Format yang disokong: JPEG, PNG, WEBP.
  • Bahagian belakang mengesahkan kandungan fail sebenar, bukan hanya sambungan fail.

Penguatkuasaan Saiz Muat Naik

  • Muat naik kelompok menerima sehingga 8 imej secara lalai, dengan had 20MB setiap imej dan jumlah had kandungan fail 20MB.
  • Fail atau kumpulan yang melebihi hadnya mengembalikan 413 sebelum pengesahan imej atau penciptaan tugas; tiada kumpulan separa dibuat.
  • Bahagian belakang menguatkuasakan kiraan bait sebenar yang diterima walaupun apabila Content-Length tiada atau pemindahan chunked digunakan.

Negeri Tugas

  • beratur: diterima dan menunggu pemprosesan AI.
  • berjalan: sedang diproses, atau sudah diserahkan kepada penghantar dan status masih diperiksa secara berkala untuk keputusan akhir.
  • batch_waiting_ai: setiap item dalam batch sedang menunggu perkhidmatan AI untuk kembali dalam talian.
  • batch_running: kumpulan sudah diserahkan kepada penghantar dan masih diproses.
  • selesai: selesai dengan jayanya.
  • gagal: pemprosesan gagal.
  • waiting_ai: beratur sehingga perkhidmatan AI kembali dalam talian, kemudian ia disambung semula secara automatik.

Sumber Hasil

  • segar: dijana oleh larian AI baharu.
  • cached_exact: sepadan dengan cache versi AI semasa.
  • cached_stale: AI luar talian, hasil cache terbaharu dikembalikan.
  • belum selesai: belum ada keputusan akhir.
  • gagal: tugas gagal.
  • Apabila tugasan belum selesai, semak error_message untuk mencuba semula terkini atau sebab menunggu.

Kuota dan Pengebilan

  • Gunakan `GET /api/open/quota` sebelum menyerahkan beban kerja yang besar jika penyepaduan anda perlu mengelakkan kegagalan kuota.
  • Hanya `fresh` AI menjalankan menggunakan kuota.
  • Keputusan `cached_exact`, `cached_stale`, `pending` dan `failed` tidak menggunakan kuota.
  • Akaun percuma menggunakan kuota harian dahulu. Akaun berbayar menggunakan pakej kuota berkala aktif, kemudian kuota sementara atau tetap mengikut dasar bahagian belakang.
  • Apabila kuota habis, penyerahan tugas mengembalikan `429` dan termasuk mesej ralat dan bukannya membuat tugasan baharu.

Cache dan Kesegaran Hasil

  • Bahagian belakang menyimpan hasil yang berjaya mengikut cincang imej dan versi AI, termasuk ruang nama perkhidmatan hiliran.
  • `cached_exact` bermakna imej yang sama sudah mempunyai hasil yang berjaya untuk versi AI semasa, jadi tiada larian AI baharu diperlukan.
  • `cached_stale` bermaksud perkhidmatan AI berada di luar talian dan bahagian belakang mengembalikan hasil sejarah terkini yang tersedia.
  • Apabila `is_latest_ai_version` palsu, simpan hasilnya sebagai data sejarah yang boleh digunakan tetapi boleh disemak.
  • Jangan anggap setiap `done` tugasan menggunakan kuota; semak `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

Baca kuota semasa dan baki penggunaan.

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

Baca status perkhidmatan awam untuk penyerahan tugas dan sandaran hasil cache.

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

Muat naik satu imej dan buat satu tugasan.

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

Baca satu status tugasan dan bacaan akhir.

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

Baca tugasan terbaru yang dimiliki oleh pengguna kunci API semasa.

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

Muat naik berbilang imej dalam satu permintaan.

Contoh Permintaan
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"
Contoh Respons
{
  "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}

Baca kemajuan kelompok dan keadaan tugas setiap fail.

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

Aliran Disyorkan

  • Semak `GET /api/open/ai-status` sebelum menghantar beban kerja yang besar.
  • Simpan `task_id` atau `batch_id` dalam sistem anda sendiri sejurus selepas penyerahan.
  • Anggap `queued`, `running`, `waiting_ai`, `batch_waiting_ai` dan `batch_running` sebagai keadaan bukan muktamad dan teruskan semakan status berkala.
  • Gunakan permintaan kelompok apabila laluan rangkaian ke bahagian belakang mempunyai kependaman yang tinggi dan perkhidmatan yang digunakan menyokong mod kelompok.
  • Permintaan kelompok pada masa ini mengalir melalui `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` bermakna setiap item masih menunggu perkhidmatan AI, belum aktif lagi.
  • Apabila perkhidmatan yang digunakan ialah `CAD`, gunakan `POST /api/open/tasks` buat masa ini dan anggap muat naik kelompok sebagai tidak tersedia.

Nota Ralat

  • 400: permintaan tidak sah, atau perkhidmatan yang digunakan tidak menyokong muat naik kelompok.
  • 401: kekunci API hilang, tidak sah, tamat tempoh atau dilumpuhkan.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: tugas atau kumpulan tidak ditemui, atau tidak dimiliki oleh pengguna semasa.
  • 413: fail terlalu besar.
  • 415: jenis imej tidak disokong atau kandungan imej tidak sah.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
Muat naik 400 kelompok tidak tersedia
{
  "detail": "batch upload is not supported for business: cax"
}
401 tiada atau kunci API tidak sah
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 fail terlalu besar
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 kuota habis
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Bersedia untuk menguji aliran kerja?

Gunakan ruang kerja web untuk foto pertama, kemudian beralih ke kekunci API sebaik sahaja format hasil sesuai dengan sistem anda.

Daftar dan Muat Naik FotoCipta Kunci API