水錶 OCR API

水錶 OCR API. 此頁面記錄了網站後端為第三方整合公開的公共 HTTP API。

從真正的上傳開始

首先註冊，在工作區上傳您自己的水錶照片，然後在準備整合時建立 API 密鑰。

註冊並上傳照片建立一個 API 密鑰

搜尋端點

概述

使用網站後端進行所有外部整合。
不要直接從第三方程式呼叫 waterMeterAi。
開放的 API 與 Web 入口網站共用相同的使用者、配額、快取、任務和審核規則。
後端可以透過部署配置針對不同的下游AI業務。
任務回應現在包含通用的 result_summary 對象，以便不同的企業可以顯示不同的結果類型。

認證

登入網站並在 API 密鑰頁面上建立 API 密鑰。
完整的 API 密鑰在建立時僅顯示一次。
在每個請求上發送 Authorization 標頭中的金鑰。

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

上傳規則

最大檔案大小：每張圖片 20MB。
支援的格式：JPEG、PNG、WEBP。
後端驗證實際文件內容，而不僅僅是文件副檔名。

上傳大小強制執行

預設情況下，批次上傳最多接受 8 個影像，每個影像限制為 20MB，檔案內容總量限制為 20MB。
超過其限制的檔案或批次在影像驗證或任務建立之前返回 413；未建立部分批次。
即使 Content-Length 遺失或使用分塊傳輸，後端也會強制執行實際接收的位元組計數。

任務狀態

已排隊：已接受並等待 AI 處理。
running：目前正在處理，或已經交給調度程式並且仍在輪詢最終結果。
batch_waiting_ai：批次中的每個項目都在等待 AI 服務重新上線。
batch_running：批次已經交給調度程序並且仍在處理中。
完成：成功完成。
失敗：處理失敗。
waiting_ai：排隊直到 AI 服務重新上線，然後自動恢復。

結果來源

fresh：由新的 AI 運行產生。
cached_exact：符合目前 AI 版本快取。
cached_stale: AI 離線，回傳最新的快取結果。
待定：尚未有最終結果。
失敗：任務失敗。
當任務尚未完成時，請檢查 error_message 以了解最新的重試或等待原因。

配額和計費

如果您的整合需要避免配額失敗，請在提交大型工作負載之前使用 `GET /api/open/quota`。
僅 `fresh` AI 運轉消耗配額。
`cached_exact`、`cached_stale`、`pending` 和 `failed` 結果不消耗配額。
免費帳戶首先使用每日配額。付費帳戶使用活躍的定期配額包，然後根據後端策略使用臨時或固定配額。
當配額耗盡時，任務提交將傳回 `429` 並包含錯誤訊息，而不是建立新任務。

緩存和結果新鮮度

後端透過影像雜湊和AI版本快取成功結果，包括下游業務命名空間。
`cached_exact` 表示同一圖像對於目前 AI 版本已經有成功的結果，因此不需要新的 AI 運行。
`cached_stale` 表示 AI 服務已離線，後端傳回了最新的可用歷史結果。
當 `is_latest_ai_version` 為 false 時，將結果儲存為可用但可審查的歷史資料。
不要假設每個 `done` 任務都消耗配額；檢查`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`

讀取目前配額和剩餘使用量。

請求範例

curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

回應範例

{
  "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`

讀取任務提交和快取結果回退的公共服務狀態。

請求範例

curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

回應範例

{
  "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`

上傳一張圖像並建立一個任務。

請求範例

curl -X POST "https://watermeterai.com/api/open/tasks" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \
  -F "file=@D:\data\meter_001.jpg"

回應範例

{
  "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}`

讀取一項任務狀態和最終讀數。

請求範例

curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

回應範例

{
  "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 關鍵使用者擁有的最近任務。

請求範例

curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

回應範例

{
  "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`

在一個請求中上傳多張圖片。

請求範例

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"

回應範例

{
  "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}`

讀取批次進度和每個檔案的任務狀態。

請求範例

curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"

回應範例

{
  "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": ""
    }
  ]
}

錯誤提示

400：請求無效，或部署的業務不支援批次上傳。
401：API 金鑰缺失、無效、過期或停用。
403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
404：找不到任務或批次，或不屬於目前使用者。
413：文件太大。
415：不支援的圖像類型或無效的圖像內容。
429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.

400批次上傳不可用

{
  "detail": "batch upload is not supported for business: cax"
}

401 API 金鑰遺失或無效

{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}

413 文件太大

{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}

429 配額已用完

{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

準備好測試工作流程了嗎？

使用網路工作區拍攝第一張照片，然後在結果格式適合您的系統後移至 API 鍵。

註冊並上傳照片建立一個 API 密鑰

水錶 OCR API

從真正的上傳開始

概述

認證

API Key Permissions and Limits

上傳規則

上傳大小強制執行

任務狀態

結果來源

配額和計費

緩存和結果新鮮度

Task completion webhooks

GET/api/open/quota

GET/api/open/ai-status

POST/api/open/tasks

GET/api/open/tasks/{task_id}

GET/api/open/tasks

POST/api/open/batches

GET/api/open/batches/{batch_id}

推薦流量

錯誤提示

準備好測試工作流程了嗎？

GET`/api/open/quota`

GET`/api/open/ai-status`

POST`/api/open/tasks`

GET`/api/open/tasks/{task_id}`

GET`/api/open/tasks`

POST`/api/open/batches`

GET`/api/open/batches/{batch_id}`