WaterMeter AI
JezikBosanski
Ostali jezici

API za OCR vodomjera

API za OCR vodomjera. Ova stranica dokumentuje javne HTTP API izložene od strane backenda web stranice za integracije trećih strana.

Počni sa pravim uploadom

Prvo se registrujte, postavite vlastitu fotografiju vodomjera u radni prostor, a zatim kreirajte API ključ kada budete spremni za integraciju.

Registrujte se i postavite fotografijuKreirajte API ključ

Pregled

  • Koristite web backend za sve eksterne integracije.
  • Nemojte waterMeterAi zvati direktno iz programa trećih strana.
  • Otvoreni API dijeli iste korisnike, kvotu, keš, zadatke i pravila revizije kao i web portal.
  • Backend može ciljati različite downstream AI poslovanja prema konfiguraciji implementacije.
  • Odgovori na zadatke sada uključuju generički result_summary objekat kako bi različite firme mogle prikazati različite tipove rezultata.

Autentifikacija

  • Prijavite se na web stranici i kreirajte API ključ na stranici API Keys.
  • Puni API ključ se prikazuje samo jednom prilikom kreiranja.
  • Pošaljite ključ u Authorization header na svaki zahtjev.
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 učitavanje

  • Maksimalna veličina fajla: 20MB po slici.
  • Podržani formati: JPEG, PNG, WEBP.
  • Backend provjerava stvarni sadržaj fajla, ne samo ekstenziju.

Provođenje veličine uploada

  • Batch uploadovi podrazumijevano prihvataju do 8 slika, sa ograničenjem od 20MB po slici i ograničenjem ukupnog sadržaja datoteke od 20MB.
  • Datoteka ili batch koji premaši svoj limit vraća 413 prije validacije slike ili kreiranja zadatka; Ne kreira se djelimična serija.
  • Backend provodi stvarni broj primljenih bajtova čak i kada nedostaje Content-Length ili se koristi chunked transfer.

Stanja zadatka

  • U redu čekanja: Prihvaćeno i čeka AI obradu.
  • Pokretanje: Trenutno se obrađuje, ili je već predata dispečeru i još uvijek traži konačni rezultat.
  • batch_waiting_ai: svaki artikl u seriji čeka da AI usluga ponovo bude online.
  • batch_running: serija je već predata dispečeru i još uvijek se obrađuje.
  • Gotovo: Uspješno završeno.
  • Neuspjelo: Obrada nije uspjela.
  • waiting_ai: u redu dok se AI servis ne vrati online, zatim se automatski nastavlja.

Izvori rezultata

  • Fresh: Generisano novim AI runom.
  • cached_exact: uskladio se sa trenutnim kešom verzije AI .
  • cached_stale: AI offline, posljednji keširani rezultat je vraćen.
  • Na ČEKANJU: Još nema konačnog rezultata.
  • Neuspjeh: Zadatak nije uspio.
  • Kada zadatak još nije završen, provjerite error_message za najnoviji razlog ponovnog pokušaja ili čekanja.

Kvota i naplata

  • Koristite `GET /api/open/quota` prije slanja velikih radnih opterećenja ako vaša integracija treba izbjeći neuspjeh kvota.
  • Samo `fresh` AI trčanja troše kvotu.
  • `cached_exact`, `cached_stale`, `pending`i `failed` rezultati ne troše kvotu.
  • Besplatni nalozi prvo koriste dnevnu kvotu. Plaćeni računi koriste aktivne periodične kvote, zatim privremene ili fiksne kvote prema backend politici.
  • Kada se kvota iscrpi, predaja zadatka vraća `429` i uključuje poruku o grešci umjesto kreiranja novog zadatka.

Keš i svježina rezultata

  • Backend kešira uspješne rezultate pomoću heša slike i AI verzije, uključujući i downstream poslovni imenski prostor.
  • `cached_exact` znači da ista slika već ima uspješan rezultat za trenutnu AI verziju, pa nije bilo potrebe za novim AI pokretanjem.
  • `cached_stale` znači da je AI servis offline i da je backend vratio najnoviji dostupni historijski rezultat.
  • Kada je `is_latest_ai_version` netačan, sačuvajte rezultat kao upotrebljive, ali pregledive historijske podatke.
  • Nemojte pretpostavljati da je svaki `done` zadatak potrošen kao kvota; provjeri `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

Pročitajte trenutnu kvotu i preostalu potrošnju.

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

Pročitajte status javne usluge za slanje zadataka i keširani rezultat kao rezervni odgovor.

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

Učitaj jednu sliku i kreiraj jedan zadatak.

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

Pročitaj jedan status zadatka i završno čitanje.

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

Pročitajte nedavne zadatke koje trenutno posjeduje API ključni korisnik.

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

Učitaj više slika u jednom zahtjevu.

Primjer zahtjeva
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"
Primjer odgovora
{
  "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}

Čitajte batch progress i stanja zadatka po datoteci.

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

Preporučeni protok

  • Provjerite `GET /api/open/ai-status` prije nego što pošaljete velike zadatke.
  • Sačuvajte `task_id` ili `batch_id` u svom sistemu odmah nakon predaje.
  • Tretirajte `queued`, `running`, `waiting_ai`, `batch_waiting_ai`i `batch_running` kao nekonačna stanja i nastavite sa anketiranjem.
  • Koristite batch zahtjeve kada mrežni put do backenda ima visoku latenciju, a implementirani biznis podržava batch režim.
  • Batch zahtjevi trenutno prolaze kroz `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` znači da svaki artikl još uvijek čeka na AI servis, nije aktivan.
  • Kada je implementirani biznis `CAD`, koristite `POST /api/open/tasks` za sada i tretirajte batch upload kao nedostupan.

Bilješke o greškama

  • 400: nevažeći zahtjev ili implementirani biznis ne podržava batch upload.
  • 401: nedostaje, nevažeći, istekao ili onemogućen 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: zadatak ili batch nije pronađen, ili nije u vlasništvu trenutnog korisnika.
  • 413: Fajl je prevelik.
  • 415: nepodržani tip slike ili nevažeći sadržaj slike.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 batch upload nije dostupan
{
  "detail": "batch upload is not supported for business: cax"
}
401 nedostaje ili je nevažeći API ključ
{
  "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 iscrpljena
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Spremni da testirate radni tok?

Koristite web radni prostor za prvu fotografiju, zatim pređite na API tipke kada format rezultata odgovara vašem sistemu.

Registrujte se i postavite fotografijuKreirajte API ključ