WaterMeter AI
BasaBasa Jawa
Basa liya

Meter banyu OCR API

Meter banyu OCR API. Kaca iki nyathet umum HTTP API sing kapapar dening backend situs web kanggo integrasi pihak katelu.

Miwiti kanthi unggahan nyata

Ndhaptar dhisik, unggah foto meter banyu sampeyan dhewe ing ruang kerja, banjur gawe kunci API yen wis siyap kanggo nggabungake.

Ndhaptar lan Unggah FotoGawe kunci API

Ringkesan

  • Gunakake backend situs web kanggo kabeh integrasi eksternal.
  • Aja nelpon waterMeterAi langsung saka program pihak katelu.
  • API mbukak nuduhake pangguna, kuota, cache, tugas, lan aturan audit sing padha karo portal web.
  • Backend bisa ngarahake layanan AI hilir sing beda nganggo konfigurasi panyebaran.
  • Tanggapan tugas saiki kalebu obyek umum result_summary supaya layanan sing beda bisa nampilake jinis asil sing beda.

Autentikasi

  • Mlebu ing situs web lan gawe kunci API ing kaca Kunci API.
  • Kunci API lengkap ditampilake mung sapisan nalika digawe.
  • Kirimi kunci ing header Wewenang ing saben panjalukan.
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

Aturan Upload

  • Ukuran berkas maksimal: 20MB saben gambar.
  • Format sing didhukung: JPEG, PNG, WEBP.
  • Backend validasi isi file nyata, ora mung ekstensi file.

Unggahan Ukuran Penegakan

  • Unggahan batch nampa nganti 8 gambar kanthi gawan, kanthi watesan saben gambar 20MB lan watesan isi file total 20MB.
  • Berkas utawa kumpulan sing ngluwihi watesan ngasilake 413 sadurunge validasi gambar utawa nggawe tugas; ora kumpulan sebagean digawe.
  • Backend ngleksanakake count byte ditampa nyata sanajan Content-Length ilang utawa transfer chunked digunakake.

Negara Tugas

  • antri: ditampa lan nunggu AI pangolahan.
  • mlaku: saiki lagi diproses, utawa wis dipasrahake menyang dispatcher lan status isih dipriksa kanthi berkala kanggo asil pungkasan.
  • batch_waiting_ai: saben item ing kumpulan nunggu layanan AI bali online.
  • batch_running: kumpulan wis diserahake menyang dispatcher lan isih diproses.
  • rampung: rampung kasil.
  • gagal: pangolahan gagal.
  • waiting_ai: antri nganti layanan AI bali online, banjur diterusake kanthi otomatis.

Sumber Asil

  • seger: digawe dening anyar AI mbukak.
  • cached_exact: cocog karo versi cache saiki AI.
  • cached_stale: AI offline, asil cache paling anyar bali.
  • ditundha: durung ana asil pungkasan.
  • gagal: tugas gagal.
  • Nalika tugas durung rampung, priksa error_message kanggo nyoba maneh paling anyar utawa alesan nunggu.

Kuota lan Tagihan

  • Gunakake `GET /api/open/quota` sadurunge ngirim beban kerja gedhe yen integrasi sampeyan kudu ngindhari kegagalan kuota.
  • Mung `fresh` AI mlaku nganggo kuota.
  • `cached_exact`, `cached_stale`, `pending`, lan `failed` asil ora nganggo kuota.
  • Akun gratis nggunakake kuota saben dina dhisik. Akun mbayar nggunakake paket kuota periodik aktif, banjur kuota sementara utawa tetep miturut kabijakan backend.
  • Yen kuota wis entek, kiriman tugas bali `429` lan kalebu pesen kesalahan tinimbang nggawe tugas anyar.

Cache lan Freshness Asil

  • Backend nyimpen asil sukses miturut hash gambar lan versi AI, kalebu namespace layanan hilir.
  • `cached_exact` tegese gambar sing padha wis kasil kanggo versi AI saiki, mula ora perlu mlaku AI anyar.
  • `cached_stale` tegese layanan AI offline lan backend ngasilake asil historis paling anyar sing kasedhiya.
  • Nalika `is_latest_ai_version` palsu, simpen asil minangka data historis sing bisa digunakake nanging bisa dideleng.
  • Aja nganggep saben `done` tugas sing digunakake kuota; mriksa `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

Waca kuota saiki lan sisa panggunaan.

Conto Panjaluk
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Tuladha Tanggapan
{
  "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

Waca status layanan umum kanggo pengajuan tugas lan cached-hasil mundur.

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

Unggah siji gambar lan gawe tugas siji.

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

Waca siji status tugas lan wacan pungkasan.

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

Waca tugas anyar sing diduweni dening pangguna kunci API saiki.

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

Unggah pirang-pirang gambar ing siji panyuwunan.

Conto Panjaluk
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"
Tuladha Tanggapan
{
  "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}

Waca kemajuan kumpulan lan status tugas saben file.

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

Alur sing Disaranake

  • Priksa `GET /api/open/ai-status` sadurunge ngirim beban kerja gedhe.
  • Simpen `task_id` utawa `batch_id` ing sistem sampeyan langsung sawise diajukake.
  • Nambani `queued`, `running`, `waiting_ai`, `batch_waiting_ai`, lan `batch_running` minangka status sing durung pungkasan lan terus mriksa status kanthi berkala.
  • Gunakake panjalukan kumpulan nalika jalur jaringan menyang backend nduweni latensi dhuwur lan layanan sing disebarake ndhukung mode kumpulan.
  • Panjaluk batch saiki mili liwat `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` tegese saben item isih ngenteni layanan AI, durung aktif.
  • Nalika layanan sing disebarake yaiku `CAD`, gunakake `POST /api/open/tasks` saiki lan anggep unggahan batch ora kasedhiya.

Cathetan Kasalahan

  • 400: panjalukan ora sah, utawa layanan sing disebarake ora ndhukung unggahan kumpulan.
  • 401: kunci API ilang, ora sah, kadaluwarsa, utawa dipateni.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: tugas utawa kumpulan ora ditemokake, utawa ora diduweni dening pangguna saiki.
  • 413: file gedhe banget.
  • 415: jinis gambar sing ora didhukung utawa isi gambar sing ora valid.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 batch upload ora kasedhiya
{
  "detail": "batch upload is not supported for business: cax"
}
401 kunci API ilang utawa ora valid
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 file gedhe banget
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 kuota entek
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Siap nguji alur kerja?

Gunakake ruang kerja web kanggo foto pisanan, banjur pindhah menyang kunci API yen format asil cocog karo sistem sampeyan.

Ndhaptar lan Unggah FotoGawe kunci API