WaterMeter AI
TaalNederlands
Andere talen

watermeter-OCR-API

watermeter-OCR-API. Deze pagina documenteert de openbare HTTP API die door de backend van de website wordt vrijgegeven voor integraties van derden.

Begin met een echte upload

Registreer eerst, upload uw eigen watermeterfoto in de workspace en maak daarna een API-sleutel wanneer u klaar bent voor integratie.

Registreren en foto uploadenAPI-sleutel maken

Overzicht

  • Gebruik de website-backend voor alle externe integraties.
  • Roep waterMeterAi niet rechtstreeks aan vanuit programma's van derden.
  • De open API deelt dezelfde gebruikers, quota, cache, taken en auditregels als de webportal.
  • De backend kan zich richten op verschillende downstream AI bedrijven via de implementatieconfiguratie.
  • Taakreacties bevatten nu een generiek object result_summary, zodat verschillende bedrijven verschillende resultaattypen kunnen weergeven.

Authenticatie

  • Meld u aan op de website en maak een API sleutel op de pagina API Sleutels.
  • De volledige API sleutel wordt slechts één keer weergegeven wanneer deze wordt aangemaakt.
  • Stuur bij elk verzoek de sleutel in de Autorisatie-header.
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

Uploadregels

  • Maximale bestandsgrootte: 20MB per afbeelding.
  • Ondersteunde formaten: JPEG, PNG, WEBP.
  • De backend valideert de daadwerkelijke bestandsinhoud, niet alleen de bestandsextensie.

Handhaving van uploadgrootte

  • Batchuploads accepteren standaard maximaal 8 afbeeldingen, met een limiet van 20 MB per afbeelding en een totale limiet voor de bestandsinhoud van 20 MB.
  • Een bestand of batch die de limiet overschrijdt, retourneert 413 voordat de afbeelding wordt gevalideerd of een taak wordt gemaakt; er wordt geen gedeeltelijke batch gemaakt.
  • De backend dwingt het daadwerkelijke aantal ontvangen bytes af, zelfs als Content-Length ontbreekt of als er een gefragmenteerde overdracht wordt gebruikt.

Taakstaten

  • queued: geaccepteerd en wacht op verwerking van AI.
  • running: wordt momenteel verwerkt of is al aan de coördinator overhandigd en wordt nog gevraagd naar het eindresultaat.
  • batch_waiting_ai: elk item in de batch wacht tot de AI service weer online komt.
  • batch_running: de batch is al overgedragen aan de verzender en wordt nog verwerkt.
  • done: succesvol afgerond.
  • failed: verwerking van failed.
  • waiting_ai: queued totdat de AI service weer online komt, waarna deze automatisch wordt hervat.

Resultaatbronnen

  • fresh: gegenereerd door een nieuwe AI run.
  • cached_exact: komt overeen met de huidige AI versiecache.
  • cached_stale: AI offline, laatste resultaat in cache geretourneerd.
  • pending: nog geen eindresultaat.
  • failed: de taak failed.
  • Wanneer een taak nog geen done is, controleer dan error_message voor de laatste reden voor nieuwe pogingen of wachten.

Quota en facturering

  • Gebruik `GET /api/open/quota` voordat je grote workloads indient als je integratie quota-fouten moet voorkomen.
  • Alleen `fresh` AI-runs verbruiken quota.
  • `cached_exact`, `cached_stale`, `pending` en `failed` resultaten verbruiken geen quota.
  • Gratis accounts gebruiken eerst het dagquota. Betaalde accounts gebruiken actieve periodieke quotapakketten en daarna tijdelijk of vast quota volgens het backendbeleid.
  • Wanneer het quota op is, retourneert taakindiening `429` met een foutmelding in plaats van een nieuwe taak te maken.

Cache en resultaatversheid

  • De backend cachet succesvolle resultaten op basis van afbeeldingshash en AI-versie, inclusief de namespace van de downstream business.
  • `cached_exact` betekent dat dezelfde afbeelding al een succesvol resultaat heeft voor de huidige AI-versie, dus er was geen nieuwe AI-run nodig.
  • `cached_stale` betekent dat de AI-service offline is en de backend het nieuwste beschikbare historische resultaat heeft teruggegeven.
  • Wanneer `is_latest_ai_version` false is, bewaar het resultaat als bruikbare maar controleerbare historische data.
  • Ga er niet van uit dat elke `done` taak quota verbruikte; controleer `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

Lees het huidige quotum en het resterende gebruik.

Voorbeeld aanvragen
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Reactie voorbeeld
{
  "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

Lees de status van de openbare dienst voor het indienen van taken en het terugvallen van gecachte resultaten.

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

Upload één afbeelding en maak één taak.

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

Lees één taakstatus en uiteindelijke lezing.

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

Lees recente taken die eigendom zijn van de huidige API-keygebruiker.

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

Upload meerdere afbeeldingen in één verzoek.

Voorbeeld aanvragen
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"
Reactie voorbeeld
{
  "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}

Lees de batchvoortgang en taakstatussen per bestand.

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

Aanbevolen stroom

  • Controleer `GET /api/open/ai-status` voordat u grote werklasten verzendt.
  • Bewaar `task_id` of `batch_id` onmiddellijk na indiening in uw eigen systeem.
  • Behandel `queued`, `running`, `waiting_ai`, `batch_waiting_ai` en `batch_running` als niet-definitieve staten en blijf peilen.
  • Gebruik batchaanvragen wanneer het netwerkpad naar de backend een hoge latentie heeft en het geïmplementeerde bedrijf de batchmodus ondersteunt.
  • Batchverzoeken lopen momenteel via `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` betekent dat elk item nog steeds wacht op de AI service, en nog niet actief running is.
  • Wanneer het geïmplementeerde bedrijf `CAD` is, gebruikt u voorlopig `POST /api/open/tasks` en beschouwt u batchupload als niet beschikbaar.

Foutopmerkingen

  • 400: ongeldig verzoek, of het geïmplementeerde bedrijf ondersteunt geen batch-upload.
  • 401: ontbrekende, ongeldige, verlopen of uitgeschakelde API-sleutel.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: taak of batch niet gevonden of geen eigendom van de huidige gebruiker.
  • 413: bestand te groot.
  • 415: niet-ondersteund afbeeldingstype of ongeldige afbeeldingsinhoud.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 batch-upload niet beschikbaar
{
  "detail": "batch upload is not supported for business: cax"
}
401 ontbrekende of ongeldige API-sleutel
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413-bestand te groot
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429-quotum uitgeput
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Klaar om de workflow te testen?

Gebruik de webworkspace voor de eerste foto en ga daarna naar API-sleutels zodra het resultaatformaat past.

Registreren en foto uploadenAPI-sleutel maken