Sign In
Sign Out

How Carmen Cloud's APIs, Engines, Mobile Clients, and On-Prem Components Fit Together

Carmen Cloud brings together all core recognition technologies developed by Adaptive Recognition – ANPR, MMR, ADR, industrial code reading, personal-document authentication, mobile-based data collection, and on-prem recognition engines – into one coherent, developer-friendly platform. This article explains what each component does, how they differ, and which one fits a given real-world scenario.

This overview walks through the entire ecosystem – including camera-based, mobile-based, cloud, and on-prem pipelines.

TL/DR​

Carmen Cloud is a unified recognition ecosystem covering road vehicles, cargo, document authentication, mobile data capture, and on‑premise processing.

Use this quick guide to choose the right component instantly:

  • Road‑vehicle image → Vehicle API
  • Container / rail / trailer codes → Transport API
  • Identity documents, Osmond‑based Document Authentication → PR API
  • Subscription‑based licensing for engines & SDKs → License Service
  • Offline / on‑prem / ultra‑low latency → Carmen Worker
  • Live video streams → Vehicle Detector
  • Mobile‑camera recognition → Carmen Mobile
  • Managing workspaces, API keys, subscriptions and credits → Cloud Dashboard
  • Operational integrations → Carmen Cloud API

The Carmen Cloud ecosystem at a glance​

Camera(s)
   │
   ├── Vehicle Detector (optional)
   │       │
   │       └── crops → Carmen Worker or Carmen Cloud
   │
Carmen Mobile
   │
   └── frames/crops → Carmen Worker or Carmen Cloud

Carmen Cloud APIs
   ├── Vehicle API
   ├── Transport API
   ├── PR API
   └── Carmen Cloud API
   │
   └── results → Webhooks / Event Bus / Storage → Your Application

1. Vehicle API – ANPR, MMR, ADR and full vehicle intelligence​

When people think about license plate recognition, they often imagine a simple text extraction process – but modern mobility systems require much more. That's why the Vehicle API doesn't just read plates: it helps software understand the entire vehicle.

Whether you're building parking automation, road-usage billing, or a high-end tolling back office, the Vehicle API becomes the foundation of real-world decision-making.

It is the API you use when the subject of the image is a road vehicle.

What the Vehicle API does​

In a single request, the Vehicle API can:

  • perform ANPR – license plate reading and normalization,
  • perform MMR – classify make, model family, and color,
  • detect ADR hazard signs on trucks,
  • return vehicle attributes such as model generation/variation or viewpoint,
  • provide confidence scores for each recognized element.

The API is region-aware. Each request selects a recognition engine set tuned for a geographic area using a region code:

  • eur – Europe
  • nam – North America
  • cam – Central America
  • sam – South America
  • afr – Africa
  • me – Middle East
  • cas – Central Asia
  • eas – East Asia
  • sas – South Asia
  • aus – Australia

This region abstraction lets you work with a single API surface while still using specialized engines behind the scenes.

Typical use cases for the Vehicle API​

  • Tolling and road-usage billing
  • Parking automation & LPR barriers
  • Smart mobility & city analytics
  • Border/gate control
  • Fleet, depot, and yard management
  • Automated enforcement workflows

For a deeper technical overview of the request and response model, see the Vehicle API documentation.

The API response format is stable across all regions and is mirrored on-premise when you use Carmen Worker, which makes cloud ↔ on-prem switching straightforward.

2. Transport API – ISO containers, rail wagons, truck identifiers​

Logistics environments look nothing like traditional traffic lanes: containers are dirty, scratched, misaligned, and sometimes outright chaotic.

The Transport API was designed exactly for these conditions. Instead of treating containers, trailers, and railcars as special cases, it gives you one unified interface for identifying all major freight identifiers across multiple industries.

This API focuses on industrial and cargo identifiers.

Supported recognition types​

  • ISO / ILU container codes (iso)
  • truck and trailer body identifiers (truck)
  • European rail wagon IDs (eu-rail)
  • North American railcar IDs (am-rail)

You select the engine by indicating a type in the URL path. This enables one consistent abstraction over multiple freight modes.

Designed for logistics and intermodal operations​

Common scenarios:

  • ports and container terminals
  • intermodal freight hubs
  • customs workflows
  • depot automation
  • inventory tracking
  • industrial audit/compliance tasks

Many deployments use Vehicle API + Transport API together to identify both the vehicle and its cargo.

For more details on field types, error handling, and integration patterns, visit the Transport API reference.

3. PR API – Cloud-based Document Authentication (Osmond document readers)​

Physical identity documents remain one of the strongest trust anchors in customer onboarding, banking, border control, and countless service flows.

The integration between Osmond document-reading hardware and Carmen Cloud helps bridge the gap between physical documents and digital verification by handling the microscopic details that make a document authentic – so developers can focus on user experience rather than forensic complexity.

What this layer does today​

It:

  • validates identity documents captured by Osmond scanners,
  • checks structural and security features,
  • analyzes MRZ/VIZ elements,
  • returns an authentication result with detailed indicators.

This supports:

  • onboarding kiosks,
  • border-control systems,
  • banking and KYC flows,
  • customer-service verification points.

A more general-purpose Document API is under development.

If you want to see the underlying hardware platform, check out the Osmond passport reader and ID scanner family.

4. License Service – cloud-based licensing for engines, SDKs, Worker deployments, and downloadable products​

The License Service is a cloud-hosted licensing backend that replaces traditional hardware-based licensing with secure, subscription-driven activation.

It enables integrators to:

  • activate and revoke entitlements centrally via cloud subscriptions,
  • license all Adaptive Recognition engines and SDKs without physical dongles,
  • use the same entitlement across cloud APIs, on-prem Carmen Worker clusters, and downloadable SDKs,
  • manage licensing across deployments in different locations,
  • monitor entitlement status,
  • eliminate overhead of hardware keys.

Before processing images, local engines verify entitlements with the License Service, supporting fleet-wide and hybrid deployments.

For implementation details and client-side integration patterns, see the License Service client documentation.

5. Carmen Worker – full on-prem recognition engine​

Not every environment has the luxury of cloud connectivity. Some lanes are air-gapped by design; some countries impose strict data residency rules; some use-cases simply require sub-100-millisecond latency. That's exactly where Carmen Worker shines. It behaves like the cloud, speaks the same JSON, but runs directly on your infrastructure – whether that's a Docker host or your own AWS account via the SAR template.

The Carmen Worker is the on-premise runtime for the same vehicle and transport engines used in Carmen Cloud. It is deployed as a Docker container and exposes local HTTP endpoints:

http://localhost:8080/vehicle/{region}
http://localhost:8080/transport/{type}

Key characteristics​

  • No API key required
  • No cloud traffic
  • Unlimited requests
  • Low, predictable latency
  • Same JSON format as cloud

Switching between cloud and on-prem often only requires changing the base URL.

Running Worker in your own AWS account (SAR deployment)​

For integrators without local infrastructure – but who need an isolated environment separated from Carmen Cloud – the Worker can be deployed via the carmen-worker-cluster AWS Serverless Application Repository template.

It provides:

  • isolated VPC
  • optional WAF / JWT protection
  • private API endpoints
  • scalable worker cluster
  • CloudWatch monitoring

This enables a fully self-contained recognition environment inside the customer's AWS account.

For deployment guides, configuration examples, and security best practices, refer to the Carmen Worker documentation and the Carmen Worker SAR Infrastructure.

6. Vehicle Detector – stream-to-crop engine for high-volume pipelines​

A camera stream is messy: vehicles appear at different angles, speeds, lighting conditions, or not at all. The Vehicle Detector's job is to turn this chaos into a clean stream of recognition-ready crops. It works quietly in the background and handles the "boring but essential" job of finding the right frame so your recognition pipeline stays fast, accurate, and predictable.

The Vehicle Detector extracts relevant frames from video streams and forwards them to recognition engines.

It ingests RTSP or MJPEG streams (or frame sequences), detects vehicles, crops them, and forwards those crops to the Vehicle API (cloud or on-prem).

Responsibilities​

  • connect to camera streams
  • detect vehicles
  • crop and normalize frames
  • apply rate limiting
  • forward crops to the chosen recognition endpoint
  • optionally publish events

When to use it​

Ideal for large camera networks, continuous operation, and high-throughput pipelines.

You can learn more about configuration options and health monitoring in the Vehicle Detector agent guide.

7. Carmen Mobile – mobile-based detection, tracking, and data collection​

Fixed cameras aren't always possible – think patrol units, temporary enforcement, or pop-up checkpoints at events. Carmen Mobile turns any modern mobile device into a powerful, field-ready recognition client.

It handles detection, tracking, image capture, and even offline storage, making it ideal for mobile operations that need professional-grade recognition without the complexity of installing physical infrastructure.

While conceptually similar to the Vehicle Detector, it operates using the mobile camera and adds additional functionality.

What Carmen Mobile does​

  • performs real-time vehicle detection using the device camera,
  • performs vehicle tracking to find the optimal capture moment,
  • automatically calls:
    • the Carmen Cloud's Vehicle API, or
    • a local Carmen Worker
  • processes still images from:
    • camera snapshots,
    • the device gallery,
    • local file storage,
  • supports whitelist/blacklist logic,
  • sends webhook events to arbitrary backends,
  • supports offline or low-connectivity scenarios.

Carmen Mobile is a full-featured data-gathering and preprocessing client for field operations, patrol units, parking enforcement, temporary checkpoints, and any scenario where fixed camera infrastructure is unavailable.

For usage examples, configuration screens, and deployment scenarios, see the Carmen Mobile documentation.

8. Cloud Dashboard – workspaces, subscriptions, API keys and operations​

The Cloud Dashboard is the management interface for Carmen Cloud. It is where users organize business access around workspaces instead of a single personal account.

A workspace owns the operational state of an integration:

  • subscriptions and prepaid Carmen credits,
  • API keys and product access per key,
  • API version and engine parameter overrides,
  • usage statistics,
  • temporary event storage and webhook forwarding,
  • users, invitations, roles and ownership transfer.

This model lets a company keep billing, keys, events and usage together even when several users collaborate on the same integration. A user can own one workspace, be invited to another, and have different permissions in each.

Typical Dashboard roles are:

  • Owner – full workspace control, including ownership and user management.
  • Administration – workspace operations such as API key and integration settings.
  • Billing – subscription, credit purchase and billing portal access.

For the full overview, see the Cloud Dashboard documentation. Workspace operations are also available programmatically through the Carmen Cloud API, authenticated with a bearer token obtained from your API key (see Authentication).

9. The Carmen Cloud API – usage, events, storage & hooks and the common error model​

Real-world systems rarely operate as isolated components. Webhooks, entitlement metadata, licensing, and error handling become just as important as the recognition itself.

The Carmen Cloud API ties everything together, ensuring that events flow correctly and the system remains observable and maintainable at scale. Authenticate by exchanging your API key for a short-lived bearer token — see the Authentication reference.

These APIs complement the recognition engines and data-collection components, and they provide the operational glue that holds full deployments together.

Usage statistics​

The Carmen Cloud API exposes recognition call statistics per workspace and per API key:

  • total workspace usage,
  • daily totals,
  • product and API breakdowns.

The date range contract uses ISO date parameters, from and to. See the Carmen Cloud API reference and the Dashboard usage guide. Workspace management itself (workspaces, users, invitations, API keys) is done in the Cloud Dashboard or programmatically via the Carmen Cloud API.

Storage settings​

Temporary event storage is managed through the Carmen Cloud API:

  • enabling storage per workspace and product,
  • listing stored events,
  • filtering events by API key,
  • exposing generated links for stored event attachments.

See the Carmen Cloud API reference and the Storage & Hooks Dashboard guide.

Events​

The Carmen Cloud API provides event browsing and retrieval:

  • stored event lists per API,
  • event details and attachment links,
  • pagination and time-range filtering.

See the Carmen Cloud API reference.

Hooks​

Hooks deliver asynchronous webhook notifications with retry logic and delivery status tracking. They allow event-driven systems to receive recognition results without polling.

Hook setup is documented in the Storage & Hooks Dashboard guide and the hook tutorials; hooks can also be managed programmatically via the Carmen Cloud API.

Common error model​

All Carmen Cloud APIs follow a consistent error schema:

  • machine-readable error code,
  • human-readable message,
  • optional structured details.

10. Cloud vs On-Prem vs Hybrid – choosing the right deployment model​

The beauty of Carmen Cloud is that you don't have to choose a single path and commit forever. Many deployments start in the cloud, later add Carmen Workers for specific lanes, and eventually become fully hybrid. Because everything speaks the same JSON, migration paths are smooth – your architecture can evolve without rewriting the entire system.

Carmen Cloud supports three deployment models.

Cloud-first deployment​

Call the cloud Vehicle and Transport APIs directly.

Use this when:

  • minimal operations overhead is required,
  • automatic scaling is preferred,
  • cloud-based quotas/dashboards are needed,
  • sending images to the cloud is acceptable.

On-prem-first deployment​

Run Carmen Worker (and optionally Vehicle Detector) locally.

Use this when:

  • privacy or regulation requires local processing,
  • networks are air-gapped,
  • ultra-low latency is needed,
  • offline operation is required.

Hybrid deployment​

Combine:

  • Vehicle Detector (streams),
  • Carmen Worker (on-prem),
  • Cloud APIs,
  • Carmen Mobile as an additional image source.

Examples:

  • Vehicle Detector → Carmen Worker for sensitive lanes
  • Vehicle Detector → Carmen Cloud where bandwidth allows
  • Carmen Mobile → Vehicle API/Carmen Worker for field operations
  • Carmen Worker fallback when cloud is temporarily unavailable

Because the JSON schema is uniform, hybrid routing is configuration rather than code branching.

11. The full Carmen Cloud ecosystem at a glance​

At first glance the ecosystem diagram looks simple, but it captures a critical advantage: every component is interchangeable. Cameras, Carmen Mobile, Vehicle Detector, Carmen Worker, Carmen Cloud APIs – all can be connected in different combinations depending on the project's needs.

This modularity is what makes Carmen Cloud suitable for both small integrators and nationwide tolling authorities.

Below is a simplified representation of how image sources flow into recognition:

Camera(s)
   │
   ├── Vehicle Detector (optional)
   │       │
   │       └── crops → Carmen Worker or Carmen Cloud
   │
Carmen Mobile
   │
   └── frames/crops → Carmen Worker or Carmen Cloud

Carmen Cloud APIs
   ├── Vehicle API
   ├── Transport API
   ├── PR API
   └── Carmen Cloud API
   │
   └── results → Webhooks / Event Bus / Storage → Your Application

Image sources include:

  • fixed cameras,
  • video streams via Vehicle Detector,
  • mobile devices via Carmen Mobile,
  • still images from any source.

This architecture supports cloud-native, on-premise, hybrid, and multi-site deployments.

12. Quick decision guide – which component do I need?​

Even experienced integrators sometimes ask, "Which component should I start with?" This guide exists exactly for that reason: to make the first architectural choice obvious, even if the project is complex.

Most workflows become clear once you map them to a single decision: is the image coming from a camera, a stream, a mobile device, or a backend system?

  • You have images of road vehicles → Vehicle API
  • You have containers, wagons, trailers → Transport API
  • You need ID document checks → PR API
  • You must run offline or on-site → Carmen Worker
  • You have video streams → Vehicle Detector
  • You need mobile/field data capture → Carmen Mobile
  • You need to manage workspaces, users, subscriptions and API keys → Cloud Dashboard
  • You want event-driven backends → Carmen Cloud API + Hooks
  • You need usage statistics or workspace operations → Carmen Cloud API
  • You want a unified, subscription-based licensing backend for engines and SDKs → License Service

13. Why this structure matters for integrators​

Large-scale recognition projects rarely fail because the engines are inaccurate – they fail because the architecture becomes fragmented.

By offering cloud, on-prem, and mobile components under a single umbrella, Carmen Cloud ensures that teams don't have to reinvent transport layers, authentication flows, or event distribution.

Everything fits together by design, so architects can focus on delivering value rather than stitching components manually. By keeping request and response formats unified across all engines and deployments, Carmen Cloud:

  • reduces engineering effort,
  • simplifies client code,
  • allows dynamic routing between cloud and on-prem,
  • scales from single devices to multi-site footprints,
  • enables clean, modern hybrid architectures.

Carmen Cloud is not a single API – it is a fully integrated family of interoperable recognition engines, mobile tools, and utility services designed for tolling, logistics, security, smart cities, and industrial automation.