Ҳисобкунаки об OCR API

Ҳисобкунаки об OCR API. Ин саҳифа HTTP 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 тасвирро бо маҳдудияти 20 МБ барои як тасвир ва маҳдудияти умумии мундариҷаи файл 20 МБ қабул мекунанд.
Файл ё партияе, ки аз ҳадди худ зиёд аст, пеш аз тасдиқи тасвир ё эҷоди вазифа 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}`