API OCR đồng hồ nước
API OCR đồng hồ nước. Trang này ghi lại HTTP API công khai được phần phụ trợ của trang web cung cấp cho hoạt động tích hợp của bên thứ ba.
Bắt đầu bằng một lần tải lên thật
Đăng ký trước, tải ảnh đồng hồ nước của bạn trong workspace, rồi tạo API key khi bạn sẵn sàng tích hợp.
Tổng quan
- Sử dụng phần phụ trợ của trang web cho tất cả các tích hợp bên ngoài.
- Không gọi waterMeterAi trực tiếp từ chương trình của bên thứ ba.
- API mở chia sẻ cùng người dùng, hạn ngạch, bộ đệm, tác vụ và quy tắc kiểm tra như cổng web.
- Phần phụ trợ có thể nhắm mục tiêu các doanh nghiệp AI hạ nguồn khác nhau bằng cấu hình triển khai.
- Phản hồi tác vụ hiện bao gồm đối tượng result_summary chung để các doanh nghiệp khác nhau có thể hiển thị các loại kết quả khác nhau.
Xác thực
- Đăng nhập vào trang web và tạo khóa API trên trang API Khóa.
- Khóa API đầy đủ chỉ được hiển thị một lần khi nó được tạo.
- Gửi khóa trong tiêu đề Ủy quyền cho mọi yêu cầu.
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
Tải lên quy tắc
- Kích thước tệp tối đa: 20MB mỗi hình ảnh.
- Các định dạng được hỗ trợ: JPEG, PNG, WEBP.
- Phần phụ trợ xác thực nội dung tệp thực tế, không chỉ phần mở rộng tệp.
Thực thi kích thước tải lên
- Tải lên hàng loạt chấp nhận tối đa 8 hình ảnh theo mặc định, với giới hạn 20 MB cho mỗi hình ảnh và giới hạn tổng nội dung tệp là 20 MB.
- Một tệp hoặc lô vượt quá giới hạn sẽ trả về 413 trước khi xác thực hình ảnh hoặc tạo tác vụ; không có một phần lô nào được tạo ra.
- Phần phụ trợ thực thi số byte nhận được thực tế ngay cả khi Content-Length bị thiếu hoặc sử dụng chuyển khối.
Trạng thái nhiệm vụ
- queued: đã chấp nhận và chờ xử lý AI.
- running: hiện đang được xử lý hoặc đã giao cho người điều phối và vẫn đang bỏ phiếu cho kết quả cuối cùng.
- batch_waiting_ai: mọi mặt hàng trong lô đang chờ dịch vụ AI trực tuyến trở lại.
- batch_running: lô đã được giao cho người điều phối và vẫn đang được xử lý.
- done: đã hoàn tất thành công.
- failed: đang xử lý failed.
- waiting_ai: queued cho đến khi dịch vụ AI trực tuyến trở lại thì dịch vụ sẽ tự động tiếp tục lại.
Nguồn kết quả
- fresh: được tạo bởi lần chạy AI mới.
- cached_exact: khớp với bộ đệm của phiên bản AI hiện tại.
- cached_stale: AI ngoại tuyến, kết quả được lưu trong bộ nhớ đệm mới nhất được trả về.
- pending: chưa có kết quả cuối cùng.
- failed: nhiệm vụ failed.
- Khi một tác vụ chưa done, hãy kiểm tra error_message để biết lý do chờ hoặc thử lại mới nhất.
Hạn mức và tính phí
- Dùng `GET /api/open/quota` trước khi gửi khối lượng công việc lớn nếu tích hợp của bạn cần tránh lỗi hạn mức.
- Chỉ các lần chạy AI `fresh` mới tiêu thụ hạn mức.
- Các kết quả `cached_exact`, `cached_stale`, `pending` và `failed` không tiêu thụ hạn mức.
- Tài khoản miễn phí dùng hạn mức hằng ngày trước. Tài khoản trả phí dùng các gói hạn mức chu kỳ đang hoạt động, sau đó dùng hạn mức tạm thời hoặc cố định theo chính sách backend.
- Khi hết hạn mức, việc gửi tác vụ trả về `429` và thông báo lỗi thay vì tạo tác vụ mới.
Bộ nhớ đệm và độ mới của kết quả
- Backend lưu đệm kết quả thành công theo hash ảnh và phiên bản AI, bao gồm namespace của nghiệp vụ downstream.
- `cached_exact` nghĩa là cùng ảnh đã có kết quả thành công cho phiên bản AI hiện tại, nên không cần chạy AI mới.
- `cached_stale` nghĩa là dịch vụ AI ngoại tuyến và backend trả về kết quả lịch sử mới nhất hiện có.
- Khi `is_latest_ai_version` là false, hãy lưu kết quả như dữ liệu lịch sử có thể dùng nhưng cần xem xét.
- Đừng mặc định mọi tác vụ `done` đều tiêu thụ hạn mức; hãy kiểm tra `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/quotaĐọc hạn ngạch hiện tại và mức sử dụng còn lại.
Yêu cầu ví dụ
curl -X GET "https://watermeterai.com/api/open/quota" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Ví dụ phản hồi
{
"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-statusĐọc trạng thái dịch vụ công cộng để gửi tác vụ và dự phòng kết quả được lưu trong bộ nhớ đệm.
Yêu cầu ví dụ
curl -X GET "https://watermeterai.com/api/open/ai-status" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Ví dụ phản hồi
{
"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/tasksTải lên một hình ảnh và tạo một tác vụ duy nhất.
Yêu cầu ví dụ
curl -X POST "https://watermeterai.com/api/open/tasks" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \ -F "file=@D:\data\meter_001.jpg"
Ví dụ phản hồi
{
"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}Đọc một trạng thái nhiệm vụ và đọc lần cuối.
Yêu cầu ví dụ
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Ví dụ phản hồi
{
"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/tasksĐọc các tác vụ gần đây thuộc sở hữu của người dùng khóa API hiện tại.
Yêu cầu ví dụ
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Ví dụ phản hồi
{
"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/batchesTải lên nhiều hình ảnh trong một yêu cầu.
Yêu cầu ví dụ
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"
Ví dụ phản hồi
{
"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}Đọc tiến trình hàng loạt và trạng thái tác vụ trên mỗi tệp.
Yêu cầu ví dụ
curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \ -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Ví dụ phản hồi
{
"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": ""
}
]
}Luồng đề xuất
- Kiểm tra `GET /api/open/ai-status` trước khi gửi khối lượng công việc lớn.
- Lưu trữ `task_id` hoặc `batch_id` trong hệ thống của bạn ngay sau khi gửi.
- Hãy coi `queued`, `running`, `waiting_ai`, `batch_waiting_ai` và `batch_running` là trạng thái không phải cuối cùng và tiếp tục bỏ phiếu.
- Sử dụng yêu cầu hàng loạt khi đường dẫn mạng tới phần phụ trợ có độ trễ cao và doanh nghiệp được triển khai hỗ trợ chế độ hàng loạt.
- Yêu cầu hàng loạt hiện đang chuyển qua `webBackend -> dispatchCenter -> waterMeterAi`.
- `batch_waiting_ai` nghĩa là mọi mặt hàng vẫn đang chờ dịch vụ AI, chưa tích cực running.
- Khi doanh nghiệp đã triển khai là `CAD`, hãy sử dụng `POST /api/open/tasks` ngay bây giờ và coi tính năng tải lên hàng loạt là không khả dụng.
Ghi chú lỗi
- 400: yêu cầu không hợp lệ hoặc doanh nghiệp đã triển khai không hỗ trợ tải lên hàng loạt.
- 401: khóa API bị thiếu, không hợp lệ, hết hạn hoặc bị vô hiệu hóa.
- 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
- 404: không tìm thấy tác vụ hoặc lô hoặc không thuộc sở hữu của người dùng hiện tại.
- 413: tệp quá lớn.
- 415: loại hình ảnh không được hỗ trợ hoặc nội dung hình ảnh không hợp lệ.
- 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
Tải lên hàng loạt 400 không có sẵn
{
"detail": "batch upload is not supported for business: cax"
}401 khóa API bị thiếu hoặc không hợp lệ
{
"ok": false,
"error": "unauthorized",
"message": "Missing or invalid API key."
}Tệp 413 quá lớn
{
"ok": false,
"error": "file_too_large",
"message": "Maximum file size is 20MB."
}Hạn ngạch 429 đã hết
{
"ok": false,
"error": "quota_exhausted",
"message": "Quota exhausted.",
"quota": {
"remaining": 0,
"quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
}
}Sẵn sàng kiểm thử workflow?
Dùng web workspace cho ảnh đầu tiên, sau đó chuyển sang API keys khi định dạng kết quả phù hợp với hệ thống của bạn.