Усны хэмжигч OCR API

Усны хэмжигч OCR API. Энэ хуудсанд гуравдагч талын систем нэгтгэхэд зориулан вэбсайтын арын системээс нээлттэй болгосон HTTP API-г тайлбарлана.

Бодит зураг байршуулж эхлэх

Эхлээд бүртгүүлж, ажлын хэсэгт өөрийн усны тоолуурын зургийг байршуулна уу. Системд нэгтгэхэд бэлэн болсон үедээ API түлхүүр үүсгэнэ үү.

Бүртгүүлж, зураг байршуулах API түлхүүр үүсгэх

API төгсгөлийн цэг хайх

Тойм

Бүх гадаад системийн холболтод вэбсайтын арын системийг ашиглана уу.
Гуравдагч талын програмаас waterMeterAi-г шууд дуудаж болохгүй.
Нээлттэй API нь вэб порталтай ижил хэрэглэгч, квот, кэш, даалгавар, аудитын дүрмийг хуваалцдаг.
Арын систем байршуулалтын тохиргооноос хамааран доод түвшний өөр өөр AI үйлчилгээг сонгож чадна.
Даалгаврын хариунд ерөнхий result_summary объект багтдаг тул өөр өөр үйлчилгээ өөр төрлийн үр дүнг харуулах боломжтой.

Баталгаажуулалт

Вэбсайтад нэвтэрч, API түлхүүрүүд хуудсанд API түлхүүр үүсгэнэ үү.
API түлхүүрийг бүрэн хэлбэрээр нь зөвхөн үүсгэх үед нэг удаа харуулна.
Хүсэлт бүрийн Authorization толгой хэсэгт түлхүүрийг илгээнэ үү.

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

Зураг байршуулах дүрэм

Файлын хамгийн их хэмжээ: нэг зураг бүрт 20MB.
Дэмжигдсэн форматууд: JPEG, PNG, WEBP.
Арын систем нь зөвхөн файлын өргөтгөлийг бус, бодит агуулгыг нь шалгана.

Байршуулалтын хэмжээний хязгаарлалт

Багц байршуулалт нь анхдагчаар хамгийн ихдээ 8 зураг хүлээн авна. Нэг зураг 20MB, бүх файлын нийт агуулга 20MB хүртэл байна.
Файл эсвэл багц хязгаараас хэтэрвэл зураг шалгах, даалгавар үүсгэхээс өмнө 413 хариу буцаана. Хэсэгчилсэн багц үүсгэхгүй.
Content-Length байхгүй эсвэл хэсэгчлэн дамжуулалт ашигласан ч арын систем бодитоор хүлээн авсан байтын тоогоор хязгаарлана.

Даалгаврын төлөвүүд

queued: даалгаврыг хүлээн авч, AI боловсруулалтыг хүлээж байна.
running: одоо боловсруулж байгаа, эсвэл диспетчерт шилжүүлсэн бөгөөд эцсийн үр дүнг тогтмол шалгаж байна.
batch_waiting_ai: багц дахь бүх элемент AI үйлчилгээ дахин онлайн болохыг хүлээж байгаа бөгөөд хараахан ажиллаж эхлээгүй.
batch_running: багцыг диспетчерт шилжүүлсэн бөгөөд боловсруулалт үргэлжилж байна.
done: амжилттай дууссан.
failed: боловсруулалт амжилтгүй болсон.
waiting_ai: AI үйлчилгээ дахин онлайн болох хүртэл дараалалд хүлээгээд дараа нь автоматаар үргэлжилнэ.

Үр дүнгийн эх сурвалж

fresh: AI-г шинээр ажиллуулж үүсгэсэн.
cached_exact: одоогийн AI хувилбарын кэштэй таарсан.
cached_stale: AI оффлайн, хамгийн сүүлд кэшлэгдсэн үр дүн буцаагдсан.
pending: эцсийн үр дүн хараахан гараагүй.
failed: даалгавар амжилтгүй болсон.
Даалгавар дуусаагүй бол хамгийн сүүлийн дахин оролдлого эсвэл хүлээж буй шалтгааныг error_message-ээс шалгана уу.

Квот ба төлбөр

Таны систем квот дууссанаас үүсэх алдаанаас сэргийлэх шаардлагатай бол их хэмжээний даалгавар илгээхийн өмнө `GET /api/open/quota`-г ашиглана уу.
Зөвхөн AI-г шинээр ажиллуулсан `fresh` үр дүн квот зарцуулна.
`cached_exact`, `cached_stale`, `pending` болон `failed` үр дүн квот зарцуулахгүй.
Үнэгүй бүртгэл эхлээд өдрийн квотоо ашиглана. Төлбөртэй бүртгэл арын системийн бодлогын дагуу хүчинтэй хугацаат квотын багц, дараа нь түр эсвэл тогтмол квот ашиглана.
Квот дууссан үед даалгавар илгээх хүсэлт шинэ даалгавар үүсгэхгүй, харин `429` болон алдааны мэдэгдэл буцаана.

Кэш ба үр дүнгийн шинэлэг байдал

Арын систем амжилттай үр дүнг зурагны hash, AI хувилбар болон доод түвшний бизнесийн namespace-аар кэшлэнэ.
`cached_exact` гэдэг нь ижил зурагт одоогийн AI хувилбарын амжилттай үр дүн аль хэдийн байгаа тул AI-г шинээр ажиллуулах шаардлагагүйг илэрхийлнэ.
`cached_stale` гэдэг нь AI үйлчилгээ оффлайн үед арын систем хамгийн сүүлийн боломжтой түүхэн үр дүнг буцаасныг илэрхийлнэ.
`is_latest_ai_version` нь false бол үр дүнг ашиглаж болох боловч хянан шалгах шаардлагатай түүхэн өгөгдөл болгон хадгална.
`done` төлөвтэй даалгавар бүр квот зарцуулсан гэж үзэж болохгүй; `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`

Одоогийн квот болон үлдсэн хэрэглээг авах.

Хүсэлтийн жишээ

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

Хариуны жишээ

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

Даалгавар илгээх боломж болон кэшлэгдсэн үр дүнд шилжих эсэхийг тодорхойлох нийтийн үйлчилгээний төлөвийг авах.

Хүсэлтийн жишээ

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

Хариуны жишээ

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

Нэг зураг байршуулж, нэг даалгавар үүсгэх.

Хүсэлтийн жишээ

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

Хариуны жишээ

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

Нэг даалгаврын төлөв болон эцсийн заалтыг авах.

Хүсэлтийн жишээ

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

Хариуны жишээ

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

Одоогийн API түлхүүрийн хэрэглэгчид хамаарах сүүлийн даалгавруудыг авах.

Хүсэлтийн жишээ

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

Хариуны жишээ

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

Нэг хүсэлтээр олон зураг байршуулах.

Хүсэлтийн жишээ

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"

Хариуны жишээ

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

Багцын явц болон файл бүрийн даалгаврын төлөвийг авах.

Хүсэлтийн жишээ

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

Хариуны жишээ

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

Санал болгосон урсгал

Их хэмжээний даалгавар илгээхийн өмнө `GET /api/open/ai-status`-ийг шалгана уу.
Илгээсний дараа `task_id` эсвэл `batch_id` шууд өөрийн системдээ хадгалаарай.
`queued`, `running`, `waiting_ai`, `batch_waiting_ai` болон `batch_running`-ийг эцсийн бус төлөв гэж үзэж, төлөвийг үргэлжлүүлэн шалгана уу.
Арын систем хүрэх сүлжээний саатал их бөгөөд байршуулсан үйлчилгээ багц горим дэмждэг бол багц хүсэлт ашиглана уу.
Багц хүсэлт одоогоор `webBackend -> dispatchCenter -> waterMeterAi` урсгалаар дамжина.
`batch_waiting_ai` гэдэг нь бүх элемент AI үйлчилгээг хүлээж байгаа бөгөөд хараахан ажиллаж эхлээгүйг илэрхийлнэ.
Байршуулсан үйлчилгээ `CAD` бол одоогоор `POST /api/open/tasks`-ийг ашиглаж, багц байршуулалтыг боломжгүй гэж үзнэ үү.

Алдааны тэмдэглэл

400: хүсэлт буруу эсвэл байршуулсан үйлчилгээ багц байршуулалтыг дэмждэггүй.
401: API түлхүүр байхгүй, хүчингүй, хугацаа нь дууссан эсвэл идэвхгүй болсон.
403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
404: даалгавар эсвэл багц олдсонгүй, эсвэл одоогийн хэрэглэгчид хамаарахгүй.
413: файл хэт том.
415: зургийн төрөл дэмжигдээгүй эсвэл зургийн агуулга хүчингүй.
429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.

400 багц байршуулалт боломжгүй

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

401 API түлхүүр дутуу эсвэл буруу

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

413 файл хэт том

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

429 квот дууссан

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

Ажлын урсгалыг туршихад бэлэн үү?

Эхний зургаа вэб ажлын хэсгээр боловсруулна уу. Үр дүнгийн формат таны системд тохирсны дараа API түлхүүр ашиглаж эхэлнэ үү.

Бүртгүүлж, зураг байршуулах API түлхүүр үүсгэх

Усны хэмжигч OCR API

Бодит зураг байршуулж эхлэх

Тойм

Баталгаажуулалт

API Key Permissions and Limits

Зураг байршуулах дүрэм

Байршуулалтын хэмжээний хязгаарлалт

Даалгаврын төлөвүүд

Үр дүнгийн эх сурвалж

Квот ба төлбөр

Кэш ба үр дүнгийн шинэлэг байдал

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}

Санал болгосон урсгал

Алдааны тэмдэглэл

Ажлын урсгалыг туршихад бэлэн үү?

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