WaterMeter AI
JezikSlovenščina
Drugi jeziki

Vodomer OCR API

Vodomer OCR API. Ta stran dokumentira javno HTTP API , ki ga spletna stran izpostavlja za integracije tretjih oseb.

Začnite z resničnim nalaganjem

Najprej se registrirajte, naložite svojo fotografijo vodomerja v delovno okolje in nato ustvarite API ključ, ko boste pripravljeni na integracijo.

Registrirajte se in naložite fotografijoUstvarite API ključ

Pregled

  • Za vse zunanje integracije uporabljajte spletni backend.
  • Ne kliči waterMeterAi neposredno iz programov tretjih oseb.
  • Odprti API deli iste uporabnike, kvoto, predpomnilnik, naloge in revizijska pravila kot spletni portal.
  • Backend lahko cilja na različne downstream AI podjetja glede na konfiguracijo nameščanja.
  • Odgovori na naloge zdaj vključujejo generični result_summary objekt, da lahko različna podjetja prikažejo različne vrste rezultatov.

Avtentikacija

  • Prijavite se na spletni strani in ustvarite API ključ na strani API Ključi.
  • Celoten ključ API se ob ustvarjanju prikaže le enkrat.
  • Na vsako zahtevo pošljite ključ v glavo avtorizacije.
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

Pravila za nalaganje

  • Največja velikost datoteke: 20MB na sliko.
  • Podprti formati: JPEG, PNG, WEBP.
  • Backend preverja dejansko vsebino datoteke, ne le končnice.

Izvrševanje velikosti nalaganja

  • Serijske nalaganja privzeto sprejemajo do 8 slik, z omejitvijo 20 MB na sliko in 20 MB skupne vsebine datotek.
  • Datoteka ali paket, ki preseže svoj limit, vrne 413 pred validacijo slike ali ustvarjanjem naloge; Delna serija ni ustvarjena.
  • Backend uveljavlja dejansko število prejetih bajtov tudi, ko manjka Content-Length ali je uporabljen prenos v delih.

Stanja nalog

  • V vrsti: sprejeto in čakam na AI obdelavo.
  • Teče: Trenutno se obdeluje ali pa je že predana dispečerju in še vedno išče končni rezultat.
  • batch_waiting_ai: vsak izdelek v seriji čaka, da se AI storitev ponovno aktivira.
  • batch_running: serija je že predana dispečerju in se še vedno obdeluje.
  • Končano: uspešno končano.
  • neuspešno: obdelava ni uspela.
  • waiting_ai: v vrsti, dokler se storitev AI ne ponovno poveže, nato se samodejno nadaljuje.

Rezultati Viri

  • Fresh: Ustvarjeno z novim AI tekom.
  • cached_exact: ujema se s trenutnim AI predpomnilnikom različic.
  • cached_stale: AI offline je bil vrnjen najnovejši predpomnjeni rezultat.
  • V teku: Končni rezultat še ni.
  • Neuspešno: Naloga spodletela.
  • Ko naloga še ni končana, preverite error_message za najnovejši razlog za ponovni poskus ali čakanje.

Kvota in obračunavanje

  • Uporabite `GET /api/open/quota` pred oddajo velikih obremenitev, če je vaša integracija potrebna, da se izognete neuspehu kvot.
  • Samo `fresh` AI tekem porabi kvoto.
  • `cached_exact`, `cached_stale`, `pending`in `failed` rezultati ne porabijo kvote.
  • Brezplačni računi najprej uporabijo dnevno kvoto. Plačljivi računi uporabljajo aktivne periodične kvote, nato pa začasne ali fiksne kvote glede na politiko v ozadju.
  • Ko je kvota izčrpana, oddaja naloge vrne `429` in vključi sporočilo o napaki namesto ustvarjanja nove naloge.

Predpomnilnik in svežina rezultatov

  • Backend shranjuje uspešne rezultate z zgoščevanjem slike in AI različico, vključno z nadaljnjim poslovnim imenskim prostorom.
  • `cached_exact` pomeni, da ima ista slika že uspešen rezultat za trenutno AI različico, zato ni bilo potrebe po novem AI zagonu.
  • `cached_stale` pomeni, da je AI storitev nedosegljiva in da je backend vrnil najnovejši razpoložljivi zgodovinski rezultat.
  • Ko je `is_latest_ai_version` napačno, shranite rezultat kot uporabne, a pregledljive zgodovinske podatke.
  • Ne predpostavljajte, da je vsaka `done` naloga porabljena kot kvota; Preveri `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

Preberite trenutno kvoto in preostalo porabo.

Primer zahteve
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Primer odziva
{
  "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

Preberite status javne storitve za oddajo nalog in predpomnjeno vračilo rezultatov.

Primer zahteve
curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Primer odziva
{
  "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

Naloži eno sliko in ustvari eno nalogo.

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

Preberi eno nalogo, status naloge in končno branje.

Primer zahteve
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Primer odziva
{
  "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

Preberite nedavne naloge, ki jih ima trenutni API ključni uporabnik.

Primer zahteve
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Primer odziva
{
  "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

Naložite več slik v eni zahtevi.

Primer zahteve
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"
Primer odziva
{
  "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}

Preberite serijski napredek in stanja nalog za posamezne datoteke.

Primer zahteve
curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Primer odziva
{
  "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": ""
    }
  ]
}

Priporočeni pretok

  • Preverite `GET /api/open/ai-status` , preden pošljete velike obremenitve.
  • Takoj po oddaji shranite `task_id` ali `batch_id` v svoj sistem.
  • Obravnavajte `queued`, `running`, `waiting_ai`, `batch_waiting_ai`in `batch_running` kot nekončna stanja in nadaljujte z anketiranjem.
  • Uporabite serijske zahteve, kadar ima omrežna pot do zaledja visoko zakasnitev in podjetje podpira serijski način.
  • Serijske zahteve trenutno tečejo skozi `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` pomeni, da vsak izdelek še vedno čaka na AI storitev in še ni aktiven.
  • Ko je nameščeno podjetje `CAD`, za zdaj uporabite `POST /api/open/tasks` in obravnavajte serijsko nalaganje kot nedosegljivo.

Opombe o napakah

  • 400: neveljavna zahteva ali pa podjetje ne podpira serijskega nalaganja.
  • 401: manjka, neveljavna, potekla ali onemogočena API ključ.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: naloga ali paket ni najden ali ni v lasti trenutnega uporabnika.
  • 413: Datoteka je prevelika.
  • 415: nepodprta vrsta slike ali neveljavna vsebina slike.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 serijsko nalaganje ni na voljo
{
  "detail": "batch upload is not supported for business: cax"
}
401 manjka ali je API ključ neveljaven
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 datoteka prevelika
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 kvota izčrpana
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Ste pripravljeni preizkusiti potek dela?

Uporabite spletni delovni prostor za prvo fotografijo, nato pa preidite na API tipke, ko se rezultat prilega vašemu sistemu.

Registrirajte se in naložite fotografijoUstvarite API ključ