# 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](https://ikomia-dev.github.io/python-api-documentation/index.html) that allows you to define workflows and run them on your machine.

## Installation[​](#installation "Direct link to Installation")

```
pip install ikomia-client
```

## Instantiating the client[​](#instantiating-the-client "Direct link to 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[​](#async-support "Direct link to 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[​](#running-deployment "Direct link to 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`](https://filesystem-spec.readthedocs.io/en/latest/) 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[​](#tracking-progress "Direct link to 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[​](#accessing-the-results "Direct link to 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[​](#image-outputs "Direct link to 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
```