WaterMeter AI
SpracheDeutsch
Andere Sprachen

Wasserzähler-OCR-API

Wasserzähler-OCR-API. Diese Seite dokumentiert die öffentliche HTTP-API, die das Website-Backend für Drittanbieter-Integrationen bereitstellt.

Mit einem echten Upload starten

Registrieren Sie sich zuerst, laden Sie Ihr eigenes Wasserzählerfoto im Workspace hoch und erstellen Sie danach einen API-Schlüssel für die Integration.

Registrieren und Foto hochladenAPI-Schluessel erstellen

Überblick

  • Verwende für alle externen Integrationen das Website-Backend.
  • Rufe waterMeterAi nicht direkt aus Drittanbieterprogrammen auf.
  • Die offene API verwendet dieselben Benutzer, Kontingente, Caches, Aufgaben und Audit-Regeln wie das Webportal.
  • Das Backend kann je nach Deployment-Konfiguration unterschiedliche nachgelagerte KI-Geschäfte ansteuern.
  • Aufgabenantworten enthalten jetzt ein generisches result_summary-Objekt, damit verschiedene Geschäfte unterschiedliche Ergebnistypen anzeigen können.

Authentifizierung

  • Melde dich auf der Website an und erstelle auf der Seite API-Schlüssel einen API-Schlüssel.
  • Der vollständige API-Schlüssel wird nur einmal bei der Erstellung angezeigt.
  • Sende den Schlüssel bei jeder Anfrage im Authorization-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

Upload-Regeln

  • Maximale Dateigröße: 20 MB pro Bild.
  • Unterstützte Formate: JPEG, PNG, WEBP.
  • Das Backend prüft den tatsächlichen Dateiinhalt, nicht nur die Dateierweiterung.

Durchsetzung der Upload-Größe

  • Batch-Uploads akzeptieren standardmäßig bis zu 8 Bilder, mit einem Limit von 20 MB pro Bild und einem Limit für den gesamten Dateiinhalt von 20 MB.
  • Eine Datei oder ein Stapel, die bzw. der ihr Limit überschreitet, gibt vor der Image-Validierung oder Aufgabenerstellung 413 zurück; es entsteht keine Teilcharge.
  • Das Backend erzwingt die tatsächliche Anzahl der empfangenen Bytes, auch wenn Content-Length fehlt oder eine Chunked-Übertragung verwendet wird.

Aufgabenstatus

  • queued: angenommen und wartet auf KI-Verarbeitung.
  • running: wird gerade verarbeitet oder wurde bereits an den Dispatcher übergeben und fragt noch das Endergebnis ab.
  • batch_waiting_ai: jedes Element im Stapel wartet darauf, dass der KI-Dienst wieder online kommt.
  • batch_running: der Stapel wurde bereits an den Dispatcher übergeben und wird noch verarbeitet.
  • done: erfolgreich abgeschlossen.
  • failed: Verarbeitung fehlgeschlagen.
  • waiting_ai: in Warteschlange, bis der KI-Dienst wieder online kommt; danach wird automatisch fortgesetzt.

Ergebnisquellen

  • fresh: durch einen neuen KI-Lauf erzeugt.
  • cached_exact: Treffer im Cache der aktuellen KI-Version.
  • cached_stale: KI offline, neuestes zwischengespeichertes Ergebnis zurückgegeben.
  • pending: noch kein Endergebnis.
  • failed: die Aufgabe ist fehlgeschlagen.
  • Wenn eine Aufgabe noch nicht abgeschlossen ist, prüfe error_message für den letzten Wiederholungs- oder Wartegrund.

Kontingent und Abrechnung

  • Verwende `GET /api/open/quota`, bevor du große Arbeitslasten sendest, wenn deine Integration Kontingentfehler vermeiden muss.
  • Nur `fresh` AI-Läufe verbrauchen Kontingent.
  • `cached_exact`, `cached_stale`, `pending` und `failed` verbrauchen kein Kontingent.
  • Kostenlose Konten verwenden zuerst das Tageskontingent. Bezahlte Konten verwenden aktive periodische Kontingentpakete und danach temporäres oder festes Kontingent gemäß Backend-Richtlinie.
  • Wenn das Kontingent erschöpft ist, gibt die Aufgabenerstellung `429` mit einer Fehlermeldung zurück, statt eine neue Aufgabe anzulegen.

Cache und Ergebnisaktualität

  • Das Backend speichert erfolgreiche Ergebnisse nach Bild-Hash und AI-Version, einschließlich Namespace des nachgelagerten Geschäftsbereichs.
  • `cached_exact` bedeutet, dass dasselbe Bild bereits ein erfolgreiches Ergebnis für die aktuelle AI-Version hat; es war kein neuer AI-Lauf nötig.
  • `cached_stale` bedeutet, dass der AI-Dienst offline ist und das Backend das neueste verfügbare historische Ergebnis zurückgegeben hat.
  • Wenn `is_latest_ai_version` false ist, speichere das Ergebnis als verwendbare, aber prüfbare historische Daten.
  • Gehe nicht davon aus, dass jede `done`-Aufgabe Kontingent verbraucht hat; prüfe `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

Lesen Sie das aktuelle Kontingent und die verbleibende Nutzung.

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

Lesen Sie den Status des öffentlichen Dienstes für die Aufgabenübermittlung und den Fallback für zwischengespeicherte Ergebnisse.

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

Laden Sie ein Bild hoch und erstellen Sie eine einzelne Aufgabe.

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

Lesen Sie einen Aufgabenstatus und eine abschließende Lektüre.

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

Aktuelle Aufgaben des aktuellen Hauptbenutzers API lesen.

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

Laden Sie mehrere Bilder in einer Anfrage hoch.

Anfragebeispiel
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"
Antwortbeispiel
{
  "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}

Lesen Sie den Batch-Fortschritt und den Aufgabenstatus pro Datei.

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

Empfohlener Ablauf

  • Prüfe `GET /api/open/ai-status`, bevor du große Arbeitslasten sendest.
  • Speichere `task_id` oder `batch_id` unmittelbar nach dem Senden in deinem eigenen System.
  • Behandle `queued`, `running`, `waiting_ai`, `batch_waiting_ai` und `batch_running` als nicht finale Zustände und frage weiter ab.
  • Verwende Stapelanfragen, wenn der Netzwerkpfad zum Backend hohe Latenz hat und das bereitgestellte Geschäft den Stapelmodus unterstützt.
  • Stapelanfragen laufen derzeit über `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` bedeutet, dass jedes Element noch auf den KI-Dienst wartet und noch nicht aktiv läuft.
  • Wenn das bereitgestellte Geschäft `CAD` ist, verwende vorerst `POST /api/open/tasks` und behandle Stapeluploads als nicht verfügbar.

Fehlerhinweise

  • 400: Ungültige Anfrage oder das bereitgestellte Unternehmen unterstützt keinen Batch-Upload.
  • 401: Fehlender, ungültiger, abgelaufener oder deaktivierter API-Schlüssel.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: Aufgabe oder Stapel nicht gefunden oder nicht im Besitz des aktuellen Benutzers.
  • 413: Datei zu groß.
  • 415: nicht unterstützter Bildtyp oder ungültiger Bildinhalt.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 Batch-Upload nicht verfügbar
{
  "detail": "batch upload is not supported for business: cax"
}
401 fehlender oder ungültiger API-Schlüssel
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413-Datei zu groß
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 Kontingent ausgeschöpft
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Bereit, den Ablauf zu testen?

Nutzen Sie den Web-Workspace fuer das erste Foto und wechseln Sie zu API-Schluesseln, wenn das Ergebnisformat passt.

Registrieren und Foto hochladenAPI-Schluessel erstellen