API na OCR na mitar ruwa
API na OCR na mitar ruwa. Wannan shafin yana bayyana HTTP API na jama'a da backend na shafin yanar gizo ke bayarwa don haɗin ɓangare na uku.
Fara tare da loda na ainihi
Yi rijista da farko, loda hoton mita na ruwa a cikin wurin aiki, sannan ƙirƙirar maɓallin API lokacin da kuke shirye don haɗawa.
Bayani
- Yi amfani da backend na shafin yanar gizo don duk haɗin waje.
- Kada ku kira waterMeterAi kai tsaye daga shirye-shiryen ɓangare na uku.
- Buɗaɗɗen API yana raba masu amfani iri ɗaya, rabo, cache, ayyuka, da ƙa'idodin dubawa kamar tashar yanar gizo.
- Backend na iya yin niyya ga sabis na AI na ƙasa daban-daban bisa tsarin turawa.
- Amsoshin aiki yanzu sun haɗa da abu na result_summary domin sabis daban-daban su iya nuna nau'ikan sakamako daban-daban.
Tabbatarwa
- Shiga cikin shafin yanar gizon kuma ƙirƙiri maɓallin API a kan shafin API Keys.
- Ana nuna cikakken maɓallin API sau ɗaya kawai lokacin da aka ƙirƙira shi.
- Aika maɓallin a cikin taken Authorization a kowane buƙata.
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
Dokokin Lodawa
- Matsakaicin girman fayil: 20MB a kowane hoto.
- Tsarin da ake tallafawa: JPEG, PNG, WEBP.
- Backend yana tabbatar da ainihin abun cikin fayil, ba kawai tsawo fayil ɗin ba.
Aiwatar da Iyakokin Girman Lodawa
- Loda rukuni suna karɓar hotuna 8 ta tsoho, tare da iyakar 20MB a kowane hoto da iyakar 20MB na abun cikin fayil.
- Fayil ko rukuni wanda ya wuce iyakarsa ya dawo 413 kafin tabbatar da hoto ko ƙirƙirar aiki; Babu wani ɓangare na rukuni da aka ƙirƙira.
- Backend yana tilasta ainihin adadin byte da aka karɓa ko da Content-Length ya ɓace ko ana amfani da canja wurin chunked.
Matsayin Aiki
- queued: an karɓa kuma yana jiran sarrafawar AI.
- running: ana sarrafawa yanzu, ko an riga an miƙa shi ga dispatcher kuma har yanzu ana duba matsayin don samun sakamakon ƙarshe.
- batch_waiting_ai: Kowane abu a cikin rukuni yana jiran sabis na AI ya dawo kan layi.
- batch_running: an riga an miƙa rukunin ga mai aikawa kuma har yanzu ana sarrafawa.
- done: an gama cikin nasara.
- failed: sarrafawa ta gaza.
- waiting_ai: an yi layi har sai sabis na AI ya dawo kan layi, sannan yana ci gaba kai tsaye.
Tushen Sakamako
- fresh: sabon sarrafawar AI ne ya samar da shi.
- cached_exact: ya dace da cache na AI na yanzu.
- cached_stale: AI layi, sabon sakamakon cache ya dawo.
- pending: babu sakamako na ƙarshe tukuna.
- failed: aikin ya gaza.
- Idan ba a gama aiki ba tukuna, duba error_message na sabon gwadawa ko dalilin jira.
Quota da lissafin kuɗi
- Yi amfani da `GET /api/open/quota` kafin ƙaddamar da manyan ayyuka idan haɗin ka yana buƙatar kauce wa gazawar kaso.
- Gudun `fresh` AI ne kawai ke cinye quota.
- `cached_exact`, `cached_stale`, `pending`, da `failed` sakamakon ba su cinye quota ba.
- Asusun kyauta suna amfani da ƙididdigar yau da kullun da farko. Asusun da aka biya suna amfani da fakitin quota na lokaci-lokaci, sannan na wucin gadi ko tsayayyen kaso bisa ga manufofin backend.
- Lokacin da ƙididdigar ta ƙare, ƙaddamar da aikin ya dawo `429` kuma ya haɗa da saƙon kuskure maimakon ƙirƙirar sabon aiki.
Cache da Sabuntar Sakamako
- Backend yana adana sakamako mai nasara a cache bisa hash na hoto da sigar AI, gami da namespace na sabis na ƙasa.
- `cached_exact` yana nufin wannan hoton ya riga ya sami sakamako mai nasara don sigar AI na yanzu, don haka ba a buƙatar sabon sarrafawar AI ba.
- `cached_stale` yana nufin sabis na AI ba shi layi ba kuma backend ya dawo da sabon sakamako na tarihi.
- Idan `is_latest_ai_version` ya kasance false, adana sakamakon a matsayin bayanan tarihi masu amfani amma da ya kamata a sake dubawa.
- Kada ku ɗauka kowane aikin `done` ya cinye quota; duba `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
/api/open/quotaKaranta quota na yanzu da sauran amfani.
Nemi Misali
curl -X GET "https://watermeterai.com/api/open/quota" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Misalin Amsa
{
"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
/api/open/ai-statusKaranta matsayin sabis na jama'a don ƙaddamar da aiki da komawa ga sakamakon cache.
Nemi Misali
curl -X GET "https://watermeterai.com/api/open/ai-status" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Misalin Amsa
{
"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
/api/open/tasksLoda hoto ɗaya kuma ƙirƙirar aiki ɗaya.
Nemi Misali
curl -X POST "https://watermeterai.com/api/open/tasks" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \ -F "file=@D:\data\meter_001.jpg"
Misalin Amsa
{
"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}
/api/open/tasks/{task_id}Karanta matsayi ɗaya da karatu na ƙarshe.
Nemi Misali
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Misalin Amsa
{
"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
/api/open/tasksKaranta ayyukan kwanan nan da mai amfani da maɓallin API na yanzu ya mallaka.
Nemi Misali
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Misalin Amsa
{
"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
/api/open/batchesLoda hotuna da yawa a cikin buƙata ɗaya.
Nemi Misali
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"
Misalin Amsa
{
"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}
/api/open/batches/{batch_id}Karanta ci gaban batch da jihohin aikin kowane fayil.
Nemi Misali
curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Misalin Amsa
{
"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": ""
}
]
}Bayar da shawarar Flow
- Bincika `GET /api/open/ai-status` kafin aikawa da manyan ayyuka.
- Ajiye `task_id` ko `batch_id` a cikin na'urarka nan da nan bayan ƙaddamarwa.
- Bi da `queued`, `running`, `waiting_ai`, `batch_waiting_ai` da `batch_running` a matsayin matsayi marasa ƙarshe kuma ku ci gaba da duba matsayi lokaci-lokaci.
- Yi amfani da buƙatun batch lokacin da hanyar cibiyar sadarwa zuwa backend ke da babban latency kuma sabis ɗin da aka tura yana tallafawa yanayin batch.
- A halin yanzu, buƙatun Batch suna gudana ta hanyar `webBackend -> dispatchCenter -> waterMeterAi`.
- `batch_waiting_ai` yana nufin kowane abu har yanzu yana jiran sabis na AI , ba a gudanar da aiki ba tukuna.
- Lokacin da sabis ɗin da aka tura shi ne `CAD`, yi amfani da `POST /api/open/tasks` a yanzu kuma ɗauki lodawar batch a matsayin marar samuwa.
Bayanin kuskure
- 400: buƙata mara inganci, ko sabis ɗin da aka tura ba ya goyon bayan loda rukuni.
- 401: maɓallin API ya ɓace, ba shi da inganci, ya ƙare ko an kashe shi.
- 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
- 404: aiki ko rukuni ba a samo ba, ko kuma ba mallakar mai amfani na yanzu ba.
- 413: fayil ɗin ya yi girma sosai.
- 415: nau'in hoto da ba a tallafawa ba ko abun ciki na hoto mara inganci.
- 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 ba shi da loda
{
"detail": "batch upload is not supported for business: cax"
}401 ɓace ko maɓallin maɓallin API
{
"ok": false,
"error": "unauthorized",
"message": "Missing or invalid API key."
}413 fayil ɗin ya yi girma sosai
{
"ok": false,
"error": "file_too_large",
"message": "Maximum file size is 20MB."
}429 quota ya gaji
{
"ok": false,
"error": "quota_exhausted",
"message": "Quota exhausted.",
"quota": {
"remaining": 0,
"quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
}
}Shirye don gwada aikin?
Yi amfani da wurin aiki na yanar gizo don hoto na farko, sannan matsawa zuwa maɓallan API da zarar tsarin sakamako ya dace da na'urarka.