Getting Started with Python

info

This doc refers to the Python client library for integrating Ikomia SCALE deployments. This is not to be confused with Ikomia Python API that allows you to define workflows and run them on your machine.

Installation

pip install ikomia-client

Instantiating the client

from ikclient.core.client import Client

with Client(
    url="https://your.scale.endpoint.url",
    token="your-api-token",  # Or use the environment variable IKOMIA_TOKEN
) as flux_deployment:
    results = flux_deployment.run(parameters={"prompt": "A cat sitting on a mat"})

warning

We strongly recommend avoiding exposing your personal token in your code. One option is to set the environment variable IKOMIA_TOKEN to avoid passing it explicitly.

Async support

We also provide an async version of the client with the same features:

import asyncio
from ikclient.core.client import AsyncClient

async def main():
    async with AsyncClient(url="https://your.scale.endpoint.url") as flux_deployment:
        results = await flux_deployment.run(parameters={"prompt": "A cat sitting on a mat"})

asyncio.run(main())

Running deployment

For deployment of straightforward workflows, you can simply call Client.run() optionally passing inputs and parameters.

with Client(url="https://your.scale.endpoint.url") as client:
    results = client.run("path/to/image.jpg", parameters={"model_name": "yolov8m"})

We use fsspec for parsing paths, so you can pass local file paths, URLs, S3 URIs, and more.

If your deployment takes multiple inputs, you can just pass multiple paths directly:

results = client.run(
    "path/to/image1.jpg",
    "path/to/image2.jpg",
)

Because we rely on the path file extension to determine the input type, you may encounter CannotInferPathDataTypeException if the path has no extension or an unrecognized extension. You can use Client.create_input() to explicitly define the input type:

input1 = client.create_input("https://this.is.an.image.url/without-extension", data_type="image")
input2 = client.create_input("s3://bucket/video-object", data_type="video")

results = client.run(input1, input2)

The Results object contains the output of your deployment. The number of outputs, their type and values depends on the deployment you are running and the inputs and parameters you provided.

By default, the results will contains all outputs returned by the first leaf task in your workflow. In the common use case where your workflow is a simple chain of algorithms (or just one), this will correspond to the outputs of the last algorithm of the chain.

Tracking progress

You can track the progress of your deployment using the on_progress callback:

results = client.run(
    "https://raw.githubusercontent.com/Ikomia-dev/notebooks/main/examples/img/img_work.jpg",
    parameters={"model_name": "yolov8m"},
    on_progress=lambda **kwargs: print(f"Progress: {kwargs}")
)

# Progress: {"run_id": "v4d4mg96bu", "name": "Object Detection Workflow", "uuid": "c0315bef-3642-44ba-9e94-5749881fc297", "state": "PENDING", "eta": [1000, 2000]}
# ...
# Progress: {"run_id": "v4d4mg96bu", "name": "Object Detection Workflow", "uuid": "c0315bef-3642-44ba-9e94-5749881fc297", "state": "SUCCESS", "eta": [0, 0], "results": Results(...)}

This callback will be called repeatedly during the polling process of the deployment. It can be useful for logging or updating UIs while the deployment runs.

Accessing the results

Once the deployment is complete, you can retrieve output data through the Results.get_output() method:

from ikclient.core.io import ImageIO

first_output = results.get_output()  # shortcut for results.get_output(0)
output_image = results.get_output(1, assert_type=ImageIO)

The assert_type parameter is optional, but we recommend using it when you know the expected type of the output. During development, it will provide better type hints in your editor and during runtime, it will raise an exception if the output is not of the expected type.

We provide the following standard types:

• ImageIO: for image outputs
• StorageObjectIO: for outputs saved to your Project's storage

Other output types (e.g. object detection, segmentation, ocr, non-standard outputs, etc.) will be returned as the generic TaskIO.

Image outputs

We provide some utility methods for working with image outputs:

output_image = results.get_output(1, assert_type=ImageIO)

image_pil = output_image.to_pil()  # convert to PIL image
image_array = output_image.to_numpy()  # convert to numpy array
image_bytes = output_image.to_bytes()  # get raw bytes