Suw ölçeýji OCR API

Suw ölçeýji OCR API. Bu sahypa üçünji taraplaryň integrasiýasy üçin web-saýtyň backendiniň paş HTTP API açyk maglumatlaryny dokumentleşdirýär.

Hakyky ýüklemekden başlaň

Ilki hasaba alynyň, iş ýeriňizde öz suw metr suratyňyzy ýükläň, soňra integrasiýa etmäge taýýar bolanyňyzda API açaryny dörediň.

Hasaba alyň we suraty ýükleň API açaryny döret

Uç noktalary gözle

Umumy mazmun

Ähli daşky integrasiýalar üçin web-saýtyň backendini ulanyň.
Üçünji tarap programmalaryndan waterMeterAi hyzmatyny göni ulanmaň.
Açyk API web portaly bilen şol bir ulanyjy, kota, keş, ýumuş we audit düzgünlerini ulanýar.
Backend ýerleşdirme konfigurasiýasy boýunça dürli aşak akymdaky AI hyzmatlaryna ugrukdyrylyp bilýär.
Ýumuş jogaplarynda umumy result_summary obýekti bar, şonuň üçin dürli hyzmatlar özüne degişli netije görnüşini görkezip biler.

Tassyklamak

Web-saýta giriň we API Keys sahypasynda API açaryny dörediň.
Doly API açary döredilende diňe bir gezek görkezilýär.
Her haýyşda Authorization başlygynda açary iberiň.

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

Ýükleme düzgünleri

Iň köp faýl ululygy: Her resim üçin 20MB.
Goldanylýan formatlar: JPEG, PNG, WEBP.
Backend diňe bir faýl giňişligini däl, eýsem hakyky faýl mazmunyny tassyklaýar.

Ýükleme ululygy düzgüni

Batch ýüklemeler öň bellenilen 8 suraty kabul edýär, her resim üçin 20MB we 20MB faýl-mazmun çägi bar.
Bir faýl ýa-da tutuş batch çäkden aşsa, backend surat barlagyndan ýa-da ýumuş döredilmezinden öň 413 gaýtarýar; bölekleýin batch döredilmeýär.
Backend hatda Content-Length bolmasa ýa-da bölek-bölek transfer ulanylsa-da, hakyky alnan bayt sanyny mejbur edýär.

Ýumşuň ýagdaýlary

queued: kabul edildi we AI tarapyndan işlenilmegine garaşýar.
running: häzir işlenilýär ýa-da dispetchere tabşyryldy we soňky netije üçin ýagdaý henizem döwürleýin barlanýar.
batch_waiting_ai: partiýadaky her bir zat AI hyzmatynyň ýene-de peýda bolmagyna garaşýar.
batch_running: ýumuşlar toplumy dispetchere tabşyryldy we henizem işlenilýär.
done: üstünlikli tamamlandy.
failed: işlemek başa barmady.
waiting_ai: AI hyzmaty gaýdyp gelýänçä nobata durýar, soňra otomatik dowam edýär.

Netije çeşmeleri

fresh: AI-nyň täze işledilmegi arkaly döredildi.
cached_exact: häzirki AI wersiýasynyň keshine gabat geldi.
cached_stale: AI offline, iň soňky keshlenen netije gaýdyp geldi.
pending: heniz gutarnykly netije ýok.
failed: ýumuş başa barmady.
Ýumuş entek tamamlanmadyk bolsa, iň soňky garaşma ýa-da gaýtadan synanyşma sebäbini error_message arkaly barlaň.

Kota we hasaplaýyş

Integrasiýaňyz kota ýetmezçiligi sebäpli ýalňyşlykdan gaça durmaly bolsa, köp ýumuş ibermezden öň `GET /api/open/quota` ulanyň.
Diňe `fresh` çeşmeli täze AI tanama netijesi kota sarp edýär.
`cached_exact`, `cached_stale`, `pending` we `failed` netijeleri kota sarp etmeýär.
Mugt hasaplar ilki gündelik kotany ulanýar. Tölegli hasaplar işjeň döwürleýin kota paketlerini, soňra wagtlaýyn ýa-da hemişelik kotalary ulanýar.
Kota gutaranda ýumuş ibermek `429` we ýalňyşlyk habaryny gaýtarýar; täze ýumuş döredilmeýär.

Kesh we netije täzeligi

Backend üstünlikli netijeleri surat hash-i we AI wersiýasy boýunça keshleýär hem-de aşak akymdaky hyzmatyň namespace bahasyny öz içine alýar.
`cached_exact` şol resim häzirki AI wersiýasy üçin eýýäm üstünlikli netije berdi, şonuň üçin täze AI gerek däldi.
`cached_stale` bu hyzmatyň offline AI we backendiň iň soňky elýeterli taryhy netijesini gaýtaryp berýändigini aňladýar.
Eger `is_latest_ai_version` false bolsa, netijäni ulanyp bolýan, ýöne gözden geçirilmeli taryhy maglumat hökmünde saklaň.
Her bir `done` ýumuş kota sarp etdi diýip pikir etmäň; `result_source` bahasyny barlaň.

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`

Häzirki kotalary we galan ulanylyşy okaň.

Mysal haýyş et

curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

Jogap mysaly

{
  "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`

Ýumuş ibermegiň mümkindigini we keşlenen netijä dolanmagyň zerurdygyny kesgitlemek üçin açyk hyzmat ýagdaýyny okaň.

Mysal haýyş et

curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

Jogap mysaly

{
  "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`

Bir resim ýükläp, ýekeje ýumuş dörediň.

Mysal haýyş et

curl -X POST "https://watermeterai.com/api/open/tasks" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \
  -F "file=@D:\data\meter_001.jpg"

Jogap mysaly

{
  "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}`

Bir ýumşuň ýagdaýyny we soňky görkezijisini okaň.

Mysal haýyş et

curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

Jogap mysaly

{
  "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`

Häzirki API açarynyň ulanyjysyna degişli soňky ýumuşlary okaň.

Mysal haýyş et

curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

Jogap mysaly

{
  "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`

Bir haýyşda birnäçe suratlary ýükle.

Mysal haýyş et

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"

Jogap mysaly

{
  "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}`

Batch ösüşini we her faýlyň ýumuş ýagdaýyny okaň.

Mysal haýyş et

curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

Jogap mysaly

{
  "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": ""
    }
  ]
}

Maslahat berilýän akym

Köp ýumuş ibermezden öň `GET /api/open/ai-status` ýagdaýyny barlaň.
`task_id` ýa-da `batch_id` iberilenden soň derrew öz sistemaňyzda saklaň.
`queued`, `running`, `waiting_ai`, `batch_waiting_ai` we `batch_running` ýagdaýlaryny gutarnykly däl diýip hasaplaň we ýagdaýy döwürleýin barlamagy dowam ediň.
Backend-e barýan ulgam ýolunyň gijikmesi ýokary bolsa we ýerleşdirilen hyzmat batch režimini goldasa, batch haýyşlaryny ulanyň.
Batch haýyşlary şu wagt `webBackend -> dispatchCenter -> waterMeterAi` zynjyry boýunça geçýär.
`batch_waiting_ai` her bir elementiň AI hyzmatyna garaşýandygyny we heniz işlenip başlanmandygyny aňladýar.
Ýerleşdirilen hyzmat `CAD` bolsa, häzirlikçe `POST /api/open/tasks` ulanyň we batch ýüklemäni elýeterli däl diýip hasaplaň.

Ýalňyşlyk bellikleri

400: nädogry haýyş ýa-da ýerleşdirilen iş batch ýüklemegi goldamaýar.
401: ýiten, geçersiz, möhleti dolan ýa-da öçürilen API açary.
403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
404: ýumuş ýa-da batch tapylmady, ýa-da häzirki ulanyja degişli däl.
413: faýl gaty ulu.
415: desteklenmeýän resim hili ýa-da nädogry resim mazmuny.
429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.

400: Batch ýüklemek elýeterli däl

{
  "detail": "batch upload is not supported for business: cax"
}

401: API açary ýok ýa-da nädogry

{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}

413 faýly gaty uly

{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}

429: Kota gutardy

{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Iş akışyny barlamaga taýýarmy?

Ilkinji surat üçin web iş meýdançasyny ulanyň, netije formaty sistemaňyza gabat gelende API açarlaryna geçiň.

Hasaba alyň we suraty ýükleň API açaryny döret

Suw ölçeýji OCR API

Hakyky ýüklemekden başlaň

Umumy mazmun

Tassyklamak

API Key Permissions and Limits

Ýükleme düzgünleri

Ýükleme ululygy düzgüni

Ýumşuň ýagdaýlary

Netije çeşmeleri

Kota we hasaplaýyş

Kesh we netije täzeligi

Task completion webhooks

GET/api/open/quota

GET/api/open/ai-status

POST/api/open/tasks

GET/api/open/tasks/{task_id}

GET/api/open/tasks

POST/api/open/batches

GET/api/open/batches/{batch_id}

Maslahat berilýän akym

Ýalňyşlyk bellikleri

Iş akışyny barlamaga taýýarmy?

GET`/api/open/quota`

GET`/api/open/ai-status`

POST`/api/open/tasks`

GET`/api/open/tasks/{task_id}`

GET`/api/open/tasks`

POST`/api/open/batches`

GET`/api/open/batches/{batch_id}`