WaterMeter AI
EdeYorùbá
Awọn ede miiran

API OCR fún mítà omi

API OCR fún mítà omi. Ojú-ìwé yìí ṣàlàyé HTTP API gbangba tí backend ojú opo wẹẹbu n pèsè fún ìṣọ̀kan ẹnikẹta.

Bẹrẹ pẹlu ikojọpọ gidi kan

Forukọsilẹ akọkọ, gbe fọto mita omi ti ara rẹ ni ibi iṣẹ, ati lẹhinna ṣẹda bọtini API nigbati o ba ṣetan lati ṣepọ.

Forukọsilẹ ki o si gbe fọto kanṢẹda Bọtini API

Akopọ

  • Lo backend ojú opo wẹẹbu fún gbogbo ìṣọ̀kan ita.
  • Maṣe pe waterMeterAi taara lati awọn eto ẹnikẹta.
  • Ṣiṣi API pin awọn olumulo kanna, ipin kanna, kaṣe, awọn iṣẹ-ṣiṣe, ati awọn ofin ayewo bi oju opo wẹẹbu naa.
  • Backend lè yan àwọn iṣẹ́ AI ìsàlẹ̀ tó yàtọ̀ gẹ́gẹ́ bí ìṣètò ìfìdímúlẹ̀.
  • Àwọn ìdáhùn iṣẹ́ ní nkan result_summary gbogbogbòò, kí iṣẹ́ ọ̀tọ̀ọ̀tọ̀ lè fi irú èsì tó yàtọ̀ hàn.

Ijẹrisi

  • Wọle si oju opo wẹẹbu naa ki o ṣẹda bọtini API lori oju-iwe API Keys.
  • Bọ́tìnì kíkún API ni a fi hàn lẹ́ẹ̀kan ṣoṣo nígbà tí wọ́n bá ṣẹ̀dá rẹ̀.
  • Fi kọ́kọ́rọ́ ránṣẹ́ nínú akọlé Authorization lórí gbogbo ìbéèrè.
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

Po si awọn ofin

  • Iwọn faili ti o pọju: 20MB fun aworan kan.
  • Ìlànà tí wọ́n ṣe àtìlẹ́yìn: JPEG, PNG, WEBP.
  • Backend ń fìdí àkóónú fáìlì gidi múlẹ̀, kì í ṣe ìfikún orúkọ fáìlì nìkan.

Po si Iwọn Imudaniloju

  • Awọn ikojọpọ ipele gba to awọn aworan 8 nipasẹ aiyipada, pẹlu opin 20MB fun aworan ati opin akoonu faili lapapọ 20MB.
  • Faili tabi ipele ti o kọja opin rẹ pada 413 ṣaaju ifọwọsi aworan tabi ẹda iṣẹ-ṣiṣe; ko si apakan apakan ti a ṣẹda.
  • Backend ń fi iye byte gidi tí ó gba múlẹ̀, kódà nígbà tí Content-Length kò sí tàbí tí a lo ìfiránṣẹ́ chunked.

Àwọn Ipo Iṣẹ́

  • queued: a ti gbà á, ó sì ń dúró de ìṣiṣẹ́ AI.
  • running: a ń ṣiṣẹ́ lé e lórí, tàbí a ti fi ránṣẹ́ sí dispatcher, a sì ń ṣàyẹ̀wò ipo rẹ̀ fún èsì ìkẹyìn.
  • batch_waiting_ai: Gbogbo awọn ohun ti o wa ninu ipele n duro de iṣẹ AI lati pada si intanẹẹti.
  • batch_running: ipele naa ti fi silẹ tẹlẹ si olufiranṣẹ ati pe o tun n ṣiṣẹ.
  • done: ó parí ní àṣeyọrí.
  • failed: ìṣiṣẹ́ kùnà.
  • waiting_ai: duro titi iṣẹ AI yoo fi pada si ori ayelujara, lẹhinna o tun bẹrẹ laifọwọyi.

Awọn orisun abajade

  • fresh: ìṣiṣẹ́ AI tuntun ló ṣe é.
  • cached_exact: ni ibamu pẹlu kaṣe ẹya AI lọwọlọwọ.
  • cached_stale: AI ni aisinipo, esi tuntun ti o ti fipamọ pada.
  • pending: kò tíì sí èsì ìkẹyìn.
  • failed: iṣẹ́ náà kùnà.
  • Nígbà tí iṣẹ́ kan kò bá tíì parí síbẹ̀, yẹ error_message wò fún àtúnyẹ̀wò tuntun tàbí ìdí ìdúró.

Quota ati Ìdíyelé

  • Lo `GET /api/open/quota` ṣaaju fifiranṣẹ awọn iṣẹ nla ti o ba nilo lati yago fun awọn ikuna ipin rẹ.
  • Ìṣiṣẹ́ AI tí orísun rẹ̀ jẹ́ `fresh` nìkan ló ń lo ìpín.
  • `cached_exact`, `cached_stale`, `pending`, ati awọn abajade `failed` ko jẹ ipin naa.
  • Awọn akọọlẹ ọfẹ lo ipin ojoojumọ akọkọ. Awọn akọọlẹ ti o sanwo lo awọn idii ipin igbagbogbo ti nṣiṣe lọwọ, lẹhinna igba diẹ tabi ipin ti o wa titi ni ibamu si eto imulo ẹhin.
  • Nigbati ipin ba ti pari, ifakalẹ iṣẹ-ṣiṣe pada `429` ati ṣafikun ifiranṣẹ aṣiṣe dipo ṣiṣẹda iṣẹ-ṣiṣe tuntun.

Cache ati abajade alabapade

  • Backend ń fi èsì àṣeyọrí pamọ́ sínú cache gẹ́gẹ́ bí hash àwòrán àti ẹ̀yà AI, pẹ̀lú namespace iṣẹ́ ìsàlẹ̀.
  • `cached_exact` túmọ̀ sí pé àwòrán kan náà ti ní èsì àṣeyọrí fún ẹ̀yà AI lọwọlọwọ, nítorí náà kò nílò ìṣiṣẹ́ AI tuntun.
  • `cached_stale` tumọ si pe iṣẹ AI wa ni aisinipo ati pe ẹhin pada si abajade itan ti o kẹhin ti o wa.
  • Nígbà tí `is_latest_ai_version` jẹ́ false, pa èsì mọ́ gẹ́gẹ́ bí dátà ìtàn tó wúlò ṣùgbọ́n tó yẹ fún àtúnyẹ̀wò.
  • Má ṣe rò pé gbogbo iṣẹ́ `done` lo ìpín; wo `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

Ka ipin lọwọlọwọ ati lilo ti o ku.

Beere Apẹẹrẹ
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Idahun Apẹẹrẹ
{
  "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

Ka ipo iṣẹ́ gbangba fún fífi iṣẹ́ ránṣẹ́ àti lílo èsì cache gẹ́gẹ́ bí àfidípò.

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

Tẹ aworan kan ki o si ṣẹda iṣẹ kan ṣoṣo.

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

Ka ipo iṣẹ-ṣiṣe kan ati kika ikẹhin.

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

Ka àwọn iṣẹ́ tí ó ṣẹ̀ṣẹ̀ ṣẹ̀ṣẹ̀ jẹ́ ti aṣàmúlò API bọ́tìnì lọ́wọ́lọ́wọ́.

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

Gbe ọpọlọpọ awọn aworan ni ibeere kan.

Beere Apẹẹrẹ
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"
Idahun Apẹẹrẹ
{
  "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}

Ka ilọsiwaju ipele ati awọn ipinlẹ iṣẹ-ṣiṣe fun faili kọọkan.

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

Sisan ti a ṣe iṣeduro

  • Ṣayẹwo `GET /api/open/ai-status` ṣaaju fifiranṣẹ awọn iṣẹ nla.
  • Tọju `task_id` tabi `batch_id` ninu eto tirẹ lẹsẹkẹsẹ lẹhin fifiranṣẹ.
  • Ka `queued`, `running`, `waiting_ai`, `batch_waiting_ai` àti `batch_running` sí ipo tí kò tíì parí, kí o sì máa ṣàyẹ̀wò ipo lẹ́ẹ̀kọ̀ọ̀kan.
  • Lo ìbéèrè ipele nígbà tí ọ̀nà nẹ́tíwọ́ọ̀kì sí backend bá ní latency gíga, tí iṣẹ́ tí a fi sílẹ̀ sì ń ṣe àtìlẹ́yìn ipo ipele.
  • Awọn ibeere ipele lọwọlọwọ n ṣan nipasẹ `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` túmọ̀ sí pé gbogbo nǹkan ṣì ń dúró dè iṣẹ́ AI náà, kò tíì ṣiṣẹ́ tòótọ́.
  • Nígbà tí iṣẹ́ tí a fi sílẹ̀ jẹ́ `CAD`, lo `POST /api/open/tasks` fún báyìí, kí o sì ka ìgbé-sókè ipele sí ohun tí kò sí.

Awọn akọsilẹ aṣiṣe

  • 400: ìbéèrè kò tọ́, tàbí iṣẹ́ tí a fi sílẹ̀ kò ṣe àtìlẹ́yìn ìgbé-sókè ipele.
  • 401: kọ́kọ́rọ́ API kò sí, kò tọ́, ó ti parí tàbí a ti pa á.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: iṣẹ-ṣiṣe tabi ipele ko ri, tabi ko ni nipasẹ olumulo lọwọlọwọ.
  • 413: fáìlì ti tóbi jù.
  • 415: Iru aworan ti ko ni atilẹyin tabi akoonu aworan ti ko wulo.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 ìgbé-sókè ipele kò sí
{
  "detail": "batch upload is not supported for business: cax"
}
401 kọ́kọ́rọ́ API sọnù tàbí tí kò wúlò
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 fáìlì tí ó tóbi jù
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 ìpín ti parí
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

Ṣetan lati ṣe idanwo iṣẹ naa?

Lo ibi iṣẹ-iṣẹ wẹẹbu fun fọto akọkọ, lẹhinna gbe si awọn bọtini API ni kete ti ọna kika abajade ba mu ẹrọ rẹ.

Forukọsilẹ ki o si gbe fọto kanṢẹda Bọtini API