WaterMeter AI
BasaBasa Sunda
Basa séjén

API OCR méter cai

API OCR méter cai. Kaca ieu dokumén publik HTTP API kakeunaan ku backend ramatloka pikeun integrasi pihak katilu.

Mimitian ku unggah nyata

Ngadaptar heula, unggah poto méter cai anjeun sorangan dina rohangan gawé, teras jieun konci API nalika anjeun siap ngahijikeun.

Ngadaptar sareng Unggah PotoJieun konci API

Ihtisar

  • Paké backend ramatloka pikeun sakabéh integrations éksternal.
  • Ulah nelepon waterMeterAi langsung ti program pihak katilu.
  • Buka API ngabagi pangguna, kuota, cache, tugas, sareng aturan audit anu sami sareng portal wéb.
  • Backend tiasa nargétkeun ladenan AI hilir anu béda ngaliwatan konfigurasi deployment.
  • Tanggapan tugas ayeuna kalebet objék umum result_summary supaya ladenan anu béda tiasa ningalikeun jinis hasil anu béda.

Auténtikasi

  • Asup dina situs web tur jieun konci API dina kaca konci API.
  • Konci API lengkep dipintonkeun ngan sakali nalika dijieun.
  • Kirim konci dina lulugu Otorisasi dina unggal pamundut.
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 nu dirojong: JPEG, PNG, WEBP.
  • Backend ngesahkeun eusi file anu sabenerna, sanes ngan ukur ekstensi file.

Unggah Ukuran Penegak

  • Unggahan bets nampi dugi ka 8 gambar sacara standar, kalayan wates per-gambar 20MB sareng wates eusi file 20MB.
  • A file atawa bets nu ngaleuwihan wates na mulih 413 saméméh validasi gambar atawa nyieun tugas; euweuh bets parsial dijieun.
  • Backend maksakeun jumlah bait anu ditampi saleresna sanajan Panjang-Konten leungit atanapi transfer chunked dianggo.

Tugas Nagara

  • antrian: ditarima tur ngantosan AI ngolah.
  • ngajalankeun: ayeuna keur diprosés, atawa geus dibikeun ka dispatcher sarta statusna masih dipariksa sacara périodik pikeun hasil ahir.
  • batch_waiting_ai: unggal item dina bets ngantosan jasa AI balik deui online.
  • batch_running: bets geus dibikeun ka dispatcher jeung masih ngolah.
  • rengse: rengse suksés.
  • gagal: pamrosésan gagal.
  • waiting_ai: antrian nepi ka ladenan AI balik deui online, teras diteruskeun sacara otomatis.

Sumber Hasil

  • seger: dihasilkeun ku anyar AI ngajalankeun.
  • cached_exact: cocog sareng AI versi cache ayeuna.
  • cached_stale: AI offline, hasil cache panganyarna balik.
  • pending: teu acan aya hasil ahir.
  • gagal: tugasna gagal.
  • Lamun tugas teu acan rengse, pariksa error_message pikeun nyoba ulang panganyarna atawa alesan ngantosan.

Kuota jeung Tagihan

  • Anggo `GET /api/open/quota` sateuacan ngirimkeun beban kerja anu ageung upami integrasi anjeun kedah nyegah gagal kuota.
  • Ngan `fresh` AI ngajalankeun meakeun kuota.
  • `cached_exact`, `cached_stale`, `pending`, jeung `failed` hasilna teu meakeun kuota.
  • Akun gratis nganggo kuota poean heula. Akun anu mayar nganggo pakét kuota périodik aktip, teras kuota samentawis atanapi tetep dumasar kana kawijakan backend.
  • Lamun kuota béak, tugas kaluman balik deui `429` tur ngawengku pesen kasalahan tinimbang nyieun tugas anyar.

Cache jeung Freshness Hasil

  • Backend nyimpen hasil anu suksés dumasar hash gambar sareng vérsi AI, kalebet namespace ladenan hilir.
  • `cached_exact` hartina gambar anu sarua geus hasil suksés pikeun versi AI ayeuna, jadi euweuh AI ngajalankeun anyar diperlukeun.
  • `cached_stale` hartina ladenan AI offline jeung backend balik hasil sajarah panganyarna sadia.
  • Nalika `is_latest_ai_version` palsu, simpen hasilna salaku data sajarah anu tiasa dianggo tapi tiasa ditinjau.
  • Ulah nganggap unggal `done` tugas dihakan kuota; pariksa `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 ayeuna sareng pamakean sésana.

Ménta Conto
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Conto 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

Baca status layanan publik pikeun kaluman tugas jeung cache-hasil fallback.

Ménta Conto
curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Conto 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 hiji gambar sareng jieun hiji tugas.

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

Baca hiji status tugas jeung bacaan ahir.

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

Baca tugas panganyarna milik pamaké konci API ayeuna.

Ménta Conto
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Conto 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 sababaraha gambar dina hiji pamundut.

Ménta Conto
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"
Conto 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}

Baca kamajuan bets jeung kaayaan tugas per-file.

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

Disarankeun Aliran

  • Pariksa `GET /api/open/ai-status` sateuacan ngirim beban kerja anu ageung.
  • Simpen `task_id` atawa `batch_id` dina sistem Anjeun sorangan langsung saatos kiriman.
  • Anggap `queued`, `running`, `waiting_ai`, `batch_waiting_ai`, jeung `batch_running` minangka status nu can final sarta terus pariksa status sacara périodik.
  • Paké pamundut bets lamun jalur jaringan ka backend boga latency luhur jeung ladenan nu di-deploy ngarojong mode bets.
  • Paménta bets ayeuna ngalir ngaliwatan `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` hartina unggal item masih ngantosan ladenan AI, teu acan aktip.
  • Nalika ladenan anu di-deploy nyaéta `CAD`, paké `POST /api/open/tasks` pikeun ayeuna sareng anggap unggahan bets henteu sayogi.

Catetan Kasalahan

  • 400: pamundut teu valid, atawa ladenan nu di-deploy teu ngarojong unggah bets.
  • 401: konci API leungit, teu valid, kadaluwarsa, atawa ditumpurkeun.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: tugas atawa bets teu kapanggih, atawa teu dipiboga ku pamaké ayeuna.
  • 413: file badag teuing.
  • 415: tipe gambar teu dirojong atawa eusi gambar teu valid.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 bets unggah teu sadia
{
  "detail": "batch upload is not supported for business: cax"
}
401 leungit atawa teu valid API konci
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 file badag teuing
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 kuota béak
{
  "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?

Pake rohangan gawé wéb pikeun poto kahiji, teras pindah ka konci API sawaktos format hasil cocog sareng sistem anjeun.

Ngadaptar sareng Unggah PotoJieun konci API