WaterMeter AI
NyelvMagyar
Más nyelvek

vízmérő OCR API

vízmérő OCR API. Ez az oldal azt a nyilvános HTTP API dokumentumot dokumentálja, amelyet a webhely háttérrendszere tesz közzé harmadik féltől származó integrációkhoz.

Kezdje egy valódi feltöltéssel

Először regisztráljon, töltse fel saját vízmérő fényképét a munkaterületre, majd hozzon létre egy API kulcsot, ha készen áll az integrációra.

Regisztrálj és tölts fel egy fényképetHozzon létre egy API kulcsot

Áttekintés

  • Használja a webhely hátterét minden külső integrációhoz.
  • Ne hívja a waterMeterAi-t közvetlenül harmadik féltől származó programokból.
  • A nyitott API ugyanazokat a felhasználókat, kvótákat, gyorsítótárat, feladatokat és naplózási szabályokat használja, mint a webportál.
  • A háttérrendszer az üzembe helyezési konfigurációval megcélozhatja a különböző downstream AI vállalkozásokat.
  • A feladatválaszok mostantól tartalmaznak egy általános result_summary objektumot, így a különböző vállalkozások különböző eredménytípusokat jeleníthetnek meg.

Hitelesítés

  • Jelentkezzen be a webhelyen, és hozzon létre egy API kulcsot a API Kulcsok oldalon.
  • A teljes API kulcs csak egyszer jelenik meg a létrehozáskor.
  • Minden kérés esetén küldje el a kulcsot a Authorization fejlécben.
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

Feltöltési szabályok

  • Maximális fájlméret: 20 MB képenként.
  • Támogatott formátumok: JPEG, PNG, WEBP.
  • A háttérprogram érvényesíti a tényleges fájltartalmat, nem csak a fájlkiterjesztést.

Feltöltési méret érvényesítése

  • A kötegelt feltöltések alapértelmezés szerint legfeljebb 8 képet fogadnak el, képenkénti korláttal 20 MB és teljes fájltartalmi korláttal 20 MB.
  • A korlátot túllépő fájl vagy köteg 413-at ad vissza a képérvényesítés vagy a feladat létrehozása előtt; nem jön létre részleges köteg.
  • A háttérrendszer akkor is érvényesíti a tényleges fogadott bájtszámot, ha hiányzik a Content-Length, vagy csonka átvitelt használnak.

Feladatállapotok

  • sorban: elfogadva, és a AI feldolgozásra vár.
  • fut: jelenleg feldolgozás alatt áll, vagy már átadták a diszpécsernek, és még mindig lekérdezik a végeredményt.
  • batch_waiting_ai: a köteg minden eleme arra vár, hogy a AI szolgáltatás újra online legyen.
  • batch_running: a köteget már átadták a diszpécsernek, és még feldolgozás alatt áll.
  • kész: sikeresen befejeződött.
  • sikertelen: a feldolgozás sikertelen.
  • wait_ai: sorban áll, amíg a AI szolgáltatás újra online állapotba kerül, majd automatikusan folytatódik.

Eredményforrások

  • friss: egy új AI futtatása hozta létre.
  • cached_exact: megegyezett a jelenlegi AI verzió gyorsítótárával.
  • cached_stale: AI offline, a legutóbbi gyorsítótárazott eredmény visszakerült.
  • függőben: még nincs végeredmény.
  • sikertelen: a feladat nem sikerült.
  • Ha egy feladat még nem fejeződött be, ellenőrizze az error_message fájlt a legutóbbi újrapróbálkozás vagy várakozás okáért.

Kvóta és számlázás

  • Használja a `GET /api/open/quota`-t a nagy munkaterhelések elküldése előtt, ha az integrációnak el kell kerülnie a kvótahibákat.
  • Csak a `fresh` AI futások használnak kvótát.
  • A `cached_exact`, `cached_stale`, `pending` és `failed` eredmények nem használnak kvótát.
  • Az ingyenes fiókok először a napi kvótát használják fel. A fizetős fiókok aktív időszakos kvótacsomagokat használnak, majd ideiglenes vagy rögzített kvótát a háttérszabályzatnak megfelelően.
  • Ha a kvóta kimerült, a feladat elküldése `429` értékkel tér vissza, és hibaüzenetet tartalmaz új feladat létrehozása helyett.

Gyorsítótár és az eredmény frissessége

  • A háttérrendszer gyorsítótárazza a sikeres eredményeket a képkivonat és a AI verzió szerint, beleértve a downstream üzleti névteret is.
  • A `cached_exact` azt jelenti, hogy ugyanaz a kép már sikeres eredménye a jelenlegi AI verziónál, így nem volt szükség új AI futtatásra.
  • A `cached_stale` azt jelenti, hogy a AI szolgáltatás offline állapotban van, és a háttérrendszer a legújabb elérhető előzményeredményeket adta vissza.
  • Ha a `is_latest_ai_version` hamis, az eredményt használható, de áttekinthető előzményadatként tárolja.
  • Ne feltételezze, hogy minden `done` feladat felhasznált kvótát; ellenőrizze `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

Olvassa el az aktuális kvótát és a fennmaradó használatot.

Példa kérésre
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Válasz példa
{
  "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

Olvassa el a közszolgáltatás állapotát a feladat elküldéséhez és a gyorsítótárazott eredmények tartalékához.

Példa kérésre
curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Válasz példa
{
  "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

Töltsön fel egy képet, és hozzon létre egyetlen feladatot.

Példa kérésre
curl -X POST "https://watermeterai.com/api/open/tasks" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \
  -F "file=@D:\data\meter_001.jpg"
Válasz példa
{
  "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}

Olvassa el az egyik feladat állapotát és a végső olvasatot.

Példa kérésre
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Válasz példa
{
  "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

Olvassa el a jelenlegi API kulcsfelhasználó legutóbbi feladatait.

Példa kérésre
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Válasz példa
{
  "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

Több kép feltöltése egy kéréssel.

Példa kérésre
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"
Válasz példa
{
  "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}

Olvassa el a kötegelt előrehaladást és a fájlonkénti feladatállapotokat.

Példa kérésre
curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Válasz példa
{
  "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": ""
    }
  ]
}

Ajánlott áramlás

  • Nagy munkaterhelések küldése előtt ellenőrizze a `GET /api/open/ai-status` fájlt.
  • Tárolja a `task_id` vagy `batch_id` fájlt a saját rendszerében közvetlenül a beküldés után.
  • Kezelje a `queued`, `running`, `waiting_ai`, `batch_waiting_ai` és `batch_running` nem végleges állapotként, és folytassa a szavazást.
  • Használjon kötegelt kéréseket, ha a háttérrendszer hálózati elérési útja nagy késéssel rendelkezik, és a telepített vállalkozás támogatja a kötegelt módot.
  • A kötegelt kérések jelenleg a következőn keresztül érkeznek: `webBackend -> dispatchCenter -> waterMeterAi`.
  • A `batch_waiting_ai` azt jelenti, hogy minden elem még mindig a AI szolgáltatásra vár, még nem fut aktívan.
  • Ha a telepített vállalkozás `CAD`, használja egyelőre a `POST /api/open/tasks`-t, és kezelje a kötegelt feltöltést nem elérhetőként.

Hibajegyzetek

  • 400: érvénytelen kérés, vagy a telepített vállalkozás nem támogatja a kötegelt feltöltést.
  • 401: hiányzó, érvénytelen, lejárt vagy letiltott API kulcs.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: feladat vagy köteg nem található, vagy nem az aktuális felhasználó tulajdona.
  • 413: a fájl túl nagy.
  • 415: nem támogatott képtípus vagy érvénytelen képtartalom.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 kötegelt feltöltés nem érhető el
{
  "detail": "batch upload is not supported for business: cax"
}
401 hiányzó vagy érvénytelen API kulcs
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
A 413-as fájl túl nagy
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 kvóta kimerült
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Készen áll a munkafolyamat tesztelésére?

Használja a webes munkaterületet az első fényképhez, majd lépjen a API billentyűkre, ha az eredményformátum illeszkedik a rendszerhez.

Regisztrálj és tölts fel egy fényképetHozzon létre egy API kulcsot