WaterMeter AI
SprogDansk
Andre sprog

API til OCR af vandmålere

API til OCR af vandmålere. Denne side dokumenterer den offentlige HTTP API, som eksponeres af webstedets backend for tredjeparts integrationer.

Start med en rigtig upload

Registrer først, upload dit eget vandmålerbillede i arbejdsområdet, og opret derefter en API nøgle, når du er klar til at integrere.

Registrer og upload et billedeOpret en API nøgle

Oversigt

  • Brug hjemmesidens backend til alle eksterne integrationer.
  • Ring ikke til waterMeterAi direkte fra tredjepartsprogrammer.
  • Den åbne API deler de samme brugere, kvoter, cache, opgaver og revisionsregler som webportalen.
  • Backend'en kan målrette mod forskellige downstream AI-virksomheder ved implementeringskonfiguration.
  • Opgavesvar inkluderer nu et generisk resultat_summary-objekt, så forskellige virksomheder kan vise forskellige resultattyper.

Autentificering

  • Log ind på webstedet, og opret en API nøgle på siden API Keys.
  • Den fulde API nøgle vises kun én gang, når den er oprettet.
  • Send nøglen i Authorization-headeren ved hver anmodning.
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

Regler for upload

  • Maksimal filstørrelse: 20 MB pr. billede.
  • Understøttede formater: JPEG, PNG, WEBP.
  • Backend validerer faktisk filindhold, ikke kun filtypenavnet.

Håndhævelse af uploadstørrelse

  • Batchuploads accepterer som standard op til 8 billeder med en grænse på 20 MB pr. billede og en samlet grænse for filindhold på 20 MB.
  • En fil eller batch, der overskrider sin grænse, returnerer 413 før billedvalidering eller opgaveoprettelse; der oprettes ingen partiel batch.
  • Backend håndhæver det faktiske modtagne byteantal, selv når Content-Length mangler, eller der bruges chunked overførsel.

Opgavestater

  • i kø: accepteret og venter på AI-behandling.
  • kører: i øjeblikket behandles, eller allerede afleveret til afsenderen og stadig polling for det endelige resultat.
  • batch_waiting_ai: hvert element i batchen venter på, at AI-tjenesten kommer online igen.
  • batch_running: batchen er allerede afleveret til afsenderen og behandles stadig.
  • udført: afsluttet med succes.
  • mislykkedes: behandling mislykkedes.
  • waiting_ai: i kø, indtil AI-tjenesten kommer online igen, så genoptages den automatisk.

Resultatkilder

  • fresh: genereret af en ny AI kørsel.
  • cached_exact: matchede den aktuelle AI-versionscache.
  • cached_stale: AI offline, seneste cachelagrede resultat returneret.
  • afventer: intet endeligt resultat endnu.
  • mislykkedes: opgaven mislykkedes.
  • Når en opgave ikke er udført endnu, skal du kontrollere fejlmeddelelse for det seneste forsøg eller ventende årsag.

Kontingent og fakturering

  • Brug `GET /api/open/quota`, før du indsender store arbejdsbelastninger, hvis din integration skal undgå kvotefejl.
  • Kun `fresh` AI-kørsler bruger kvote.
  • Resultaterne `cached_exact`, `cached_stale`, `pending` og `failed` optager ikke kvoten.
  • Gratis konti bruger først den daglige kvote. Betalte konti bruger aktive periodiske kvotepakker, derefter midlertidig eller fast kvote i henhold til backend-politikken.
  • Når kvoten er opbrugt, returnerer opgaveafsendelse `429` og inkluderer en fejlmeddelelse i stedet for at oprette en ny opgave.

Cache og resultatfriskhed

  • Backend'en cacher vellykkede resultater efter billedhash og AI-version, inklusive downstream-virksomhedens navneområde.
  • `cached_exact` betyder, at det samme billede allerede har et vellykket resultat for den nuværende AI-version, så der var ikke behov for en ny AI-kørsel.
  • `cached_stale` betyder, at AI-tjenesten er offline, og backend returnerede det seneste tilgængelige historiske resultat.
  • Når `is_latest_ai_version` er falsk, skal du gemme resultatet som brugbare, men gennemseelige historiske data.
  • Antag ikke hver `done` opgave forbrugt kvote; tjek `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

Læs den aktuelle kvote og resterende brug.

Eksempel på anmodning
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Eksempel på svar
{
  "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

Læs public service-status for indsendelse af opgave og cache-resultat fallback.

Eksempel på anmodning
curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Eksempel på svar
{
  "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 et billede og lav en enkelt opgave.

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

Læs en opgavestatus og afsluttende læsning.

Eksempel på anmodning
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Eksempel på svar
{
  "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

Læs seneste opgaver ejet af den nuværende API nøglebruger.

Eksempel på anmodning
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Eksempel på svar
{
  "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 flere billeder på én anmodning.

Eksempel på anmodning
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"
Eksempel på svar
{
  "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}

Læs batchfremskridt og opgavetilstande pr. fil.

Eksempel på anmodning
curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Eksempel på svar
{
  "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": ""
    }
  ]
}

Anbefalet flow

  • Tjek `GET /api/open/ai-status` før du sender store arbejdsbelastninger.
  • Gem `task_id` eller `batch_id` i dit eget system umiddelbart efter indsendelse.
  • Behandl `queued`, `running`, `waiting_ai`, `batch_waiting_ai` og `batch_running` som ikke-endelige tilstande, og fortsæt med at stemme.
  • Brug batch-anmodninger, når netværksstien til backend har høj latenstid, og den implementerede virksomhed understøtter batch-tilstand.
  • Batch-anmodninger flyder i øjeblikket gennem `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` betyder, at hvert element stadig venter på AI-tjenesten, og det kører ikke aktivt endnu.
  • Når den implementerede virksomhed er `CAD`, skal du bruge `POST /api/open/tasks` indtil videre og behandle batchupload som utilgængelig.

Fejlnoter

  • 400: ugyldig anmodning, eller den implementerede virksomhed understøtter ikke batchupload.
  • 401: manglende, ugyldig, udløbet eller deaktiveret API-nøgle.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: opgave eller batch ikke fundet eller ejet af den aktuelle bruger.
  • 413: filen er for stor.
  • 415: ikke-understøttet billedtype eller ugyldigt billedindhold.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 batch-upload ikke tilgængelig
{
  "detail": "batch upload is not supported for business: cax"
}
401 manglende eller ugyldig API-nøgle
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 fil for stor
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 kvote opbrugt
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Klar til at teste arbejdsgangen?

Brug webarbejdsområdet til det første billede, og flyt derefter til API-tasterne, når resultatformatet passer til dit system.

Registrer og upload et billedeOpret en API nøgle