WaterMeter AI
ЕзикБългарски
Други езици

API за OCR на водомери

API за OCR на водомери. Тази страница документира публичния HTTP API, изложен от бекенда на уебсайта за интеграции на трети страни.

Започнете с истинско качване

Първо се регистрирайте, качете своя собствена снимка на водомера в работното пространство и след това създайте API ключ, когато сте готови за интегриране.

Регистрирайте се и качете снимкаСъздайте API ключ

Преглед

  • Използвайте бекенда на уебсайта за всички външни интеграции.
  • Не извиквайте waterMeterAi директно от програми на трети страни.
  • Open 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

Правила за качване

  • Максимален размер на файла: 20 MB на изображение.
  • Поддържани формати: JPEG, PNG, WEBP.
  • Бекендът валидира действителното файлово съдържание, а не само файловото разширение.

Налагане на размер на качване

  • Пакетните качвания приемат до 8 изображения по подразбиране, с ограничение от 20 MB на изображение и ограничение от 20 MB общо съдържание на файлове.
  • Файл или партида, които надвишават своя лимит, връща 413 преди валидиране на изображението или създаване на задача; не се създава частична партида.
  • Бекендът налага действителния брой получени байтове дори когато липсва Content-Length или се използва прехвърляне на парчета.

Състояния на задачата

  • queued: прието и чака обработка от AI.
  • running: в момента се обработва или вече е предадено на диспечера и все още чака окончателен резултат.
  • 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` и включва съобщение за грешка вместо създаване на нова задача.

Кеш и актуалност на резултатите

  • Бекендът кешира успешни резултати по хеш на изображението и версия на AI, включително пространството от имена на съответната услуга.
  • `cached_exact` означава, че същото изображение вече има успешен резултат за текущата версия на AI, така че не е необходимо ново изпълнение на AI.
  • `cached_stale` означава, че услугата AI е офлайн и бекендът е върнал последния наличен исторически резултат.
  • Когато `is_latest_ai_version` е невярно, запазете резултата като използваеми, но прегледани исторически данни.
  • Не приемайте, че всяка `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 ключ