WaterMeter AI
JazykČeština
Jiné jazyky

API OCR vodoměrů

API OCR vodoměrů. Tato stránka dokumentuje veřejné HTTP API vystavené backendem webu pro integrace třetích stran.

Začněte skutečným nahráváním

Nejprve se zaregistrujte, nahrajte vlastní fotografii vodoměru do pracovního prostoru a až budete připraveni k integraci, vytvořte klíč API.

Zaregistrujte se a nahrajte fotografiiVytvořte klíč API

Přehled

  • Pro všechny externí integrace použijte backend webu.
  • Nevolejte waterMeterAi přímo z programů třetích stran.
  • Otevřený API sdílí stejné uživatele, kvótu, mezipaměť, úkoly a pravidla auditu jako webový portál.
  • Backend může cílit na různé downstreamové AI podniky podle konfigurace nasazení.
  • Odpovědi na úkoly nyní zahrnují obecný objekt result_summary, takže různé podniky mohou zobrazovat různé typy výsledků.

Autentizace

  • Přihlaste se na webu a vytvořte klíč API na stránce Klíče API.
  • Úplný klíč API se zobrazí pouze jednou, když je vytvořen.
  • Odešlete klíč v záhlaví Authorization při každém požadavku.
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

Pravidla nahrávání

  • Maximální velikost souboru: 20 MB na obrázek.
  • Podporované formáty: JPEG, PNG, WEBP.
  • Backend ověřuje skutečný obsah souboru, nejen příponu souboru.

Vynucení velikosti nahrávání

  • Hromadné nahrávání přijímá ve výchozím nastavení až 8 obrázků s limitem 20 MB na obrázek a 20 MB celkového obsahu souboru.
  • Soubor nebo dávka, která překročí svůj limit, vrátí 413 před ověřením obrazu nebo vytvořením úlohy; nevytvoří se žádná dílčí dávka.
  • Backend vynucuje skutečný počet přijatých bajtů, i když chybí Content-Length nebo je použit blokový přenos.

Úkolové státy

  • ve frontě: přijato a čeká na zpracování AI.
  • běží: aktuálně se zpracovává nebo je již předán dispečerovi a stále se dotazuje na konečný výsledek.
  • batch_waiting_ai: každá položka v dávce čeká, až se služba AI vrátí online.
  • batch_running: dávka je již předána dispečerovi a stále se zpracovává.
  • hotovo: úspěšně dokončeno.
  • selhalo: zpracování se nezdařilo.
  • wait_ai: ve frontě, dokud se služba AI nevrátí do režimu online, pak se automaticky obnoví.

Zdroje výsledků

  • čerstvé: generováno novým spuštěním AI.
  • cached_exact: odpovídá mezipaměti aktuální verze AI.
  • cached_stale: AI offline, vrácen poslední výsledek z mezipaměti.
  • čeká: zatím žádný konečný výsledek.
  • selhalo: úkol se nezdařil.
  • Pokud úkol ještě není dokončen, zkontrolujte error_message pro poslední opakování nebo důvod čekání.

Kvóta a fakturace

  • Před odesláním velkých úloh použijte `GET /api/open/quota`, pokud vaše integrace potřebuje zabránit selhání kvót.
  • Pouze `fresh` AI běhy spotřebovávají kvótu.
  • Výsledky `cached_exact`, `cached_stale`, `pending` a `failed` nespotřebovávají kvótu.
  • Bezplatné účty nejprve využívají denní kvótu. Placené účty používají aktivní balíčky pravidelných kvót, poté dočasné nebo pevné kvóty podle zásad backendu.
  • Po vyčerpání kvóty vrátí odeslání úkolu `429` a namísto vytvoření nového úkolu bude obsahovat chybovou zprávu.

Čerstvost mezipaměti a výsledků

  • Backend ukládá do mezipaměti úspěšné výsledky podle hash obrázku a verze AI, včetně downstreamového obchodního jmenného prostoru.
  • `cached_exact` znamená, že stejný obrázek již má úspěšný výsledek pro aktuální verzi AI, takže nebylo potřeba žádné nové spuštění AI.
  • `cached_stale` znamená, že služba AI je offline a backend vrátil poslední dostupný historický výsledek.
  • Když je `is_latest_ai_version` nepravda, uložte výsledek jako použitelná, ale kontrolovatelná historická data.
  • Nepředpokládejte, že každý úkol `done` spotřebuje kvótu; zkontrolujte `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

Přečtěte si aktuální kvótu a zbývající využití.

Příklad žádosti
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Příklad odpovědi
{
  "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

Přečtěte si stav veřejné služby pro odeslání úlohy a záložní výsledek z mezipaměti.

Příklad žádosti
curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Příklad odpovědi
{
  "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ázek a vytvořte jeden úkol.

Příklad žádosti
curl -X POST "https://watermeterai.com/api/open/tasks" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \
  -F "file=@D:\data\meter_001.jpg"
Příklad odpovědi
{
  "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}

Přečtěte si stav jednoho úkolu a závěrečné čtení.

Příklad žádosti
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Příklad odpovědi
{
  "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

Přečtěte si nedávné úlohy vlastněné aktuálním klíčovým uživatelem API.

Příklad žádosti
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Příklad odpovědi
{
  "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 více obrázků v jedné žádosti.

Příklad žádosti
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"
Příklad odpovědi
{
  "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}

Přečtěte si průběh dávky a stavy úloh jednotlivých souborů.

Příklad žádosti
curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Příklad odpovědi
{
  "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": ""
    }
  ]
}

Doporučený průtok

  • Před odesláním velkých úloh zkontrolujte `GET /api/open/ai-status`.
  • Uložte `task_id` nebo `batch_id` ve svém vlastním systému ihned po odeslání.
  • Považujte `queued`, `running`, `waiting_ai`, `batch_waiting_ai` a `batch_running` za nekonečné stavy a pokračujte v hlasování.
  • Použijte dávkové požadavky, když má síťová cesta k backendu vysokou latenci a nasazený podnik podporuje dávkový režim.
  • Dávkové požadavky aktuálně procházejí `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` znamená, že každá položka stále čeká na službu AI a ještě není aktivně spuštěna.
  • Když je nasazená firma `CAD`, použijte prozatím `POST /api/open/tasks` a pokládejte hromadné nahrávání jako nedostupné.

Poznámky k chybám

  • 400: neplatný požadavek nebo nasazený podnik nepodporuje hromadné nahrávání.
  • 401: chybějící, neplatný, vypršela platnost nebo deaktivovaný klíč API.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: úloha nebo dávka nebyla nalezena nebo ji aktuální uživatel nevlastní.
  • 413: soubor je příliš velký.
  • 415: Nepodporovaný typ obrázku nebo neplatný obsah obrázku.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
Dávkové nahrání 400 není k dispozici
{
  "detail": "batch upload is not supported for business: cax"
}
401 chybějící nebo neplatný klíč API
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 soubor je příliš velký
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
Kvóta 429 vyčerpána
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Jste připraveni otestovat pracovní postup?

Použijte webovou pracovní plochu pro první fotografii a poté, jakmile bude výsledný formát odpovídat vašemu systému, přejděte na klávesy API.

Zaregistrujte se a nahrajte fotografiiVytvořte klíč API