su sayacı OCR API’si

su sayacı OCR API’si. Bu sayfa, üçüncü taraf entegrasyonları için web sitesi arka ucu tarafından açığa çıkarılan genel HTTP API belgelemektedir.

Gerçek bir yükleme ile başlayın

Önce kaydolun, workspace içinde kendi su sayacı fotoğrafınızı yükleyin, entegrasyona hazır olduğunuzda API key oluşturun.

Kaydol ve fotoğraf yükle API key oluştur

Uç noktaları arayın

Genel Bakış

Tüm harici entegrasyonlar için web sitesinin arka ucunu kullanın.
waterMeterAi'yi doğrudan üçüncü taraf programlardan aramayın.
Açık API, web portalıyla aynı kullanıcıları, kotayı, önbelleği, görevleri ve denetim kurallarını paylaşır.
Arka uç, dağıtım yapılandırmasına göre farklı alt akış AI işletmelerini hedefleyebilir.
Görev yanıtları artık genel bir result_summary nesnesi içeriyor; böylece farklı işletmeler farklı sonuç türlerini görüntüleyebilir.

Kimlik doğrulama

Web sitesinde oturum açın ve API Anahtarlar sayfasında bir API anahtarı oluşturun.
Tam API anahtarı oluşturulduğunda yalnızca bir kez gösterilir.
Her istekte Yetkilendirme başlığındaki anahtarı gönderin.

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

Kuralları Yükle

Maksimum dosya boyutu: resim başına 20MB.
Desteklenen formatlar: JPEG, PNG, WEBP.
Arka uç yalnızca dosya uzantısını değil, gerçek dosya içeriğini de doğrular.

Yükleme Boyutunun Uygulanması

Toplu yüklemeler, görüntü başına 20 MB ve toplam dosya içeriği sınırı 20 MB olmak üzere varsayılan olarak en fazla 8 görüntüyü kabul eder.
Sınırını aşan bir dosya veya toplu iş, görüntü doğrulamadan veya görev oluşturmadan önce 413 sayısını döndürür; kısmi toplu iş oluşturulmaz.
Arka uç, Content-Length eksik olduğunda veya yığın halinde aktarım kullanıldığında bile alınan gerçek bayt sayısını zorlar.

Görev Durumları

queued: kabul edildi ve AI işlenmesi bekleniyor.
running: şu anda işleniyor veya sevk görevlisine zaten teslim edildi ve nihai sonuç için hâlâ oylama yapılıyor.
batch_waiting_ai: gruptaki her öğe AI hizmetinin tekrar çevrimiçi olmasını bekliyor.
batch_running: toplu iş zaten dağıtıcıya teslim edildi ve hala işleniyor.
done: başarıyla tamamlandı.
failed: failed işleniyor.
waiting_ai: queued, AI hizmeti tekrar çevrimiçi oluncaya kadar, ardından otomatik olarak devam eder.

Sonuç Kaynakları

fresh: yeni bir AI çalıştırması tarafından oluşturuldu.
cached_exact: geçerli AI sürüm önbelleğiyle eşleşti.
cached_stale: AI çevrimdışı, önbelleğe alınan en son sonuç döndürüldü.
pending: henüz nihai sonuç yok.
failed: görev failed.
Bir görev henüz done değilse, en son yeniden deneme veya bekleme nedeni için error_message öğesini kontrol edin.

Kota ve faturalandırma

Entegrasyonunuz kota hatalarını önlemek zorundaysa büyük iş yükleri göndermeden önce `GET /api/open/quota` kullanın.
Yalnızca `fresh` AI çalıştırmaları kota tüketir.
`cached_exact`, `cached_stale`, `pending` ve `failed` sonuçları kota tüketmez.
Ücretsiz hesaplar önce günlük kotayı kullanır. Ücretli hesaplar backend politikasına göre aktif dönemsel kota paketlerini, ardından geçici veya sabit kotayı kullanır.
Kota tükendiğinde görev gönderimi yeni görev oluşturmak yerine `429` ve bir hata mesajı döndürür.

Önbellek ve sonuç güncelliği

Backend başarılı sonuçları görüntü hash’i ve AI sürümüne göre, downstream iş namespace’i dahil olacak şekilde önbelleğe alır.
`cached_exact`, aynı görüntünün mevcut AI sürümü için zaten başarılı bir sonucu olduğu ve yeni AI çalıştırmasına gerek olmadığı anlamına gelir.
`cached_stale`, AI hizmetinin çevrimdışı olduğu ve backend’in mevcut en son geçmiş sonucu döndürdüğü anlamına gelir.
`is_latest_ai_version` false olduğunda sonucu kullanılabilir ancak incelenebilir geçmiş veri olarak saklayın.
Her `done` görevin kota tükettiğini varsaymayın; `result_source` alanını kontrol edin.

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`

Mevcut kotayı ve kalan kullanımı okuyun.

Örnek Talep

curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

Yanıt Örneği

{
  "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`

Görev gönderimi ve önbelleğe alınmış sonuç geri dönüşü için kamu hizmeti durumunu okuyun.

Örnek Talep

curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

Yanıt Örneği

{
  "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`

Bir görsel yükleyin ve tek bir görev oluşturun.

Örnek Talep

curl -X POST "https://watermeterai.com/api/open/tasks" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \
  -F "file=@D:\data\meter_001.jpg"

Yanıt Örneği

{
  "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}`

Bir görev durumunu ve son okumayı okuyun.

Örnek Talep

curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

Yanıt Örneği

{
  "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`

Geçerli API anahtar kullanıcısının sahip olduğu son görevleri okuyun.

Örnek Talep

curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

Yanıt Örneği

{
  "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`

Tek bir istekte birden fazla resim yükleyin.

Örnek Talep

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"

Yanıt Örneği

{
  "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}`

Toplu ilerlemeyi ve dosya başına görev durumlarını okuyun.

Örnek Talep

curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

Yanıt Örneği

{
  "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": ""
    }
  ]
}

Önerilen Akış

Büyük iş yüklerini göndermeden önce `GET /api/open/ai-status` öğesini kontrol edin.
`task_id` veya `batch_id`'yi gönderimden hemen sonra kendi sisteminizde saklayın.
`queued`, `running`, `waiting_ai`, `batch_waiting_ai` ve `batch_running`'e nihai olmayan durumlar olarak davranın ve yoklamaya devam edin.
Arka uca giden ağ yolunun yüksek gecikme süresine sahip olduğu ve dağıtılan işletmenin toplu modunu desteklediği durumlarda toplu istekleri kullanın.
Toplu istekler şu anda `webBackend -> dispatchCenter -> waterMeterAi` üzerinden akıyor.
`batch_waiting_ai` her öğenin hala AI hizmetini beklediği anlamına gelir, henüz aktif olarak running değil.
Dağıtılan işletme `CAD` olduğunda, şimdilik `POST /api/open/tasks` kullanın ve toplu yüklemeyi kullanılamaz olarak değerlendirin.

Hata Notları

400: geçersiz istek veya konuşlandırılan işletme toplu yüklemeyi desteklemiyor.
401: eksik, geçersiz, süresi dolmuş veya devre dışı API anahtarı.
403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
404: görev veya toplu iş bulunamadı veya geçerli kullanıcıya ait değil.
413: dosya çok büyük.
415: desteklenmeyen resim türü veya geçersiz resim içeriği.
429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.

400 toplu yükleme kullanılamıyor

{
  "detail": "batch upload is not supported for business: cax"
}

401 eksik veya geçersiz API anahtarı

{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}

413 dosyası çok büyük

{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}

429 kontenjan doldu

{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Workflow test etmeye hazır mısınız?

İlk fotoğraf için web workspace kullanın, sonuç formatı sisteminize uyduğunda API keys aşamasına geçin.

Kaydol ve fotoğraf yükle API key oluştur

su sayacı OCR API’si

Gerçek bir yükleme ile başlayın

Genel Bakış

Kimlik doğrulama

API Key Permissions and Limits

Kuralları Yükle

Yükleme Boyutunun Uygulanması

Görev Durumları

Sonuç Kaynakları

Kota ve faturalandırma

Önbellek ve sonuç güncelliği

Task completion webhooks

GET/api/open/quota

GET/api/open/ai-status

POST/api/open/tasks

GET/api/open/tasks/{task_id}

GET/api/open/tasks

POST/api/open/batches

GET/api/open/batches/{batch_id}

Önerilen Akış

Hata Notları

Workflow test etmeye hazır mısınız?

GET`/api/open/quota`

GET`/api/open/ai-status`

POST`/api/open/tasks`

GET`/api/open/tasks/{task_id}`

GET`/api/open/tasks`

POST`/api/open/batches`

GET`/api/open/batches/{batch_id}`