Ximilar Flows service provides a way for connecting individual custom recognition (and detection in near future) task/models into one API endpoint. With this service you can build more complex solutions in which you can aggregate result from multiple task/models or connect models with conditional dependencies/branches. In other words you can build powerful hierachical machine learning system on a few clicks!

Building flow is easy ...

For building flow, we provide easy to use user interface for simple connecting your tasks into a Flow. After creating definition of flow you can call the prediction endpoint /v2/process. For newcomers, you can read our introduction blog post about flows.

Active the service in Ximilar App

In order to get access to the Flows service, please register at https://app.ximilar.com and then click on this Service on the main panel to make it accessible for your Ximilar account.

Pricing ...

Creating a definition of flow through the frontend (app.ximilar.com) is free. If you call flow api processing endpoint (/v2/process) on your image then you pay for every service that is used in your flow. That means, if your flow contains three recognition tasks and all of them all called during the processing on the image then you will be billed for 3.0 api credits per image. One credit for each calling of recognition service (see pricing).

Building your flow

With flows you can build complex systems for industries, fashion, e-commerce, healthcare, real estate, ... Here are two simple use cases which will help you to start:

1. Use case example: Connect multiple models to one endpoint

Imagine that you are building simple real estate tagging system. You would like to identify room type, home features and condition. So first task is able to recognize type of room (Bedroom, Kitchen, Restroom, Living room, ...). Second task is recognizing home features present on the image (Wooden Floor, Fireplace, TV, ...). Third task is analyzing real estate condition (Good, Average, Poor.) We can connect them into one flow so we don't need to call three recognition endpoints but just one flow endpoint.


2. Use case example: Create hierachical classification

Imagine that we want to recognize type of fashion appareal on image (Pants vs Shirt). If we recognize Pants we would like to recognize also length of them (long, 3/4, short, ...) and material (Denim , ...). If we recognize Shirt we would like to recognize sleeves length, color and neckline type. We must create recognition tasks Pants Vs Shirt, Color, Pants Length, Sleeves Length, Neckline and Material before defining of our fashion flow. Then upload images and train all the tasks. Then we can connect all of them into the flow and build this powerful machine learning system on few clicks again. The first action is called branch selector which decides branch/path based if the image is pants or shirt:


Flow Action types

Every flow consists of one or several actions (or another nested flows):

  • Branch Selector Action: Contains Image Recognition Task, based on the result from the task (labels), go to most probable branch (defined by label) which is default behaviour. Another mode is processing all of the branches where the label probability is bigger than some user specified value.
  • List Action: performs list of action in sequence or parallel (default)
  • Recognition Action: Performs Image Recognition Task and ouput is stored to field specified by user.

Be aware that, if you delete any task from the branch selector your flow will become invalid and the processing endpoint will stop working!

API Endpoints



This is the main prediction endpoint of flow for your records.

To sum up /v2/process

  • Similar to recognition/v2/classify endpoint, this endpoit also process "records" with "_base64" or "_url"
  • You must specify ID of flow in 'flow' field
  • Number of records cannot exceed 10
  • If you specify valid value in field of your branch selection, then you can skip processing this branching decision process. For example in second use case you could specify for example fashion_category: 'Shirt' in your record and the proceessing of flow will be forced to process Shirt branch.
$ curl https://api.ximilar.com/flows/v2/process -H "Content-Type: application/json" -H "Authorization: Token __API_TOKEN__" -d '{
    "records": [
        { "_url": "__URL_IMAGE__" },
        {"_base64": "__BASE64_DATA__", "_id": "image_id"}
    "flow": "__FLOW_ID__"
from ximilar.client import FlowsClient

flow_client = FlowsClient(token="__API_TOKEN__")

flow = flow_client.get_flow("__FLOW_ID__")
result = flow.process([{"_file": "__PATH_TO_YOUR_IMAGE_LOCALY__"}])