WaterMeter AI
ZimanKurdî
Zimanên din

API-ya OCR-ê ya metreya avê

API-ya OCR-ê ya metreya avê. Ev rûpel HTTP API ji hêla pişta malperê ve ji bo entegrasyonên partiya sêyemîn ve hatî eşkere kirin belge dike.

Bi barkirina rastîn dest pê bikin

Pêşî qeyd bikin, wêneyê xweya mêtroya avê li cîhê xebatê bar bikin, û dûv re gava ku hûn amade ne ku tevbigerin mifteyek API biafirînin.

Xwe qeyd bikin û wêneyek bar bikinMifteyek API biafirîne

Nêrîna giştî

  • Piştgiriya malperê ji bo hemî entegrasyonên derveyî bikar bînin.
  • Ji bernameyên aliyê sêyem waterMeterAi rasterast bikar neynin.
  • API vekirî heman bikarhêner, kota, cache, peywir û qaîdeyên kontrolê wekî portala malperê parve dike.
  • Piştgiriya paşîn dikare ji hêla veavakirina sazkirinê ve karsaziyên cûda yên jêrîn ên AI bike hedef.
  • Bersivên peywirê naha hêmanek result_summary ya gelemperî vedihewîne ji ber vê yekê karsaziyên cihêreng dikarin cûreyên encamên cûda nîşan bidin.

Nasname

  • Di malperê de têkevin û li ser rûpela API Keys mifteyek API biafirînin.
  • Mifteya API ya tam tenê carekê, dema ku tê afirandin, tê nîşandan.
  • Di her daxwazê de mifteyê di sernavê Authorization de bişînin.
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

Rêbazên barkirinê

  • Mezinahiya pelê ya herî zêde: her wêneyê 20 MB.
  • Formên destekirî: JPEG, PNG, WEBP.
  • Piştgiriyê naveroka pelê ya rastîn rast dike, ne tenê dirêjkirina pelê.

Pêkanîna Mezinahiya Barkirin

  • Barkirinên komê bi xweber heta 8 wêneyan dipejirînin, bi 20 MB sînorê her wêneyê û 20 MB sînorê naveroka pelê ya tevahî.
  • Pelek an komek ku ji sînorê xwe derbas dibe 413 vedigerîne berî pejirandina wêneyê an çêkirina peywirê; ti beşê qismî nayê afirandin.
  • Paşend jimara rastîn a baytên wergirtî sînordar dike, heta dema ku Content-Length tune be an veguheztina perçekirî were bikaranîn.

Rewşên peywirê

  • queued: hate pejirandin û li benda pêvajoya AI ye.
  • running: niha tê pêvajokirin, an ji navenda şandinê re hatiye radestkirin û ji bo encama dawî rewş hîn demdemî tê kontrolkirin.
  • batch_waiting_ai: her tişt di komê de li bendê ye ku karûbarê AI vegere serhêl.
  • batch_running: koma peywiran ji navenda şandinê re hatiye radestkirin û hîn tê pêvajokirin.
  • done: bi serkeftî qediya.
  • failed: pêvajokirin bi ser neket.
  • waiting_ai: heya ku karûbarê AI vegere serhêl, di rêzê de ye, dûv re ew bixweber dest pê dike.

Çavkaniyên Encamê

  • fresh: bi xebitandina nû ya AI hate afirandin.
  • cached_exact: bi cache guhertoya niha ya AI re hevaheng kir.
  • cached_stale: AI negirêdayî, encama cache ya herî dawî vegeriya.
  • pending: hê encama dawî tune.
  • failed: peywir bi ser neket.
  • Dema ku peywir hîn neqediya, ji bo sedema herî dawî ya dubareceribandinê an bendê error_message kontrol bikin.

Kota û hesablaşma

  • Heke entegrasyona we divê ji têkçûna kêmbûna kotayê dûr bimîne, berî radestkirina gelek peywiran `GET /api/open/quota` bikar bînin.
  • Tenê naskirinên nû yên AI yên `fresh` kotayê dixwin.
  • `cached_exact`, `cached_stale`, `pending`, û `failed` kotayê naxwin.
  • Hesabên belaş pêşî kotaya rojane bikar tînin. Hesabên drav pakêtên kotaya periyodîk çalak bikar tînin, dûv re li gorî polîtîkaya paşîn kotaya demkî an sabît bikar tînin.
  • Dema kota biqede, radestkirina peywirê `429` vedigerîne û li şûna afirandina peywirek nû peyamek xeletiyê vedigire.

Cache û Tezebûna Encamê

  • Paşend encamên serketî li gorî hash-a wêneyê û guhertoya AI cache dike û namespace-a karûbarê jêrîn jî tê de ye.
  • `cached_exact` tê vê wateyê ku heman wêneyê jixwe ji bo guhertoya AI ya heyî encamek serketî heye, ji ber vê yekê AI nû ne hewce bû.
  • `cached_stale` tê vê wateyê ku karûbarê AI negirêdayî ye û paşîn encama herî dawî ya dîrokî ya berdest vegerand.
  • Dema ku `is_latest_ai_version` false be, encamê wekî daneyên dîrokî yên bikêr lê pêdivî bi vekolînê hilînin.
  • Nehesibînin ku her peywira `done` kotayê xwariye; `result_source` kontrol bikin.

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

Kotaya heyî û karanîna mayî bixwînin.

Daxwaza Mînak
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Mînak Bersiv
{
  "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

Ji bo radestkirina peywirê û paşvegera encamên cached rewşa karûbarê giştî bixwînin.

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

Wêneyek bar bikin û peywirek yekane biafirînin.

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

Rewşa yek peywirê û xwendina dawî bixwînin.

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

Peywirên dawî yên bikarhênerê mifteya API ya niha bixwînin.

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

Di daxwazekê de gelek wêneyan barkirin.

Daxwaza Mînak
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"
Mînak Bersiv
{
  "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}

Pêşkeftina komê û rewşên peywirê yên pelê bixwînin.

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

Herikîna Pêşniyarkirî

  • Berî ku karên mezin bişînin `GET /api/open/ai-status` kontrol bikin.
  • `task_id` an `batch_id` tavilê piştî radestkirinê di pergala xwe de hilînin.
  • `queued`, `running`, `waiting_ai`, `batch_waiting_ai` û `batch_running` wekî rewşên ne-dawî binirxînin û kontrolkirina demdemî ya rewşê bidomînin.
  • Dema ku riya torê ya berbi paşîn derengiyek zêde heye û karsaziya hatî veqetandin moda hevîrê piştgirî dike, daxwazên hevîrê bikar bînin.
  • Daxwazên Batchê niha di nav `webBackend -> dispatchCenter -> waterMeterAi` re derbas dibin.
  • `batch_waiting_ai` tê vê wateyê ku her tişt hîn jî li benda karûbarê AI ye, hîn bi rengek çalak nayê xebitandin.
  • Dema ku karsaziya `CAD` ye, `POST /api/open/tasks` ji bo naha bikar bînin û barkirina komê wekî ne berdest binirxînin.

Têbînîyên çewtiyê

  • 400: Daxwaza nederbasdar, an jî karsaziya ku hatî belav kirin barkirina hevî piştgirî nake.
  • 401: Mifteya API wenda, nederbasdar, derbasbûyî, an neçalak.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: peywir an komek nehat dîtin, an ne xwediyê bikarhênerê heyî ye.
  • 413: pel pir mezin e.
  • 415: cureyê wêneyê nepiştgirî an naveroka wêneya nederbasdar.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 barkirina hevî ne berdest e
{
  "detail": "batch upload is not supported for business: cax"
}
401 mifteya API tune an nederbasdar e
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 pir mezin e
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 kota qediya
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Amade ne ku hûn herikîna xebatê biceribînin?

Ji bo wêneya yekem cihê xebata webê bikar bînin, paşê dema ku formata encamê li pergala we were, biçin mifteyên API.

Xwe qeyd bikin û wêneyek bar bikinMifteyek API biafirîne