WaterMeter AI
AsụsụIgbo
Asụsụ ndị ọzọ

API OCR maka mita mmiri

API OCR maka mita mmiri. Peeji a na-akọwa HTTP API ọha nke backend webụsaịtị na-enye maka njikọta ndị ọzọ.

Malite na ezigbo ebugote

Debanye aha mbụ, bulite foto mita mmiri gị na ebe ọrụ, wee mepụta igodo API mgbe ị dị njikere ijikọta.

Debanye aha ma bulite fotoMepụta igodo API

Nchịkọta

  • Jiri backend webụsaịtị maka njikọta niile dị na mpụga.
  • Ejila waterMeterAi kpọmkwem site na mmemme ndị ọzọ.
  • Oghere API na-ekerịta otu ndị ọrụ, ọnụọgụ, cache, ọrụ, na iwu nyocha dị ka ọnụ ụzọ weebụ.
  • Backend nwere ike ịhọrọ ọrụ AI dị iche iche dị n'okpuru site na nhazi ntinye.
  • Nzaghachi ọrụ ugbu a na-agụnye ihe result_summary ka ọrụ dị iche iche nwee ike igosipụta ụdị nsonaazụ dị iche iche.

Nkwenye

  • Banye na ebe nrụọrụ weebụ ma mepụta igodo API na peeji nke API Keys.
  • A na-egosipụta igodo API zuru ezu naanị otu ugboro mgbe e kere ya.
  • Tinye igodo ahụ n'ime nkụnye eji isi mee Authorization na arịrịọ ọ bụla.
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

Iwu Ebugote

  • Ọnụ ọgụgụ kachasị elu: 20MB kwa onyinyo.
  • Tsarin ndị akwadoro: JPEG, PNG, WEBP.
  • Backend na-akwado ọdịnaya faịlụ n'ezie, ọ bụghị naanị ndọtị faịlụ.

Mmanye Oke Ebugote

  • Ebugote ogbe na-anabata ihe ruru onyonyo 8 na ndabara, yana oke 20MB kwa onyonyo na oke ọdịnaya faịlụ 20MB n'ozuzu.
  • Faịlụ ma ọ bụ ogbe nke gafere oke ya na-alaghachi 413 tupu nkwenye onyonyo ma ọ bụ okike ọrụ; ọ dịghị akụkụ ogbe e kere.
  • Backend na-amanye ọnụọgụ byte natara n'ezie ọbụlagodi mgbe Content-Length na-efu ma ọ bụ a na-eji nnyefe chunked.

Ọnọdụ Ọrụ

  • queued: anabatala ya ma ọ na-eche nhazi AI.
  • running: a na-ahazi ya ugbu a, ma ọ bụ e nyefelarị ya n'aka dispatcher ma a ka na-ajụ ọnọdụ ya maka nsonaazụ ikpeazụ.
  • batch_waiting_ai: Onye ọ bụla n'ime ogbe na-eche ka ọrụ AI laghachi na ntanetị.
  • batch_running: A na-enyefe ogbe ahụ n'aka onye na-ezipụ ma ka na-edozi.
  • done: emechara ya nke ọma.
  • failed: nhazi dara ada.
  • waiting_ai: kwụ n'ahịrị ruo mgbe ọrụ AI laghachiri na ntanetị, mgbe ahụ, ọ na-amaliteghachi na-akpaghị aka.

Isi mmalite nsonaazụ

  • fresh: nhazi AI ọhụrụ mepụtara ya.
  • cached_exact: Dakọtara na nsụgharị AI dị ugbu a.
  • cached_stale: AI na-anọghị n'ịntanetị, nsonaazụ cached kachasị ọhụrụ laghachiri.
  • pending: enweghị nsonaazụ ikpeazụ ugbu a.
  • failed: ọrụ ahụ dara ada.
  • Mgbe emebeghị ọrụ, lelee error_message maka nnwale ọhụrụ ma ọ bụ ihe kpatara ichere.

Quota na ịgba ụgwọ

  • Jiri `GET /api/open/quota` tupu ị nyefee nnukwu ọrụ ma ọ bụrụ na njikọta gị chọrọ izere ọdịda ọnụọgụ.
  • Naanị nhazi AI nke isi ya bụ `fresh` na-eri quota.
  • `cached_exact`, `cached_stale`, `pending`, na nsonaazụ `failed` anaghị eri ọnụọgụ.
  • Akaụntụ n'efu na-ebu ụzọ jiri ọnụọgụ kwa ụbọchị. Akaụntụ akwụ ụgwọ na-eji ngwugwu ọnụọgụ oge nke ka dị irè, mgbe ahụ nke nwa oge ma ọ bụ nke edoziri dịka iwu backend.
  • Mgbe oke agwụla, ntinye ọrụ na-alaghachi `429` ma na-agụnye ozi njehie kama ịmepụta ọrụ ọhụrụ.

Cache na Sabuntar Nsonaazụ

  • Backend na-echekwa nsonaazụ gara nke ọma na cache site na hash onyonyo na ụdị AI, gụnyere namespace nke ọrụ dị n'okpuru.
  • `cached_exact` pụtara na otu onyonyo ahụ enweelarị nsonaazụ gara nke ọma maka ụdị AI ugbu a, ya mere nhazi AI ọhụrụ adịghị mkpa.
  • `cached_stale` pụtara na ọrụ AI na-anọghị n'ịntanetị na backend weghachitere nsonaazụ akụkọ ihe mere eme kachasị ọhụrụ.
  • Mgbe `is_latest_ai_version` bụ false, chekwaa nsonaazụ dịka data akụkọ ihe mere eme a pụrụ iji ma kwesịkwa ịtụle.
  • Echela na ọrụ ọ bụla `done` na-eri quota; Lelee `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

Gụọ ọnụọgụ ugbu a na ojiji fọdụrụnụ.

Arịrịọ Ihe Nlereanya
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Ihe Nlereanya Nzaghachi
{
  "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ụọ ọnọdụ ọrụ ọha maka ntinye ọrụ na ịlaghachi na nsonaazụ cache.

Arịrịọ Ihe Nlereanya
curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Ihe Nlereanya Nzaghachi
{
  "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

Tinye otu ihe oyiyi ma mepụta otu ọrụ.

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

Na-agụ otu ọrụ na ọgụgụ ikpeazụ.

Arịrịọ Ihe Nlereanya
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Ihe Nlereanya Nzaghachi
{
  "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

Gụọ ọrụ ndị na-adịbeghị anya nke onye ọrụ igodo API ugbu a nwere.

Arịrịọ Ihe Nlereanya
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Ihe Nlereanya Nzaghachi
{
  "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

Bulite ọtụtụ ihe oyiyi n'otu arịrịọ.

Arịrịọ Ihe Nlereanya
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"
Ihe Nlereanya Nzaghachi
{
  "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}

Gụọ ọganihu ogbe na ọrụ ọrụ kwa faịlụ.

Arịrịọ Ihe Nlereanya
curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Ihe Nlereanya Nzaghachi
{
  "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": ""
    }
  ]
}

A na-atụ aro Flow

  • Lelee `GET /api/open/ai-status` tupu izipu nnukwu ọrụ.
  • Chekwaa `task_id` ma ọ bụ `batch_id` n'ime sistemụ gị ozugbo ị nyefere.
  • Were `queued`, `running`, `waiting_ai`, `batch_waiting_ai` na `batch_running` dịka ọnọdụ na-abụghị nke ikpeazụ ma nọgide na-ajụ ọnọdụ oge niile.
  • Jiri arịrịọ ogbe mgbe ụzọ netwọk gaa backend nwere nnukwu latency na ọrụ etinyere na-akwado ọnọdụ ogbe.
  • Arịrịọ ogbe ugbu a na-agafe `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` pụtara na ihe ọ bụla ka na-eche ọrụ AI ahụ; nhazi amalitebeghị.
  • Mgbe ọrụ etinyere bụ `CAD`, jiri `POST /api/open/tasks` ugbu a ma were ebugote ogbe dịka ihe na-adịghị adị.

Ihe edeturu njehie

  • 400: arịrịọ na-ezighi ezi, ma ọ bụ ọrụ etinyere anaghị akwado ebugote ogbe.
  • 401: igodo API na-efu, ezighị ezi, agwụla ma ọ bụ gbanyụrụ.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: ọrụ ma ọ bụ ogbe achọtaghị, ma ọ bụ na ọ bụghị nke onye ọrụ ugbu a.
  • 413: faịlụ buru ibu.
  • 415: ụdị onyonyo a na-akwadoghị ma ọ bụ ọdịnaya onyonyo na-ezighị ezi.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 ebugote ogbe adịghị adị
{
  "detail": "batch upload is not supported for business: cax"
}
401 igodo API na-efu ma ọ bụ ezighị ezi
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 faịlụ buru oke ibu
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 quota agwụla
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Njikere ịnwale ọrụ ahụ?

Jiri ebe nrụọrụ weebụ maka foto mbụ, wee gaa na igodo API ozugbo usoro nsonaazụ dabara na sistemụ gị.

Debanye aha ma bulite fotoMepụta igodo API