WaterMeter AI
BahasaBahasa Indonesia
Bahasa lainnya

API OCR meter air

API OCR meter air. Halaman ini mendokumentasikan HTTP API publik yang diekspos oleh backend situs web untuk integrasi pihak ketiga.

Mulai dengan unggahan nyata

Daftar terlebih dahulu, unggah foto meter air Anda di workspace, lalu buat API key saat siap integrasi.

Daftar dan unggah fotoBuat API key

Ringkasan

  • Gunakan backend situs web untuk semua integrasi eksternal.
  • Jangan menelepon waterMeterAi langsung dari program pihak ketiga.
  • API terbuka berbagi pengguna, kuota, cache, tugas, dan aturan audit yang sama dengan portal web.
  • Backend dapat menargetkan bisnis AI hilir yang berbeda berdasarkan konfigurasi penerapan.
  • Respons tugas kini menyertakan objek result_summary umum sehingga bisnis yang berbeda dapat menampilkan jenis hasil yang berbeda.

Otentikasi

  • Masuk ke situs web dan buat kunci API di halaman API Kunci.
  • Kunci API lengkap hanya ditampilkan satu kali saat dibuat.
  • Kirim kunci di header Otorisasi 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

Aturan Unggah

  • Ukuran file maksimum: 20MB per gambar.
  • Format yang didukung: JPEG, PNG, WEBP.
  • Backend memvalidasi konten file sebenarnya, bukan hanya ekstensi file.

Penegakan Ukuran Unggahan

  • Unggahan batch menerima hingga 8 gambar secara default, dengan batas 20MB per gambar dan total batas konten file 20MB.
  • File atau batch yang melebihi batasnya akan menghasilkan 413 sebelum validasi gambar atau pembuatan tugas; tidak ada batch parsial yang dibuat.
  • Backend menerapkan jumlah byte aktual yang diterima bahkan ketika Content-Length hilang atau transfer terpotong digunakan.

Status Tugas

  • queued: diterima dan menunggu AI diproses.
  • running : sedang diproses, atau sudah diserahkan ke petugas operator dan masih melakukan polling untuk hasil akhir.
  • batch_waiting_ai: setiap item dalam batch menunggu layanan AI kembali online.
  • batch_running: batch sudah diserahkan ke petugas operator dan masih diproses.
  • done: berhasil diselesaikan.
  • failed: memproses failed.
  • waiting_ai: queued hingga layanan AI kembali online, kemudian dilanjutkan secara otomatis.

Sumber Hasil

  • fresh: dihasilkan oleh proses AI baru.
  • cached_exact: cocok dengan cache versi AI saat ini.
  • cached_stale: AI offline, hasil cache terbaru dikembalikan.
  • pending: belum ada hasil akhir.
  • failed: tugas failed.
  • Jika suatu tugas belum done, periksa error_message untuk alasan percobaan ulang atau menunggu yang terakhir.

Kuota dan Penagihan

  • Gunakan `GET /api/open/quota` sebelum mengirim beban kerja besar jika integrasi Anda perlu menghindari kegagalan kuota.
  • Hanya proses AI `fresh` yang menggunakan kuota.
  • Hasil `cached_exact`, `cached_stale`, `pending`, dan `failed` tidak menggunakan kuota.
  • Akun gratis menggunakan kuota harian terlebih dahulu. Akun berbayar menggunakan paket kuota periodik aktif, lalu kuota sementara atau tetap sesuai kebijakan backend.
  • Saat kuota habis, pengiriman tugas mengembalikan `429` dan pesan kesalahan, bukan membuat tugas baru.

Cache dan Kesegaran Hasil

  • Backend menyimpan hasil berhasil berdasarkan hash gambar dan versi AI, termasuk namespace bisnis downstream.
  • `cached_exact` berarti gambar yang sama sudah memiliki hasil berhasil untuk versi AI saat ini, sehingga proses AI baru tidak diperlukan.
  • `cached_stale` berarti layanan AI offline dan backend mengembalikan hasil historis terbaru yang tersedia.
  • Saat `is_latest_ai_version` bernilai false, simpan hasil sebagai data historis yang dapat digunakan tetapi perlu ditinjau.
  • Jangan berasumsi setiap tugas `done` memakai kuota; periksa `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 saat ini dan sisa pemakaian.

Contoh Permintaan
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Contoh Respon
{
  "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 layanan publik untuk penyerahan tugas dan fallback hasil cache.

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

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

Contoh Permintaan
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Contoh Respon
{
  "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 tugas terkini yang dimiliki oleh pengguna kunci API saat ini.

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

Membaca kemajuan batch dan status tugas per file.

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

  • Periksa `GET /api/open/ai-status` sebelum mengirim beban kerja besar.
  • Simpan `task_id` atau `batch_id` di sistem Anda segera setelah pengiriman.
  • Perlakukan `queued`, `running`, `waiting_ai`, `batch_waiting_ai`, dan `batch_running` sebagai negara bagian non-final dan terus lakukan pemungutan suara.
  • Gunakan permintaan batch ketika jalur jaringan ke backend memiliki latensi tinggi dan bisnis yang diterapkan mendukung mode batch.
  • Permintaan batch saat ini mengalir melalui `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` artinya setiap barang masih menunggu layanan AI, belum aktif running.
  • Jika bisnis yang diterapkan adalah `CAD`, gunakan `POST /api/open/tasks` untuk saat ini dan perlakukan unggahan batch sebagai tidak tersedia.

Catatan Kesalahan

  • 400: permintaan tidak valid, atau bisnis yang diterapkan tidak mendukung unggahan batch.
  • 401: kunci API hilang, tidak valid, kedaluwarsa, atau dinonaktifkan.
  • 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 ditemukan, atau tidak dimiliki oleh pengguna saat ini.
  • 413: file terlalu besar.
  • 415: jenis gambar tidak didukung atau konten gambar tidak valid.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 unggahan batch tidak tersedia
{
  "detail": "batch upload is not supported for business: cax"
}
401 kunci API hilang atau tidak valid
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
File 413 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."
  }
}

Siap menguji alurnya?

Gunakan workspace web untuk foto pertama, lalu lanjut ke API key saat format hasil sudah sesuai.

Daftar dan unggah fotoBuat API key