WaterMeter AI
언어한국어
다른 언어

수도 계량기 OCR API

수도 계량기 OCR API. 이 페이지에서는 외부 시스템 연동을 위해 웹사이트 백엔드가 제공하는 공개 HTTP API를 설명합니다.

실제 업로드로 시작

먼저 가입한 뒤 웹 작업 공간에서 수도 계량기 사진을 업로드해 보세요. 연동할 준비가 되면 API 키를 만들 수 있습니다.

가입하고 사진 업로드API key 만들기

개요

  • 모든 외부 통합에 웹사이트 백엔드를 사용하세요.
  • 타사 프로그램에서 직접 waterMeterAi을 호출하지 마세요.
  • 공개 API은 웹 포털과 동일한 사용자, 할당량, 캐시, 작업 및 감사 규칙을 공유합니다.
  • 백엔드는 배포 구성에 따라 다양한 다운스트림 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가 누락되거나 청크 전송이 사용되는 경우에도 실제 수신된 바이트 수를 적용합니다.

작업 상태

  • queued: 승인되었으며 AI 처리를 기다리고 있습니다.
  • running: 현재 처리 중이거나 이미 디스패처에 전달되었으며 여전히 최종 결과를 폴링하고 있습니다.
  • batch_waiting_ai: 배치의 모든 항목은 AI 서비스가 다시 온라인 상태가 되기를 기다리고 있습니다.
  • batch_running: 배치가 이미 디스패처에 전달되었으며 아직 처리 중입니다.
  • done: 성공적으로 완료되었습니다.
  • failed: failed을(를) 처리 중입니다.
  • waiting_ai: queued AI 서비스가 다시 온라인 상태가 될 때까지 자동으로 재개됩니다.

결과 소스

  • fresh: 새로운 AI 실행으로 생성됩니다.
  • cached_exact: 현재 AI 버전 캐시와 일치합니다.
  • cached_stale: AI 오프라인, 캐시된 최신 결과가 반환되었습니다.
  • pending: 아직 최종 결과가 없습니다.
  • failed: 작업 failed.
  • 작업이 아직 done이 아닌 경우 error_message에서 최신 재시도 또는 대기 이유를 확인하세요.

할당량 및 과금

  • 대량 작업을 제출하기 전에 할당량 오류를 피해야 한다면 `GET /api/open/quota`를 사용하세요.
  • `fresh` AI 실행만 할당량을 사용합니다.
  • `cached_exact`, `cached_stale`, `pending`, `failed` 결과는 할당량을 사용하지 않습니다.
  • 무료 계정은 일일 할당량을 먼저 사용합니다. 유료 계정은 백엔드 정책에 따라 활성 주기 할당량 패키지, 그다음 임시 또는 고정 할당량을 사용합니다.
  • 할당량이 소진되면 작업 제출은 새 작업을 만들지 않고 `429`와 오류 메시지를 반환합니다.

캐시 및 결과 최신성

  • 백엔드는 이미지 해시와 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`은 모든 항목이 아직 running이 아닌 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."
  }
}

workflow를 테스트할 준비가 되었나요?

첫 사진은 web workspace에서 사용하고, 결과 형식이 맞으면 API key 단계로 이동하세요.

가입하고 사진 업로드API key 만들기