WaterMeter AI
LinguaGalego
Outras linguas

API OCR de contadores de auga

API OCR de contadores de auga. Esta páxina documenta o HTTP API público exposto polo backend do sitio web para integracións de terceiros.

Comeza cunha subida real

Rexístrate primeiro, sube a túa propia foto do contador de auga no espazo de traballo e logo crea unha clave API cando esteas listo para integrar.

Rexístrate e sube unha fotoCrea unha clave API

Visión xeral

  • Usa o backend do sitio web para todas as integracións externas.
  • Non chames directamente a waterMeterAi desde programas de terceiros.
  • O API aberto comparte os mesmos usuarios, cota, caché, tarefas e regras de auditoría que o portal web.
  • O backend pode usar diferentes servizos de AI descendentes mediante a configuración de despregamento.
  • As respostas das tarefas inclúen un obxecto result_summary xenérico para que diferentes servizos mostren distintos tipos de resultados.

Autenticación

  • Inicia sesión na páxina web e crea unha clave API na páxina de API Chaves.
  • A clave API completa só se mostra unha vez cando se crea.
  • Envía a chave na cabeceira Authorization en cada solicitude.
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

Regras de Subida

  • Tamaño máximo de ficheiro: 20MB por imaxe.
  • Formatos soportados: JPEG, PNG, WEBP.
  • O backend valida o contido real do ficheiro, non só a extensión do ficheiro.

Aplicación do tamaño da subida

  • As subidas por lotes aceptan ata 8 imaxes por defecto, cun límite de 20MB por imaxe e un límite total de contido de ficheiro de 20MB.
  • Un ficheiro ou lote que supera o seu límite devolve 413 antes da validación da imaxe ou creación de tarefas; non se crea ningún lote parcial.
  • O backend aplica o número real de bytes recibidos mesmo cando falta Content-Length ou se usa unha transferencia fragmentada.

Estados da tarefa

  • queued: Aceptada e agardando o procesamento da AI.
  • running: Estase procesando, ou xa foi entregada ao despachador e compróbase periodicamente o estado para obter o resultado final.
  • batch_waiting_ai: Todos os elementos do lote agardan que o servizo de AI volva estar en liña.
  • batch_running: O lote xa foi entregado ao despachador e aínda se está procesando.
  • done: Rematou correctamente.
  • failed: O procesamento fallou.
  • waiting_ai: Permanece en cola ata que o servizo de AI volve estar en liña e logo retómase automaticamente.

Fontes do resultado

  • fresh: Xerado por un novo procesamento de AI.
  • cached_exact: Coincidiu coa caché da versión actual da AI.
  • cached_stale: A AI está desconectada e devolveuse o último resultado en caché.
  • pending: Aínda non hai resultado final.
  • failed: A tarefa fallou.
  • Cando unha tarefa aínda non estea rematada, comproba error_message a última razón de reintento ou espera.

Cota e facturación

  • Usa `GET /api/open/quota` antes de enviar cargas de traballo grandes se a túa integración necesita evitar fallos nas cotas.
  • Só os novos procesamentos de AI con resultado `fresh` consumen cota.
  • `cached_exact`, `cached_stale`, `pending`e `failed` resultados non consumen a cota.
  • As contas gratuítas usan primeiro a cota diaria. As contas pagadas usan paquetes de cotas periódicas activas, logo cotas temporais ou fixas segundo a política de backend.
  • Cando se esgota a cota, a entrega da tarefa devolve `429` e inclúe unha mensaxe de erro en lugar de crear unha nova tarefa.

Caché e frescura dos resultados

  • O backend almacena en caché os resultados correctos por hash de imaxe e versión da AI, incluído o namespace do servizo descendente.
  • `cached_exact` significa que a mesma imaxe xa ten un resultado exitoso para a versión AI actual, polo que non foi necesaria ningunha nova execución AI .
  • `cached_stale` significa que o servizo AI está desconectado e o backend devolveu o último resultado histórico dispoñible.
  • Cando `is_latest_ai_version` sexa false, almacena o resultado como datos históricos utilizables pero revisables.
  • Non supoñas que cada `done` tarefa consume unha cota consumida; Comproba `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

Lea a cota actual e o uso restante.

Exemplo de Solicitude
curl -X GET "https://watermeterai.com/api/open/quota" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exemplo de resposta
{
  "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

Lea o estado do servizo público para o envío de tarefas e o respaldo de resultados en caché.

Exemplo de Solicitude
curl -X GET "https://watermeterai.com/api/open/ai-status" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exemplo de resposta
{
  "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

Sube unha imaxe e crea unha única tarefa.

Exemplo de Solicitude
curl -X POST "https://watermeterai.com/api/open/tasks" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx" \
  -F "file=@D:\data\meter_001.jpg"
Exemplo de resposta
{
  "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}

Le o estado dunha tarefa e a lectura final.

Exemplo de Solicitude
curl -X GET "https://watermeterai.com/api/open/tasks/task_a" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exemplo de resposta
{
  "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

Lea as tarefas recentes que pertence ao usuario API clave actual.

Exemplo de Solicitude
curl -X GET "https://watermeterai.com/api/open/tasks?limit=20" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exemplo de resposta
{
  "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

Sube varias imaxes nunha soa solicitude.

Exemplo de Solicitude
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"
Exemplo de resposta
{
  "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}

Lea o progreso do lote e os estados da tarefa por expediente.

Exemplo de Solicitude
curl -X GET "https://watermeterai.com/api/open/batches/5a14f4e5f6d34fdabce00e62c0dd0001" \
  -H "Authorization: Bearer wm_xxxxxxxxxxxxxxxxx"
Exemplo de resposta
{
  "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": ""
    }
  ]
}

Fluxo recomendado

  • Comproba `GET /api/open/ai-status` antes de enviar cargas de traballo grandes.
  • Garda `task_id` ou `batch_id` no teu propio sistema inmediatamente despois de enviar.
  • Trata `queued`, `running`, `waiting_ai`, `batch_waiting_ai` e `batch_running` como estados non finais e segue comprobando o estado periodicamente.
  • Usa peticións por lotes cando o camiño de rede ao backend teña alta latencia e o servizo despregado admita o modo batch.
  • Actualmente, as solicitudes por lotes flúen a través `webBackend -> dispatchCenter -> waterMeterAi`.
  • `batch_waiting_ai` significa que todos os artigos aínda están esperando o servizo de AI , aínda non están en funcionamento activo.
  • Cando o servizo despregado sexa `CAD`, usa `POST /api/open/tasks` por agora e considera non dispoñible a subida por lotes.

Notas de erro

  • 400: solicitude inválida, ou o servizo despregado non admite a carga por lotes.
  • 401: falta unha API clave, non é válida, caducada ou desactivada.
  • 403: the user account is not active, the key lacks the required scope, or the source IP is outside the key allowlist.
  • 404: tarefa ou lote non atopada, ou non pertencente ao usuario actual.
  • 413: arquivo demasiado grande.
  • 415: tipo de imaxe non soportado ou contido de imaxe inválido.
  • 429: quota exhausted or the API key request, submission, or concurrency limit was exceeded.
400 carga por lotes non dispoñible
{
  "detail": "batch upload is not supported for business: cax"
}
401 clave API ausente ou inválida
{
  "ok": false,
  "error": "unauthorized",
  "message": "Missing or invalid API key."
}
413 arquivo demasiado grande
{
  "ok": false,
  "error": "file_too_large",
  "message": "Maximum file size is 20MB."
}
429 cota esgotada
{
  "ok": false,
  "error": "quota_exhausted",
  "message": "Quota exhausted.",
  "quota": {
    "remaining": 0,
    "quota_summary_text": "Free daily quota: 20/20 used today. Remaining: 0."
  }
}

¿Preparado para probar o fluxo de traballo?

Usa o espazo de traballo web para a primeira foto e pasa ás chaves de API cando o formato do resultado se axuste ao teu sistema.

Rexístrate e sube unha fotoCrea unha clave API