WaterMeter AI
KeelEesti
Teised keeled

Veearvesti OCR API

Veearvesti OCR API. See lehekülg dokumenteerib avalikku HTTP API veebilehe taustaosa poolt kolmandate osapoolte integratsioonide jaoks avatud.

Alusta päris üleslaadimisega

Registreeru esmalt, laadi oma veearvesti foto tööruumi üles ja loo siis API võti, kui oled valmis integreerima.

Registreeru ja laadi foto üles.Loo API võti

Ülevaade

  • Kasuta kõigi väliste integratsioonide jaoks veebisaidi taustasüsteemi.
  • Ära kutsu waterMeterAi-d otse kolmandate osapoolte programmidest.
  • Avatud API jagab samu kasutajaid, kvoodit, vahemälu, ülesandeid ja auditi reegleid nagu veebiportaal.
  • Taustsüsteem saab juurutuskonfiguratsiooni alusel kasutada erinevaid allavoolu AI teenuseid.
  • Ülesannete vastused sisaldavad üldist result_summary objekti, et erinevad teenused saaksid kuvada erinevaid tulemustüüpe.

Autentimine

  • Logi sisse veebilehel ja loo API Keys lehel API võti.
  • Täielik API võti kuvatakse ainult korra, kui see on loodud.
  • Saada võti iga päringuga Authorization päises.
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

Üleslaadimise reeglid

  • Maksimaalne faili suurus: 20MB pildi kohta.
  • Toetatud vormingud: JPEG, PNG, WEBP.
  • Backend valideerib tegeliku faili sisu, mitte ainult faililaiendit.

Üleslaadimise suuruse jõustamine

  • Partiiüleslaadimised aktsepteerivad vaikimisi kuni 8 pilti, piirang on 20MB pildi kohta ja 20MB kogu failisisu piirang.
  • Fail või partii, mis ületab oma piiri, tagastab 413 enne pildi valideerimist või ülesande loomist; Osalist partiid ei teki.
  • Taustsüsteem rakendab tegelikku vastuvõetud baitide arvu ka siis, kui Content-Length puudub või kasutatakse tükeldatud edastust.

Ülesande olekud

  • queued: Vastu võetud ja ootab AI töötlemist.
  • running: Praegu töödeldakse, või on ülesanne juba dispetšerile edastatud ja olekut kontrollitakse perioodiliselt lõpptulemuse saamiseks.
  • batch_waiting_ai: Iga partii üksus ootab, et AI teenus uuesti võrku tuleks.
  • batch_running: Partii on juba dispetšerile üle antud ja seda töödeldakse endiselt.
  • done: Edukalt lõpetatud.
  • failed: Töötlemine ebaõnnestus.
  • waiting_ai: Ootab järjekorras, kuni AI teenus uuesti võrku tuleb, ja jätkub seejärel automaatselt.

Tulemuste allikad

  • fresh: Genereeritud uue AI-töötlusega.
  • cached_exact: Kattus praeguse AI versiooni vahemäluga.
  • cached_stale: AI on võrguühenduseta ja tagastati viimane vahemällu salvestatud tulemus.
  • pending: Lõplikku tulemust veel pole.
  • failed: Ülesanne ebaõnnestus.
  • Kui ülesanne pole veel tehtud, kontrolli error_message viimase kordusproovi või ootamise põhjust.

Kvoot ja arveldus

  • Kasuta `GET /api/open/quota` enne suurte töökoormuste esitamist, kui integratsioon peab kvoodirikkeid vältima.
  • Ainult uued `fresh` AI-töötlused tarbivad kvooti.
  • `cached_exact`, `cached_stale`, `pending`ja `failed` tulemused ei tarbi kvooti.
  • Tasuta kontod kasutavad esmalt päevast kvooti. Tasulised kontod kasutavad aktiivseid perioodilisi kvoodipakette, seejärel ajutisi või fikseeritud kvoote vastavalt taustapoliitikale.
  • Kui kvota on ammendatud, tagastab ülesande esitamine `429` ja sisaldab veateadet uue ülesande loomise asemel.

Vahemälu ja tulemuste värskus

  • Taustsüsteem salvestab edukad tulemused vahemällu pildi räsi ja AI versiooni järgi, sealhulgas allavoolu teenuse namespace'i.
  • `cached_exact` tähendab, et sama pilt on juba praeguse AI versiooni jaoks edukas tulemus, seega uut AI jooksu polnud vaja.
  • `cached_stale` tähendab, et AI teenus on võrguühenduseta ja taustasüsteem tagastas viimase saadaoleva ajaloolise tulemuse.
  • Kui `is_latest_ai_version` on false, salvesta tulemus kasutatavate, kuid ülevaatamist vajavate ajalooliste andmetena.
  • Ära eelda, et iga `done` ülesanne on kulutatud kvoodi; Kontrolli `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

Loe praegust kvoodit ja ülejäänud kasutust.

Taotluse näide
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Vastuse näide
{
  "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

Loe avaliku teenistuse staatust ülesannete esitamiseks ja vahemällu salvestatud tulemuste tagavaraks.

Taotluse näide
curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Vastuse näide
{
  "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

Laadi üks pilt üles ja loo üks ülesanne.

Taotluse näide
curl -X POST "https://watermeterai.com/api/open/tasks" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \
  -F "file=@D:\data\meter_001.jpg"
Vastuse näide
{
  "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}

Loe ühe ülesande staatust ja lõplikku lugemist.

Taotluse näide
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Vastuse näide
{
  "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

Loe praeguse API võtmekasutaja hiljutisi ülesandeid.

Taotluse näide
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Vastuse näide
{
  "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

Laadi üles mitu pilti ühes päringus.

Taotluse näide
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"
Vastuse näide
{
  "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}

Loe partii edenemist ja failipõhiseid ülesande seisundeid.

Taotluse näide
curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Vastuse näide
{
  "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": ""
    }
  ]
}

Soovitatav töövoog

  • Kontrolli `GET /api/open/ai-status` enne suurte töökoormuste saatmist.
  • Salvesta `task_id` või `batch_id` kohe pärast esitamist oma süsteemis.
  • Käsitle `queued`, `running`, `waiting_ai`, `batch_waiting_ai` ja `batch_running` mittelõplike olekutena ning jätka oleku perioodilist kontrollimist.
  • Kasuta partiipäringuid, kui võrgutee taustsüsteemini on suure latentsusega ja juurutatud teenus toetab partiirežiimi.
  • Partiipäringud liiguvad praegu läbi `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` tähendab, et iga ese ootab endiselt AI teenust, ei tööta veel aktiivselt.
  • Kui juurutatud teenus on `CAD`, kasuta praegu `POST /api/open/tasks` ja käsitle partiiüleslaadimist kättesaamatuna.

Veamärkused

  • 400: kehtetu päring või juurutatud teenus ei toeta partiiüleslaadimist.
  • 401: puuduv, kehtetu, aegunud või keelatud API võti.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: ülesanne või partii ei ole leitud või ei kuulu praegusele kasutajale.
  • 413: fail on liiga suur.
  • 415: toetamata pilditüüp või kehtetu pildisisu.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 partii üleslaadimine pole saadaval
{
  "detail": "batch upload is not supported for business: cax"
}
401 puuduv või kehtetu API võti
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 fail liiga suur
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 kvoot otsa saanud
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Kas oled valmis töövoogu testima?

Kasuta esimese foto jaoks veebitööruumi ja liigu API võtmete juurde, kui tulemuse vorming sobib sinu süsteemiga.

Registreeru ja laadi foto üles.Loo API võti