WaterMeter AI
SpråkSvenska
Andra språk

API för OCR av vattenmätare

API för OCR av vattenmätare. Den här sidan dokumenterar den offentliga HTTP API som exponeras av webbplatsens backend för tredjepartsintegrationer.

Börja med en riktig uppladdning

Registrera dig först, ladda upp ditt eget vattenmätarfoto i workspace och skapa sedan en API-nyckel när du är redo att integrera.

Registrera och ladda upp fotoSkapa API-nyckel

Översikt

  • Använd webbsidans backend för alla externa integrationer.
  • Ring inte waterMeterAi direkt från tredjepartsprogram.
  • Den öppna API delar samma användare, kvot, cache, uppgifter och revisionsregler som webbportalen.
  • Backend kan rikta in sig på olika nedströms AI-företag genom implementeringskonfiguration.
  • Uppgiftssvar inkluderar nu ett generiskt result_summary-objekt så att olika företag kan visa olika resultattyper.

Autentisering

  • Logga in på webbplatsen och skapa en API-nyckel på sidan API Nycklar.
  • Den fullständiga API-nyckeln visas bara en gång när den skapas.
  • Skicka nyckeln i auktoriseringshuvudet vid varje begäran.
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

Uppladdningsregler

  • Maximal filstorlek: 20MB per bild.
  • Format som stöds: JPEG, PNG, WEBP.
  • Backend validerar det faktiska filinnehållet, inte bara filtillägget.

Uppladdningsstorlek

  • Batchuppladdningar accepterar upp till 8 bilder som standard, med en gräns på 20 MB per bild och en gräns på 20 MB totalt filinnehåll.
  • En fil eller batch som överskrider sin gräns returnerar 413 före bildvalidering eller uppgiftsskapande; ingen partiell batch skapas.
  • Backend upprätthåller det faktiska antalet mottagna byte även när Content-Length saknas eller chunköverföring används.

Uppgiftsstater

  • queued: accepteras och väntar på AI bearbetning.
  • running: bearbetas för närvarande, eller har redan lämnats till avsändaren och frågar fortfarande efter det slutliga resultatet.
  • batch_waiting_ai: varje artikel i partiet väntar på att tjänsten AI ska komma tillbaka online.
  • batch_running: batchen har redan lämnats till avsändaren och bearbetas fortfarande.
  • done: avslutades framgångsrikt.
  • failed: bearbetar failed.
  • waiting_ai: queued tills tjänsten AI kommer online igen, sedan återupptas den automatiskt.

Resultatkällor

  • fresh: genererad av en ny AI körning.
  • cached_exact: matchade den aktuella AI versionscachen.
  • cached_stale: AI offline, senaste cachade resultat returnerade.
  • pending: inget slutresultat ännu.
  • failed: uppgiften failed.
  • När en uppgift inte är done ännu, kontrollera error_message för det senaste försöket eller väntan.

Kvot och debitering

  • Använd `GET /api/open/quota` innan du skickar stora arbetslaster om din integration behöver undvika kvotfel.
  • Endast `fresh` AI-körningar förbrukar kvot.
  • `cached_exact`, `cached_stale`, `pending` och `failed` resultat förbrukar inte kvot.
  • Gratis konton använder den dagliga kvoten först. Betalda konton använder aktiva periodiska kvotpaket och därefter temporär eller fast kvot enligt backendpolicyn.
  • När kvoten är slut returnerar uppgiftsinlämning `429` och ett felmeddelande i stället för att skapa en ny uppgift.

Cache och resultatets färskhet

  • Backend cachar lyckade resultat efter bildhash och AI-version, inklusive namespace för downstream-verksamheten.
  • `cached_exact` betyder att samma bild redan har ett lyckat resultat för aktuell AI-version, så ingen ny AI-körning behövdes.
  • `cached_stale` betyder att AI-tjänsten är offline och backend returnerade det senaste tillgängliga historiska resultatet.
  • När `is_latest_ai_version` är false ska resultatet lagras som användbar men granskningsbar historisk data.
  • Anta inte att varje `done` uppgift förbrukade kvot; kontrollera `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 aktuell kvot och återstående användning.

Exempel på begäran
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exempel 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-statusen för uppgiftsinlämning och cachelagrat resultat.

Exempel på begäran
curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exempel 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

Ladda upp en bild och skapa en enda uppgift.

Exempel på begäran
curl -X POST "https://watermeterai.com/api/open/tasks" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \
  -F "file=@D:\data\meter_001.jpg"
Exempel 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 status för en uppgift och slutläsning.

Exempel på begäran
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exempel 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 de senaste uppgifterna som ägs av den nuvarande API-nyckelanvändaren.

Exempel på begäran
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exempel 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

Ladda upp flera bilder i en begäran.

Exempel på begäran
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"
Exempel 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 batchförlopp och uppgiftstillstånd per fil.

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

Rekommenderat flöde

  • Kontrollera `GET /api/open/ai-status` innan du skickar stora arbetsbelastningar.
  • Lagra `task_id` eller `batch_id` i ditt eget system direkt efter inlämning.
  • Behandla `queued`, `running`, `waiting_ai`, `batch_waiting_ai` och `batch_running` som icke-slutliga tillstånd och fortsätt att rösta.
  • Använd batchförfrågningar när nätverksvägen till backend har hög latens och den distribuerade verksamheten stöder batchläge.
  • Batchförfrågningar flyter för närvarande genom `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` betyder att alla föremål fortfarande väntar på tjänsten AI, inte aktivt running än.
  • När den distribuerade verksamheten är `CAD`, använd `POST /api/open/tasks` för nu och betrakta batchuppladdning som otillgänglig.

Felanteckningar

  • 400: ogiltig begäran, eller så stöder den distribuerade verksamheten inte batchuppladdning.
  • 401: saknad, ogiltig, utgången eller inaktiverad API-nyckel.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: uppgift eller batch hittades inte, eller ägs inte av den aktuella användaren.
  • 413: filen är för stor.
  • 415: bildtyp som inte stöds eller ogiltigt bildinnehåll.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 batchuppladdning är inte tillgänglig
{
  "detail": "batch upload is not supported for business: cax"
}
401 saknas eller är ogiltig API-nyckel
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413-filen är för stor
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 kvoten är slut
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Redo att testa arbetsflödet?

Använd web workspace för det första fotot och gå sedan vidare till API-nycklar när resultatformatet passar.

Registrera och ladda upp fotoSkapa API-nyckel