WaterMeter AI
GjuhaShqip
Gjuhë të tjera

API OCR për ujëmatës

API OCR për ujëmatës. Kjo faqe dokumenton HTTP API publike të ekspozuara nga prapaskena e faqes për integrime të palëve të treta.

Filloni me një ngarkim të vërtetë

Regjistrohuni së pari, ngarkoni foton tuaj të matësit të ujit në hapësirën e punës, dhe pastaj krijoni një çelës API kur të jeni gati për integrim.

Regjistrohu dhe ngarko një fotoKrijo një Çelës API

Përmbledhje

  • Përdor backend-in e faqes për të gjitha integrimet e jashtme.
  • Mos waterMeterAi telefononi drejtpërdrejt nga programe të palëve të treta.
  • Open API ndan të njëjtat përdorues, kuotë, cache, detyra dhe rregulla auditimi si portali në internet.
  • Backend-i mund të synojë biznese të ndryshme AI më poshtë përmes konfigurimit të vendosjes.
  • Përgjigjet e detyrave tani përfshijnë një objekt të përgjithshëm result_summary në mënyrë që bizneset e ndryshme të mund të shfaqin lloje të ndryshme rezultatesh.

Autentikimi

  • Hyni në faqen e internetit dhe krijoni një çelës API në faqen API Çelësat.
  • Çelësi i plotë API shfaqet vetëm një herë kur krijohet.
  • Dërgo çelësin në header-in e Autorizimit në çdo kërkesë.
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

Rregullat e Ngarkimit

  • Madhësia maksimale e skedarit: 20MB për imazh.
  • Formatet e mbështetura: JPEG, PNG, WEBP.
  • Backend-i verifikon përmbajtjen aktuale të skedarit, jo vetëm shtesën e skedarit.

Zbatimi i Madhësisë së Ngarkimit

  • Ngarkimet në grup pranojnë deri në 8 imazhe si parazgjedhje, me një kufi prej 20MB për imazh dhe një kufi prej 20MB për përmbajtje totale skedarësh.
  • Një skedar ose grup që tejkalon kufirin e tij kthehet 413 para validimit të imazhit ose krijimit të detyrës; Nuk krijohet asnjë grup i pjesshëm.
  • Backend-i zbaton numrin aktual të bajteve të marra edhe kur mungon Content-Length ose përdoret transferim i ndarë në copa.

Shtetet e Detyrës

  • Në radhë: Pranuar dhe në pritje për përpunimin AI .
  • Në zhvillim: aktualisht po përpunohet, ose tashmë i është dorëzuar dispeçerit dhe ende po votohet për rezultatin përfundimtar.
  • batch_waiting_ai: çdo artikull në grup po pret që shërbimi i AI të rikthehet online.
  • batch_running: batch-i tashmë i është dorëzuar dispeçerit dhe ende po përpunohet.
  • Përfunduar: përfunduar me sukses.
  • dështoi: përpunimi dështoi.
  • waiting_ai: në pritje derisa shërbimi i AI të rikthehet online, pastaj rifillon automatikisht.

Burimet e rezultateve

  • E freskët: gjeneruar nga një AI e re e lojës.
  • cached_exact: përputhej me cache-in aktual të versionit AI .
  • cached_stale: AI offline, rezultati më i fundit i ruajtur në cache u kthye.
  • Në pritje: ende nuk ka rezultat përfundimtar.
  • Dështoi: Detyra dështoi.
  • Kur një detyrë nuk është përfunduar ende, kontrolloni error_message për arsyen e fundit të provës së dytë ose pritjes.

Kuotat dhe Faturimi

  • Përdorni `GET /api/open/quota` para se të dorëzoni ngarkesa të mëdha pune nëse integrimi juaj duhet të shmangë dështimet e kuotës.
  • Vetëm `fresh` AI vrapime konsumojnë kuotën.
  • `cached_exact`, `cached_stale`, `pending`, dhe rezultatet e `failed` nuk konsumojnë kuotën.
  • Llogaritë falas përdorin kuotën ditore së pari. Llogaritë e paguara përdorin paketa aktive periodike kuotash, pastaj kuota të përkohshme ose fikse sipas politikës së backend-it.
  • Kur kuota shteron, dorëzimi i detyrës kthehet `429` dhe përfshin një mesazh gabimi në vend që të krijojë një detyrë të re.

Cache dhe freskia e rezultateve

  • Backend-i ruan rezultatet e suksesshme në cache sipas hash-it të imazheve dhe versionit të AI , duke përfshirë hapësirën e emrave të biznesit në vijim.
  • `cached_exact` do të thotë që i njëjti imazh tashmë ka një rezultat të suksesshëm për versionin aktual të AI , kështu që nuk ishte e nevojshme një ekzekutim i ri AI .
  • `cached_stale` do të thotë që shërbimi AI është offline dhe backend-i ka kthyer rezultatin më të fundit historik të disponueshëm.
  • Kur `is_latest_ai_version` është e rreme, ruani rezultatin si të dhëna historike të përdorshme por të rishikoshme.
  • Mos supozoni kuotën e çdo detyre të `done` të konsumuar; Shiko `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

Lexo kuotën aktuale dhe përdorimin e mbetur.

Shembull Kërkese
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Shembull Përgjigjeje
{
  "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

Lexo statusin e shërbimit publik për dorëzimin e detyrave dhe backback-un e rezultateve të ruajtura.

Shembull Kërkese
curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Shembull Përgjigjeje
{
  "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

Ngarko një imazh dhe krijo një detyrë të vetme.

Shembull Kërkese
curl -X POST "https://watermeterai.com/api/open/tasks" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \
  -F "file=@D:\data\meter_001.jpg"
Shembull Përgjigjeje
{
  "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}

Lexoni statusin e një detyre dhe leximin përfundimtar.

Shembull Kërkese
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Shembull Përgjigjeje
{
  "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

Lexoni detyrat e fundit që zotërohen nga përdoruesi aktual API kyç.

Shembull Kërkese
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Shembull Përgjigjeje
{
  "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

Ngarkoni disa imazhe në një kërkesë.

Shembull Kërkese
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"
Shembull Përgjigjeje
{
  "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}

Lexoni progresin në grup dhe gjendjet e detyrave për çdo skedar.

Shembull Kërkese
curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Shembull Përgjigjeje
{
  "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": ""
    }
  ]
}

Rrjedha e rekomanduar

  • Kontrollo `GET /api/open/ai-status` para se të dërgosh ngarkesa të mëdha pune.
  • Ruaj `task_id` ose `batch_id` në sistemin tënd menjëherë pas dorëzimit.
  • Trajtoni `queued`, `running`, `waiting_ai`, `batch_waiting_ai`, dhe `batch_running` si gjendje jo-përfundimtare dhe vazhdoni sondazhet.
  • Përdorni kërkesat batch kur rruga e rrjetit drejt backend-it ka vonesë të lartë dhe biznesi i vendosur mbështet modalitetin batch.
  • Kërkesat batch aktualisht kalojnë përmes `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` do të thotë që çdo artikull është ende në pritje të shërbimit të AI , pa qenë aktiv ende.
  • Kur biznesi i vendosur të jetë `CAD`, përdorni `POST /api/open/tasks` për tani dhe trajtoni ngarkimin në grup si të pamundur.

Shënime Gabimi

  • 400: kërkesë e pavlefshme, ose biznesi i vendosur nuk mbështet ngarkimin në grup.
  • 401: mungon, është i pavlefshëm, i skaduar ose i çaktivizuar API çelës.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: detyra ose grupi nuk u gjet, ose nuk ishte në pronësi të përdoruesit aktual.
  • 413: fileto shumë e madhe.
  • 415: tip imazhi i pambështetur ose përmbajtje e pavlefshme imazhi.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 ngarkim në grup i pamundur
{
  "detail": "batch upload is not supported for business: cax"
}
401 çelës i munguar ose i pavlefshëm API
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 file shumë i madh
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 kuota e shterur
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Gati për të testuar rrjedhën e punës?

Përdor hapësirën e punës web për foton e parë, pastaj kalo te tastet API sapo formati i rezultatit të përshtatet me sistemin tënd.

Regjistrohu dhe ngarko një fotoKrijo një Çelës API