WaterMeter AI
DilAzərbaycanca
Digər dillər

Su sayğacı OCR API-si

Su sayğacı OCR API-si. Bu səhifə saytın üçüncü tərəf inteqrasiyaları üçün ictimai HTTP API saytın arxa tərəfi tərəfindən ifşa olunmasını sənədləşdirir.

Həqiqi yükləmə ilə başlayın

Əvvəlcə qeydiyyatdan keçin, iş sahəsində öz su sayğacının şəklini yükləyin və inteqrasiya etməyə hazır olduqda API açarı yaradın.

Qeydiyyatdan keçin və foto yükləyinBir API Açarı yarat

Ümumi baxış

  • Bütün xarici inteqrasiyalar üçün vebsaytın backendindən istifadə edin.
  • Üçüncü tərəf proqramlarından birbaşa waterMeterAi zəng etməyin.
  • Açıq API veb portalla eyni istifadəçi, kvota, keş, tapşırıqlar və audit qaydalarını paylaşır.
  • Backend yerləşdirmə konfiqurasiyası ilə müxtəlif aşağı axın AI bizneslərini hədəfləyə bilər.
  • Tapşırıq cavabları indi ümumi result_summary obyektini ehtiva edir ki, müxtəlif bizneslər fərqli nəticə növlərini göstərə bilsinlər.

Autentifikasiya

  • Vebsaytda daxil olun və API Keys səhifəsində API açarı yaradın.
  • Tam API açarı yaradıldıqda yalnız bir dəfə göstərilir.
  • Hər sorğuya açarı Avtorizasiya başlığında göndərin.
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

Yükləmə Qaydaları

  • Maksimum fayl ölçüsü: hər şəkil üçün 20MB.
  • Dəstəklənən formatlar: JPEG, PNG, WEBP.
  • Backend yalnız fayl uzantısı deyil, faktiki fayl məzmununu təsdiqləyir.

Yükləmə Ölçüsünün Tətbiqi

  • Toplu yükləmələr standart olaraq 8 şəkil qəbul edir, hər şəkil üçün 20MB, ümumi fayl məzmunu limiti isə 20MB.
  • Limitini aşan fayl və ya partiya şəkil yoxlanmasından və ya tapşırıq yaradılmasından əvvəl 413 qaytarır; Qismən partiya yaradılmır.
  • Backend hətta Content-Length olmadıqda və ya chunked transfer istifadə olunduqda belə, faktiki qəbul edilmiş bayt sayını təmin edir.

Tapşırıq Dövlətləri

  • Növbəyə qoyuldu: qəbul edildi və AI emalını gözləyirəm.
  • İşləmək: Hazırda emal olunur, ya da artıq dispetçerə təqdim olunur və yekun nəticə üçün hələ də sorğu aparılır.
  • batch_waiting_ai: partiyadakı bütün məhsullar AI xidmətinin yenidən işə düşməsini gözləyir.
  • batch_running: partiya artıq dispetçerə təhvil verilib və hələ də işlənir.
  • Bitdi: Uğurla bitirdim.
  • Uğursuz oldu: emal uğursuz oldu.
  • waiting_ai: AI xidməti yenidən işə düşənə qədər növbəyə dururam, sonra avtomatik olaraq davam edir.

Nəticə Mənbələri

  • Fresh: Yeni AI buraxılışı ilə yaradılıb.
  • cached_exact: cari AI versiya keşi ilə uyğunlaşdı.
  • cached_stale: AI offline, ən son keşlənmiş nəticə qaytarıldı.
  • Gözlənilən: Hələ yekun nəticə yoxdur.
  • uğursuz oldu: tapşırıq uğursuz oldu.
  • Əgər bir tapşırıq hələ bitməyibsə, error_message son təkrar cəhd və ya gözləmə səbəbini yoxlayın.

Kvota və Hesablaşma

  • Əgər inteqrasiyanız kvota uğursuzluqlarının qarşısını almaq üçün böyük iş yükü göndərməzdən əvvəl `GET /api/open/quota` istifadə edin.
  • Yalnız `fresh` AI oyun kvota sərf edir.
  • `cached_exact`, `cached_stale`, `pending`və `failed` nəticələri kvota istifadə etmir.
  • Pulsuz hesablar əvvəlcə gündəlik kvotadan istifadə edin. Ödənişli hesablar aktiv periodik kvota paketlərindən istifadə edir, sonra arxa plan siyasətinə görə müvəqqəti və ya sabit kvotadan istifadə olunur.
  • Kvota bitdikdə, tapşırıq təqdimatı `429` qaytarır və yeni tapşırıq yaratmaq əvəzinə səhv mesajı əlavə edir.

Keş və Nəticə Təzəliyi

  • Backend uğurlu nəticələri şəkil hash və AI versiyası ilə, o cümlədən aşağı axın biznes ad məkanına görə keşləyir.
  • `cached_exact` o deməkdir ki, eyni görüntü cari AI versiyası üçün artıq uğurlu nəticə alıb, ona görə də yeni AI işləməsinə ehtiyac olmayıb.
  • `cached_stale` o deməkdir ki, AI xidməti oflayndır və arxa plan ən son mövcud tarixi nəticəni qaytarır.
  • Əgər `is_latest_ai_version` səhv olduqda, nəticəni istifadə oluna bilən, lakin nəzərdən keçirilə bilən tarixi məlumat kimi saxlayın.
  • Hər `done` tapşırığın istifadə olunan kvotasını qəbul etməyin; yoxlayın `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

Cari kvota və qalan istifadəni oxuyun.

Nümunə Sorğusu
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Cavab nümunəsi
{
  "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

Tapşırıq təqdimatı və keşlənmiş nəticə ehtiyatı üçün ictimai xidmət statusunu oxuyun.

Nümunə Sorğusu
curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Cavab nümunəsi
{
  "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 şəkil yükləyin və tək bir tapşırıq yaradın.

Nümunə Sorğusu
curl -X POST "https://watermeterai.com/api/open/tasks" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \
  -F "file=@D:\data\meter_001.jpg"
Cavab nümunəsi
{
  "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 tapşırıq statusunu və son oxunuşu oxuyun.

Nümunə Sorğusu
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Cavab nümunəsi
{
  "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

Cari API açar istifadəçisinə məxsus son tapşırıqları oxuyun.

Nümunə Sorğusu
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Cavab nümunəsi
{
  "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

Bir sifarişdə bir neçə şəkil yükləyin.

Nümunə Sorğusu
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"
Cavab nümunəsi
{
  "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 irəliləyiş və fayl üzrə tapşırıq vəziyyətlərini oxuyun.

Nümunə Sorğusu
curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Cavab nümunəsi
{
  "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": ""
    }
  ]
}

Tövsiyə olunan axın

  • Böyük iş yükü göndərməzdən əvvəl `GET /api/open/ai-status` yoxlayın.
  • `task_id` və ya `batch_id` təqdim etdikdən dərhal sonra öz sisteminizdə saxlayın.
  • `queued`, `running`, `waiting_ai`, `batch_waiting_ai`və `batch_running` qeyri-son ştatlar kimi qəbul edin və sorğu aparmağa davam edin.
  • Şəbəkə arxa tərəfə gedən yol yüksək gecikmə olduqda və yerləşdirilmiş biznes batch rejimini dəstəklədikdə toplu sorğulardan istifadə edin.
  • Toplu sorğular hazırda `webBackend -> dispatchCenter -> waterMeterAi`vasitəsilə axır.
  • `batch_waiting_ai` o deməkdir ki, hər bir əşya hələ də AI xidmətini gözləyir, hələ aktiv işləmir.
  • Yerləşdirilmiş biznes `CAD`olduqda, hələlik `POST /api/open/tasks` istifadə edin və toplu yükləməni əlçatmaz hesab edin.

Səhv Qeydləri

  • 400: etibarsız sorğu, ya da yerləşdirilmiş biznes toplu yükləməni dəstəkləmir.
  • 401: itkin, etibarsız, müddəti bitmiş və ya deaktiv API açar.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: tapşırıq və ya toplu tapılmadı, ya da cari istifadəçiyə məxsus deyil.
  • 413: fayl çox böyükdür.
  • 415: dəstəklənməyən şəkil növü və ya etibarsız şəkil məzmunu.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 toplu yükləmə mövcud deyil
{
  "detail": "batch upload is not supported for business: cax"
}
401 açarı itkin və ya etibarsız API
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 fayl çox böyük
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 kvota bitdi
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

İş axınını sınamağa hazırsınız?

İlk şəkil üçün web workspace-dən istifadə edin, sonra nəticə formatı sisteminizə uyğunlaşdıqda API düymələrə keçin.

Qeydiyyatdan keçin və foto yükləyinBir API Açarı yarat