WaterMeter AI
ԼեզուՀայերեն
Այլ լեզուներ

Ջրաչափի OCR API

Ջրաչափի OCR API. Այս էջը փաստում է հանրային HTTP API , որը բացահայտվում է կայքի backend-ի կողմից երրորդ կողմի ինտեգրումների համար:

Սկսեք իրական վերբեռնումից

Նախ գրանցվեք, աշխատանքային աշխատատեղում վերբեռնեք ձեր սեփական ջրաչափի լուսանկարը, այնուհետեւ ստեղծեք API բանալին, երբ պատրաստ եք ինտեգրվել:

Գրանցվիր եւ վերբեռնիր լուսանկարՍտեղծել API բանալի

Ակնարկ

  • Օգտագործեք կայքի backend-ը բոլոր արտաքին ինտեգրումների համար:
  • Մի զանգահարեք waterMeterAi ուղղակիորեն երրորդ կողմի ծրագրերից:
  • Բաց API կիսում է նույն օգտվողները, քվոտան, քեշը, առաջադրանքները եւ աուդիտի կանոնները, ինչ վեբ պորտալը։
  • Backend-ը կարող է թիրախավորել տարբեր ներքեւի AI բիզնեսներ՝ տեղակայման կոնֆիգուրացիայով։
  • Առաջադրանքների պատասխանները այժմ ներառում են ընդհանուր 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

Վերբեռնման կանոններ

  • Ֆայլի առավելագույն չափը՝ 20 ՄԲ մեկ պատկերի համար:
  • Աջակցվող ձեւաչափերը: JPEG, PNG, WEBP.
  • Backend-ը վավերացնում է ֆայլի իրական բովանդակությունը, ոչ միայն ֆայլի ընդլայնումը։

Վերբեռնեք չափի կիրառում

  • Խմբաքանակի վերբեռնումները ընդունում են մինչեւ 8 պատկեր ըստ լռելյայնի՝ 20 ՄԲ մեկ պատկերի սահմանափակմամբ եւ 20 ՄԲ ընդհանուր ֆայլի բովանդակության սահմանափակումով։
  • Նիշքը կամ խմբաքանակը, որը գերազանցում է իր սահմանը, վերադարձնում է 413 նախքան պատկերի վավերացումը կամ առաջադրանքի ստեղծումը; Մասնակի խմբաքանակ չի ստեղծվում:
  • Backend-ը պարտադրում է փաստացի ստացված բայթերի քանակը նույնիսկ այն դեպքում, երբ բացակայում է Content-Length-ը կամ օգտագործվում է chunked փոխանցումը։

Առաջադրանքի վիճակները

  • Ընդունված եւ սպասում է AI մշակման:
  • Ներկայումս մշակվում է, կամ արդեն հանձնվում է առաքիչին եւ դեռ քվեարկում է վերջնական արդյունքի համար։
  • batch_waiting_ai: խմբաքանակի յուրաքանչյուր ապրանք սպասում է AI ծառայությանը վերադառնալ առցանց:
  • batch_running: խմբաքանակն արդեն հանձնվել է առաքիչին եւ դեռ մշակվում է:
  • Ավարտվել է: Ավարտվել է:
  • Մշակումը ձախողված է:
  • waiting_ai: հերթում մինչեւ AI ծառայությունը վերադառնում է առցանց, այնուհետեւ այն ավտոմատ կերպով վերսկսվում է:

Արդյունքի աղբյուրներ

  • Թարմ: Գեներացված է նոր AI վազքից:
  • cached_exact: համապատասխանում է ընթացիկ AI տարբերակի քեշին:
  • cached_stale: AI անցանց, վերջին պահեստավորված արդյունքը վերադարձվել է:
  • Դեռ վերջնական արդյունք չկա։
  • Ձախողված. առաջադրանքը ձախողվել է:
  • Եթե առաջադրանքը դեռ չի ավարտվել, ստուգեք error_message վերջին կրկնության կամ սպասման պատճառը:

Քվոտա եւ բիլինգ

  • Օգտագործեք `GET /api/open/quota` նախքան մեծ ծանրաբեռնվածություն ներկայացնելը, եթե ձեր ինտեգրումը պետք է խուսափի քվոտայի ձախողումներից:
  • Միայն `fresh` AI վազքերը սպառում են քվոտան։
  • `cached_exact`, `cached_stale`, `pending`եւ `failed` արդյունքները չեն սպառում քվոտան:
  • Անվճար հաշիվները նախ օգտագործում են օրական քվոտան։ Վճարովի հաշիվները օգտագործում են ակտիվ պարբերական քվոտաների փաթեթներ, այնուհետեւ ժամանակավոր կամ ֆիքսված քվոտա՝ համաձայն backend քաղաքականության:
  • Երբ քվոտան սպառվում է, առաջադրանքի ներկայացումը վերադարձնում է `429` եւ ներառում է սխալ հաղորդագրություն՝ նոր առաջադրանք ստեղծելու փոխարեն:

Քեշ եւ արդյունք թարմությունը

  • Backend-ը պահում է հաջող արդյունքները պատկերի հեշով եւ AI տարբերակով, ներառյալ ներքեւի բիզնեսի անվանատարածքը։
  • `cached_exact` նշանակում է, որ նույն պատկերն արդեն հաջող արդյունք ունի ընթացիկ AI տարբերակի համար, ուստի նոր AI աշխատելու կարիք չկար։
  • `cached_stale` նշանակում է, որ AI ծառայությունը օֆլայն է, եւ backend-ը վերադարձրել է վերջին հասանելի պատմական արդյունքը։
  • Երբ `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` որպես ոչ վերջնական վիճակներ եւ շարունակեք քվեարկել։
  • Օգտագործեք խմբաքանակի հարցումները, երբ ցանցային ուղին դեպի backend-ն ունի բարձր ուշացում, եւ տեղակայված բիզնեսը աջակցում է խմբաքանակի ռեժիմը:
  • Խմբաքանակի հարցումները ներկայումս հոսում են `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 բանալի