WaterMeter AI
LlenguaCatalà
Altres llengües

API OCR de comptadors d’aigua

API OCR de comptadors d’aigua. Aquesta pàgina documenta el HTTP API públic exposat pel backend del lloc web per a integracions de tercers.

Comença amb una pujada real

Registra't primer, penja la teva pròpia foto del comptador d'aigua a l'espai de treball i després crea una clau API quan estiguis preparat per integrar.

Registra't i puja una fotoCrea una clau API

Visió general

  • Utilitza el backend del lloc web per a totes les integracions externes.
  • No truquis directament a waterMeterAi des de programes de tercers.
  • L'API oberta comparteix els mateixos usuaris, quotes, memòria cau, tasques i regles d'auditoria que el portal web.
  • El backend pot utilitzar diferents serveis d'AI descendents segons la configuració de desplegament.
  • Les respostes de les tasques inclouen un objecte result_summary genèric perquè diferents serveis puguin mostrar diferents tipus de resultats.

Autenticació

  • Inicia sessió al lloc web i crea una clau API a la pàgina API Claus.
  • La clau API completa només es mostra una vegada quan es crea.
  • Envia la clau a l'encapçalament d'Authorization a cada petició.
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

Regles de pujada

  • Mida màxima del fitxer: 20MB per imatge.
  • Formats compatibles: JPEG, PNG, WEBP.
  • El backend valida el contingut real del fitxer, no només l'extensió.

Aplicació de la mida de la pujada

  • Les pujades per lots accepten fins a 8 imatges per defecte, amb un límit de 20MB per imatge i un límit total de contingut de fitxer de 20MB.
  • Un fitxer o lot que supera el seu límit retorna 413 abans de la validació de la imatge o la creació de tasques; No es crea cap lot parcial.
  • El backend aplica el recompte real de bytes rebuts fins i tot quan falta Content-Length o s'utilitza una transferència fragmentada.

Estats de la tasca

  • queued: Acceptada i esperant el processament de l'AI.
  • running: S'està processant, o ja s'ha lliurat al despatxador i se'n comprova periòdicament l'estat per obtenir el resultat final.
  • batch_waiting_ai: Tots els elements del lot esperen que el servei d'AI torni a estar en línia.
  • batch_running: El lot ja s'ha lliurat al despatxador i encara s'està processant.
  • done: Ha finalitzat correctament.
  • failed: El processament ha fallat.
  • waiting_ai: Es manté en cua fins que el servei d'AI torna a estar en línia i després es reprèn automàticament.

Fonts dels resultats

  • fresh: Generat per un processament nou de l'AI.
  • cached_exact: Coincideix amb la memòria cau de la versió actual de l'AI.
  • cached_stale: L'AI està fora de línia i s'ha retornat l'últim resultat de la memòria cau.
  • pending: Encara no hi ha cap resultat final.
  • failed: La tasca ha fallat.
  • Quan una tasca encara no estigui acabada, comprova error_message el darrer intent o motiu d'espera.

Quota i facturació

  • Utilitza `GET /api/open/quota` abans d'enviar càrregues de treball grans si la teva integració ha d'evitar fallades en quotes.
  • Només els processaments nous d'AI amb resultat `fresh` consumeixen quota.
  • `cached_exact`, `cached_stale`, `pending`, i `failed` resultats no consumeixen quota.
  • Els comptes gratuïts utilitzen primer la quota diària. Els comptes de pagament utilitzen paquets de quotes periòdiques actives, i després quotes temporals o fixes segons la política de backend.
  • Quan s'esgota la quota, la presentació de tasques retorna `429` i inclou un missatge d'error en lloc de crear una tasca nova.

Memòria cau i frescor dels resultats

  • El backend desa a la memòria cau els resultats correctes segons el hash de la imatge i la versió de l'AI, inclòs el namespace del servei descendent.
  • `cached_exact` vol dir que la mateixa imatge ja té un resultat reeixit per a la versió AI actual, així que no calia cap nova execució AI .
  • `cached_stale` vol dir que el servei de AI està fora de línia i que el backend ha retornat el darrer resultat històric disponible.
  • Quan `is_latest_ai_version` sigui false, desa el resultat com a dades històriques utilitzables però revisables.
  • No assumeixis que cada `done` tasca consumida és una quota; Comprova `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

Llegeix la quota actual i l'ús restant.

Exemple de sol·licitud
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exemple de resposta
{
  "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

Llegeix l'estat del servei públic per a l'enviament de tasques i la reserva de resultats en memòria cau.

Exemple de sol·licitud
curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exemple de resposta
{
  "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

Puja una imatge i crea una sola tasca.

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

Llegeix l'estat d'una tasca i la lectura final.

Exemple de sol·licitud
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exemple de resposta
{
  "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

Llegeix les tasques recents propietat de l'usuari API clau actual.

Exemple de sol·licitud
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exemple de resposta
{
  "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

Puja diverses imatges en una sola sol·licitud.

Exemple de sol·licitud
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"
Exemple de resposta
{
  "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}

Llegeix el progrés per lots i els estats de la tasca per fitxer.

Exemple de sol·licitud
curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exemple de resposta
{
  "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": ""
    }
  ]
}

Flux recomanat

  • Comprova `GET /api/open/ai-status` abans d'enviar càrregues de treball grans.
  • Guarda `task_id` o `batch_id` al teu propi sistema immediatament després d'enviar-la.
  • Tracta `queued`, `running`, `waiting_ai`, `batch_waiting_ai` i `batch_running` com a estats no definitius i continua comprovant-ne periòdicament l'estat.
  • Utilitza peticions per lots quan el camí de xarxa cap al backend tingui una latència alta i el servei desplegat admeti el mode per lots.
  • Les peticions per lots actualment flueixen a través `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` vol dir que cada article encara està esperant el servei de AI , encara no està en funcionament actiu.
  • Quan el servei desplegat sigui `CAD`, utilitza `POST /api/open/tasks` de moment i considera que la pujada per lots no està disponible.

Notes d'error

  • 400: sol·licitud invàlida, o el servei desplegat no admet la pujada per lots.
  • 401: falta la clau d'API, no és vàlida, ha caducat o està desactivada.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: tasca o lot no trobat, o que no és propietat de l'usuari actual.
  • 413: arxiu massa gran.
  • 415: tipus d'imatge no suportat o contingut d'imatge invàlid.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 càrrega per lots no disponible
{
  "detail": "batch upload is not supported for business: cax"
}
401 clau de API absent o invàlida
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 arxiu massa gran
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 quota esgotada
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Preparat per provar el flux de treball?

Utilitza l'espai de treball web per a la primera foto i passa a les claus d'API quan el format del resultat s'adapti al teu sistema.

Registra't i puja una fotoCrea una clau API