ឧបករណ៍វាស់ទឹក OCR API

ឧបករណ៍វាស់ទឹក OCR API. ទំព័រនេះចុះបញ្ជី HTTP API សាធារណៈដែលបានបង្ហាញដោយផ្នែកខាងក្រោយគេហទំព័រសម្រាប់ការរួមបញ្ចូលភាគីទីបី។

ចាប់ផ្តើមជាមួយការផ្ទុកឡើងពិតប្រាកដ

ចុះឈ្មោះជាមុន បញ្ចូលរូបថតម៉ែត្រទឹករបស់អ្នកនៅកន្លែងធ្វើការ ហើយបង្កើតកូនសោ API នៅពេលអ្នកត្រៀមខ្លួនសម្រាប់បញ្ចូល។

ចុះឈ្មោះ និងផ្ទុករូបភាព បង្កើតកូនសោ API

ចុងបញ្ចប់ស្វែងរក

ទិដ្ឋភាពទូទៅ

ប្រើផ្នែកខាងក្រោយគេហទំព័រសម្រាប់ការរួមបញ្ចូលខាងក្រៅទាំងអស់។
កុំហៅ waterMeterAi ដោយផ្ទាល់ពីកម្មវិធីភាគីទីបី។
Open API ចែករំលែកអ្នកប្រើ កូតា កាសេ ភារកិច្ច និងច្បាប់ត្រួតពិនិត្យដូចគ្នានឹងវេបសាយផតថល។
Backend អាចកំណត់គោលដៅសេវាកម្ម AI ខាងក្រោមផ្សេងៗតាមរយៈការកំណត់ deployment។
ការឆ្លើយតបភារកិច្ចឥឡូវនេះរួមបញ្ចូលវត្ថុទូទៅ result_summary ដូច្នេះសេវាកម្មផ្សេងៗអាចបង្ហាញប្រភេទលទ្ធផលខុសៗគ្នា។

ការផ្ទៀងផ្ទាត់អត្តសញ្ញាណ

ចូលប្រើគេហទំព័រ ហើយបង្កើតកូនសោ API នៅលើទំព័រ API Keys។
កូនសោ API ពេញលេញត្រូវបានបង្ហាញតែម្តងនៅពេលវាត្រូវបានបង្កើត។
ផ្ញើកូនសោនៅក្នុងក្បាលអនុញ្ញាតនៅលើសំណើរនីមួយៗ។

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 ខ្វះ ឬប្រើការផ្ទេរជាផ្នែកៗក៏ដោយ។

ស្ថានភាពភារកិច្ច

បានចូលជួរ៖ ទទួលយក និងរង់ចាំដំណើរការ AI ។
កំពុងដំណើរការ៖ កំពុងត្រូវបានដំណើរការ ឬបានផ្តល់ឲ្យអ្នកចែកចាយរួចហើយ ហើយកំពុងពិនិត្យស្ថានភាពជាប្រចាំសម្រាប់លទ្ធផលចុងក្រោយ។
batch_waiting_ai: ធាតុទាំងអស់ក្នុងកញ្ចប់កំពុងរង់ចាំសេវាកម្ម AI ត្រឡប់មកវិញ។
batch_running: កញ្ចប់ត្រូវបានផ្តល់ឲ្យអ្នកចែកចាយរួចហើយ ហើយកំពុងដំណើរការបន្ត។
បានបញ្ចប់៖ បានបញ្ចប់ដោយជោគជ័យ។
បរាជ័យ៖ ដំណើរការបរាជ័យ។
waiting_ai: រង់ចាំរហូតដល់សេវាកម្ម AI ត្រឡប់មកវិញ បន្ទាប់មកវានឹងបន្តដោយស្វ័យប្រវត្តិ។

ប្រភពលទ្ធផល

ថ្មី៖ បង្កើតដោយការដំណើរការ AI ថ្មី។
cached_exact: ផ្គូផ្គងនឹង cache កំណែ AI បច្ចុប្បន្ន។
cached_stale: AI offline លទ្ធផល cache ចុងក្រោយត្រូវបានបង្ហាញ។
កំពុងរង់ចាំ៖ មិនទាន់មានលទ្ធផលចុងក្រោយនៅឡើយ។
បរាជ័យ៖ ភារកិច្ចបរាជ័យ។
នៅពេលភារកិច្ចមិនទាន់បញ្ចប់ សូមពិនិត្យ error_message សម្រាប់មូលហេតុសាកល្បងថ្មី ឬរង់ចាំ។

កូតា និងការបង់ប្រាក់

ប្រើ `GET /api/open/quota` មុនពេលដាក់បន្ទុកការងារធំៗ ប្រសិនបើការរួមបញ្ចូលរបស់អ្នកត្រូវការជៀសវាងការបរាជ័យកូតា។
មានតែ `fresh` AI ដងប៉ុណ្ណោះដែលប្រើកូតា។
`cached_exact`, `cached_stale`, `pending`និង `failed` មិនប្រើកូតាទេ។
គណនីឥតគិតថ្លៃប្រើកូតាប្រចាំថ្ងៃជាមុនសិន។ គណនីដែលបានបង់ប្រាក់ប្រើកញ្ចប់កូតាដែលសកម្មជាប្រចាំ បន្ទាប់មកប្រើកូតាបណ្តោះអាសន្ន ឬកូតាថេរតាមគោលនយោបាយផ្នែកខាងក្រោយ។
ពេលកូតាត្រូវបានប្រើប្រាស់រួច ការដាក់ស្នើភារកិច្ចនឹងត្រឡប់មកវិញ `429` និងបង្ហាញសារកំហុសជំនួសការបង្កើតភារកិច្ចថ្មី។

ភាពថ្មីនៃ cache និងលទ្ធផល

Backend រក្សាទុកលទ្ធផលជោគជ័យតាម hash រូបភាព និងកំណែ AI រួមទាំង namespace សេវាកម្មខាងក្រោម។
`cached_exact` មានន័យថារូបភាពដដែលមានលទ្ធផលជោគជ័យសម្រាប់កំណែ AI បច្ចុប្បន្នរួចហើយ ដូច្នេះមិនចាំបាច់ដំណើរការ AI ថ្មីទេ។
`cached_stale` មានន័យថាសេវាកម្ម AI ត្រូវបានផ្អាក ហើយផ្នែកខាងក្រោយបង្ហាញលទ្ធផលប្រវត្តិសាស្ត្រថ្មីបំផុត។
នៅពេល `is_latest_ai_version` មិនពិត សូមរក្សាទុកលទ្ធផលជាទិន្នន័យប្រវត្តិសាស្ត្រដែលអាចប្រើបាន ប៉ុន្តែអាចពិនិត្យឡើងវិញបាន។
កុំសន្មត់ថាភារកិច្ច `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` ជាស្ថានភាពមិនទាន់ចុងក្រោយ ហើយបន្តពិនិត្យស្ថានភាពជាប្រចាំ។
ប្រើសំណើ batch នៅពេលផ្លូវបណ្តាញទៅ backend មាន latency ខ្ពស់ ហើយសេវាកម្មដែលបានដាក់ប្រើគាំទ្ររបៀប batch។
សំណើជាក្រុមបច្ចុប្បន្នហូរតាម `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 quota ត្រូវបានប្រើប្រាស់រួច

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

តើអ្នករួចរាល់សម្រាប់សាកល្បងលំហូរការងារហើយឬនៅ?

ប្រើកន្លែងធ្វើការតាមវេបសាយសម្រាប់រូបថតដំបូង បន្ទាប់មកផ្លាស់ទៅ API keys នៅពេលទ្រង់ទ្រាយលទ្ធផលសមស្របនឹងប្រព័ន្ធរបស់អ្នក។

ចុះឈ្មោះ និងផ្ទុករូបភាព បង្កើតកូនសោ API

ឧបករណ៍វាស់ទឹក OCR API

ចាប់ផ្តើមជាមួយការផ្ទុកឡើងពិតប្រាកដ

ទិដ្ឋភាពទូទៅ

ការផ្ទៀងផ្ទាត់អត្តសញ្ញាណ

API Key Permissions and Limits

ច្បាប់ផ្ទុកឡើង

ការអនុវត្តទំហំផ្ទុកឡើង

ស្ថានភាពភារកិច្ច

ប្រភពលទ្ធផល

កូតា និងការបង់ប្រាក់

ភាពថ្មីនៃ cache និងលទ្ធផល

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