WaterMeter AI
JazykSlovenčina
Iné jazyky

API na OCR vodomerov

API na OCR vodomerov. Táto stránka dokumentuje verejné HTTP API vystavené backendom webovej stránky pre integrácie tretích strán.

Začnite skutočným nahrávaním

Najprv sa zaregistrujte, nahrajte svoju vlastnú fotografiu vodomeru do pracovného priestoru a potom, keď budete pripravení na integráciu, vytvorte kľúč API.

Zaregistrujte sa a nahrajte fotografiuVytvorte kľúč API

Prehľad

  • Pre všetky externé integrácie použite backend webovej stránky.
  • Službu waterMeterAi nevolajte priamo z programov tretích strán.
  • Open API zdieľa s webovým portálom používateľov, kvótu, vyrovnávaciu pamäť, úlohy a pravidlá auditu.
  • Backend môže podľa konfigurácie nasadenia smerovať na rôzne nadväzujúce služby AI.
  • Odpovede na úlohy obsahujú všeobecný objekt result_summary, aby rôzne služby mohli zobrazovať rôzne typy výsledkov.

Autentifikácia

  • Prihláste sa na webovej lokalite a vytvorte kľúč API na stránke Kľúče API.
  • Úplný kľúč API sa zobrazí iba raz, keď je vytvorený.
  • Pri každej požiadavke odošlite kľúč v hlavičke 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

Pravidlá nahrávania

  • Maximálna veľkosť súboru: 20 MB na obrázok.
  • Podporované formáty: JPEG, PNG, WEBP.
  • Backend overuje skutočný obsah súboru, nielen príponu súboru.

Presadzovanie veľkosti nahrávania

  • Dávkové nahrávanie akceptuje štandardne až 8 obrázkov s limitom 20 MB na obrázok a 20 MB celkového obsahu súboru.
  • Súbor alebo dávka, ktorá prekročí svoj limit, vráti 413 pred overením obrázka alebo vytvorením úlohy; nevytvorí sa žiadna čiastková dávka.
  • Backend vynucuje skutočný počet prijatých bajtov, aj keď chýba Content-Length alebo sa používa blokový prenos.

Stavy úloh

  • queued: prijaté a čakajúce na spracovanie AI.
  • running: práve sa spracováva alebo už bolo odovzdané dispečerovi a stále čaká na konečný výsledok.
  • batch_waiting_ai: každá položka v dávke čaká, kým sa služba AI vráti do režimu online.
  • batch_running: dávka je už odovzdaná dispečerovi a stále sa spracováva.
  • done: úspešne dokončené.
  • failed: spracovanie zlyhalo.
  • waiting_ai: vo fronte, kým sa služba AI nevráti do režimu online; potom sa automaticky obnoví.

Zdroje výsledkov

  • fresh: vygenerované novým spustením AI.
  • cached_exact: zodpovedá aktuálnej vyrovnávacej pamäti verzie AI.
  • cached_stale: AI offline, vrátil sa posledný výsledok uložený vo vyrovnávacej pamäti.
  • pending: zatiaľ nie je k dispozícii konečný výsledok.
  • failed: úloha zlyhala.
  • Keď úloha ešte nie je dokončená, skontrolujte error_message pre posledný pokus alebo dôvod čakania.

Kvóta a fakturácia

  • Pred odoslaním veľkých pracovných zaťažení použite `GET /api/open/quota`, ak vaša integrácia potrebuje zabrániť zlyhaniam kvót.
  • Iba behy `fresh` AI spotrebúvajú kvótu.
  • Výsledky `cached_exact`, `cached_stale`, `pending` a `failed` nevyužívajú kvótu.
  • Bezplatné účty najskôr využívajú dennú kvótu. Platené účty používajú aktívne balíky pravidelných kvót, potom dočasnú alebo pevnú kvótu podľa backendovej politiky.
  • Keď je kvóta vyčerpaná, odoslanie úlohy vráti `429` a namiesto vytvorenia novej úlohy obsahuje chybové hlásenie.

Čerstvosť vyrovnávacej pamäte a výsledkov

  • Backend ukladá úspešné výsledky do vyrovnávacej pamäte podľa hashu obrázka a verzie AI vrátane menného priestoru nadväzujúcej služby.
  • `cached_exact` znamená, že rovnaký obrázok už má úspešný výsledok pre aktuálnu verziu AI, takže nebolo potrebné žiadne nové spustenie AI.
  • `cached_stale` znamená, že služba AI je offline a backend vrátil posledný dostupný historický výsledok.
  • Ak je hodnota `is_latest_ai_version` nepravdivá, uložte výsledok ako použiteľné, ale skontrolovateľné historické údaje.
  • Nepredpokladajte, že každá úloha `done` spotrebuje kvótu; skontrolujte `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

Prečítajte si aktuálnu kvótu a zostávajúce využitie.

Príklad žiadosti
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Príklad odpovede
{
  "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

Prečítajte si stav verejnej služby pre odoslanie úlohy a záložný výsledok uložený vo vyrovnávacej pamäti.

Príklad žiadosti
curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Príklad odpovede
{
  "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

Nahrajte jeden obrázok a vytvorte jednu úlohu.

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

Prečítajte si stav jednej úlohy a konečný odpočet.

Príklad žiadosti
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Príklad odpovede
{
  "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

Prečítajte si nedávne úlohy vlastnené aktuálnym kľúčovým používateľom API.

Príklad žiadosti
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Príklad odpovede
{
  "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

Nahrajte viacero obrázkov v jednej žiadosti.

Príklad žiadosti
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"
Príklad odpovede
{
  "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}

Prečítajte si priebeh dávky a stavy úloh jednotlivých súborov.

Príklad žiadosti
curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Príklad odpovede
{
  "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": ""
    }
  ]
}

Odporúčaný postup

  • Pred odoslaním veľkého pracovného zaťaženia skontrolujte `GET /api/open/ai-status`.
  • Uložte `task_id` alebo `batch_id` vo svojom vlastnom systéme ihneď po odoslaní.
  • Považujte `queued`, `running`, `waiting_ai`, `batch_waiting_ai` a `batch_running` za nekoncové stavy a pokračujte v zisťovaní stavu.
  • Dávkové požiadavky použite, keď má sieťová cesta k backendu vysokú latenciu a nasadená služba podporuje dávkový režim.
  • Dávkové požiadavky momentálne prechádzajú cez `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` znamená, že každá položka stále čaká na službu AI, ktorá ešte nie je aktívne spustená.
  • Keď je nasadená služba `CAD`, zatiaľ použite `POST /api/open/tasks` a dávkové nahrávanie považujte za nedostupné.

Poznámky k chybám

  • 400: neplatná požiadavka alebo nasadená služba nepodporuje dávkové nahrávanie.
  • 401: chýbajúci, neplatný kľúč API s vypršanou platnosťou alebo zakázaný.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: úloha alebo dávka sa nenašla alebo ju nevlastní aktuálny používateľ.
  • 413: súbor je príliš veľký.
  • 415: nepodporovaný typ obrázka alebo neplatný obsah obrázka.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
Hromadné nahrávanie 400 nie je k dispozícii
{
  "detail": "batch upload is not supported for business: cax"
}
401 chýba alebo je neplatný kľúč API
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
Súbor 413 je príliš veľký
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
Kvóta 429 je vyčerpaná
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Ste pripravení otestovať pracovný postup?

Na prvú fotografiu použite webový pracovný priestor a potom prejdite na kľúče API, keď bude formát výsledku vyhovovať vášmu systému.

Zaregistrujte sa a nahrajte fotografiuVytvorte kľúč API