WaterMeter AI
LimbaRomână
Alte limbi

API OCR pentru contoare de apă

API OCR pentru contoare de apă. Această pagină documentează HTTP API public expus de backend-ul site-ului web pentru integrări terțe.

Începeți cu o încărcare reală

Înregistrați-vă mai întâi, încărcați propria fotografie a contorului de apă în spațiul de lucru și apoi creați o cheie API când sunteți gata de integrare.

Înregistrați-vă și încărcați o fotografieCreați o cheie API

Prezentare generală

  • Utilizați backend-ul site-ului web pentru toate integrările externe.
  • Nu apelați waterMeterAi direct din programe terțe.
  • API deschis partajează aceiași utilizatori, cotă, cache, sarcini și reguli de audit ca și portalul web.
  • Backend-ul poate viza diferite afaceri AI din aval prin configurația de implementare.
  • Răspunsurile la sarcini includ acum un obiect generic result_summary, astfel încât diferitele companii să poată afișa diferite tipuri de rezultate.

Autentificare

  • Conectați-vă pe site și creați o cheie API pe pagina Chei API.
  • Cheia completă API este afișată o singură dată când este creată.
  • Trimiteți cheia în antetul Authorization la fiecare solicitare.
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

Încărcați reguli

  • Dimensiunea maximă a fișierului: 20 MB per imagine.
  • Formate acceptate: JPEG, PNG, WEBP.
  • Backend-ul validează conținutul real al fișierului, nu doar extensia fișierului.

Aplicarea dimensiunii încărcării

  • Încărcările în lot acceptă până la 8 imagini în mod implicit, cu o limită de 20 MB per imagine și o limită totală de conținut de fișiere de 20 MB.
  • Un fișier sau un lot care depășește limita returnează 413 înainte de validarea imaginii sau crearea sarcinii; nu este creat nici un lot parțial.
  • Backend-ul impune numărul real de octeți primiți chiar și atunci când Content-Length lipsește sau este utilizat transferul în bucăți.

Statele de sarcină

  • în coadă: acceptat și în așteptarea procesării AI.
  • în curs de desfășurare: în curs de procesare, sau deja predat dispecerului și încă se interoghează pentru rezultatul final.
  • batch_waiting_ai: fiecare articol din lot așteaptă ca serviciul AI să revină online.
  • batch_running: lotul este deja predat dispecerului și este încă în procesare.
  • terminat: terminat cu succes.
  • failed: procesarea a eșuat.
  • waiting_ai: în coadă până când serviciul AI revine online, apoi se reia automat.

Surse de rezultate

  • fresh: generat de o nouă rulare AI.
  • cached_exact: s-a potrivit cu versiunea cache curentă AI.
  • cached_stale: AI offline, a fost returnat cel mai recent rezultat memorat în cache.
  • în așteptare: încă nu există un rezultat final.
  • failed: sarcina a eșuat.
  • Când o sarcină nu este încă finalizată, verificați mesajul error pentru ultima reîncercare sau motivul așteptării.

Cotă și facturare

  • Utilizați `GET /api/open/quota` înainte de a trimite sarcini mari de lucru dacă integrarea dvs. trebuie să evite eșecurile cotei.
  • Numai `fresh` AI rulează cota de consum.
  • Rezultatele `cached_exact`, `cached_stale`, `pending` și `failed` nu consumă cotă.
  • Conturile gratuite folosesc mai întâi cota zilnică. Conturile plătite folosesc pachete de cote periodice active, apoi cotă temporară sau fixă, conform politicii de backend.
  • Când cota este epuizată, trimiterea sarcinii returnează `429` și include un mesaj de eroare în loc să creeze o nouă sarcină.

Cache-ul și prospețimea rezultatelor

  • Backend-ul memorează în cache rezultatele de succes prin hash de imagine și versiunea AI, inclusiv spațiul de nume de afaceri din aval.
  • `cached_exact` înseamnă că aceeași imagine are deja un rezultat de succes pentru versiunea curentă AI, deci nu a fost necesară o nouă rulare AI.
  • `cached_stale` înseamnă că serviciul AI este offline și backend-ul a returnat cel mai recent rezultat istoric disponibil.
  • Când `is_latest_ai_version` este fals, stocați rezultatul ca date istorice utilizabile, dar care pot fi revizuite.
  • Nu vă asumați fiecare cotă consumată de `done` sarcini; verificați `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

Citiți cota actuală și utilizarea rămasă.

Exemplu de solicitare
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exemplu de răspuns
{
  "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

Citiți starea serviciului public pentru trimiterea sarcinilor și soluția de rezervă a rezultatelor stocate în cache.

Exemplu de solicitare
curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exemplu de răspuns
{
  "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

Încărcați o imagine și creați o singură sarcină.

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

Citiți starea unei sarcini și citirea finală.

Exemplu de solicitare
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exemplu de răspuns
{
  "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

Citiți sarcinile recente deținute de utilizatorul cheie API actual.

Exemplu de solicitare
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exemplu de răspuns
{
  "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

Încărcați mai multe imagini într-o singură solicitare.

Exemplu de solicitare
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"
Exemplu de răspuns
{
  "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}

Citiți progresul lotului și stările sarcinilor pe fișier.

Exemplu de solicitare
curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exemplu de răspuns
{
  "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": ""
    }
  ]
}

Debit recomandat

  • Verificați `GET /api/open/ai-status` înainte de a trimite încărcături mari de lucru.
  • Stocați `task_id` sau `batch_id` în propriul sistem imediat după trimitere.
  • Tratați `queued`, `running`, `waiting_ai`, `batch_waiting_ai` și `batch_running` ca stări nefinale și continuați să sondați.
  • Utilizați solicitări în lot atunci când calea de rețea către backend are o latență ridicată și afacerea implementată acceptă modul batch.
  • În prezent, solicitările în loturi sunt transmise prin `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` înseamnă că fiecare articol încă așteaptă serviciul AI, care nu este încă în funcțiune activ.
  • Când afacerea implementată este `CAD`, utilizați `POST /api/open/tasks` deocamdată și tratați încărcarea în lot ca indisponibilă.

Note de eroare

  • 400: cerere nevalidă sau afacerea implementată nu acceptă încărcarea în lot.
  • 401: cheie API lipsă, invalidă, expirată sau dezactivată.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: sarcina sau lotul nu a fost găsit sau nu este deținut de utilizatorul curent.
  • 413: fișier prea mare.
  • 415: tip de imagine neacceptat sau conținut de imagine nevalid.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
Încărcare în loturi de 400 indisponibile
{
  "detail": "batch upload is not supported for business: cax"
}
401 cheie API lipsă sau nevalidă
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 fișier prea mare
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 cota epuizata
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Sunteți gata să testați fluxul de lucru?

Utilizați spațiul de lucru web pentru prima fotografie, apoi treceți la tastele API odată ce formatul rezultat se potrivește sistemului dvs.

Înregistrați-vă și încărcați o fotografieCreați o cheie API