WaterMeter AI
語言粵語
其他語言

水錶 OCR API

水錶 OCR API. 本頁說明網站後端向第三方系統開放的 HTTP API。

先由真實圖片上載開始

先註冊帳戶，在工作台上載自己的水錶相片；確認結果格式適合後，再建立 API 密鑰接入系統。

註冊並上載相片建立 API 密鑰

總覽

  • 所有外部系統整合都應呼叫網站後端。
  • 第三方程式不應直接呼叫 waterMeterAi。
  • 開放 API 與網站共用用戶、配額、快取、任務和審核規則。
  • 後端可按部署設定切換不同的下游 AI 服務。
  • 任務回應包含通用 result_summary 物件，方便不同服務顯示不同類型的結果。

身份驗證

  • 先登入網站，再到 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 或使用分塊傳輸，後端仍會按實際收到的位元組數量執行限制。

任務狀態

  • queued：已接收，正在等候 AI 處理。
  • running：AI 正在處理，或任務已交給分派器並仍在輪詢最終結果。
  • batch_waiting_ai：整個批次的每個項目都在等待 AI 服務重新上線，尚未開始執行。
  • batch_running：整個批次已交給分派器，仍在處理中。
  • done：成功完成。
  • failed：處理失敗。
  • waiting_ai：排隊直到 AI 服務重新上線，然後自動恢復。

結果來源

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

配額與計費

  • 如果你的系統需要避免配額不足造成失敗，提交大量任務前請先呼叫 `GET /api/open/quota`。
  • 只有來源為 `fresh` 的新 AI 識別才會消耗配額。
  • `cached_exact`、`cached_stale`、`pending` 和 `failed` 結果不消耗配額。
  • 免費帳戶會先使用每日配額。付費帳戶會按後端規則先使用有效的定期配額套裝，再使用臨時或固定配額。
  • 配額用完時，提交任務會傳回 `429` 和錯誤訊息，不會建立新任務。

快取與結果時效

  • 後端按圖片 hash、AI 版本和下游服務 namespace 快取成功結果。
  • `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": ""
    }
  ]
}

建議流程

  • 大量提交前，先檢查 `GET /api/open/ai-status`。
  • 提交後立即在自己的系統儲存 `task_id` 或 `batch_id`。
  • 將 `queued`、`running`、`waiting_ai`、`batch_waiting_ai` 和 `batch_running` 視為非最終狀態並繼續輪詢。
  • 如果連接後端的網絡延遲較高，而且已部署服務支援批次模式，應優先使用批次請求。
  • 批次請求目前經過 `webBackend -> dispatchCenter -> waterMeterAi`。
  • `batch_waiting_ai` 表示整批項目仍在等待 AI 服務，尚未開始執行。
  • 當已部署服務為 `CAD`，目前只使用 `POST /api/open/tasks`，並視為不支援批次上載。

錯誤提示

  • 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 密鑰