Skip to main content

Getting started

Instantiating the client​

First, instantiate a client with the URL of your deployment and your personal token:

import {Client} from "@ikomia/ikclient";

const client = new Client({
  url: "https://your.scale.endpoint.url",
  // token: "your-api-token", default to process.env.IKOMIA_TOKEN
});

...
warning

We strongly recommend avoiding exposing your personal token in your code. You can set IKOMIA_TOKEN as an environment variable to avoid passing it explicitly.


Running deployment​

To run your deployment, simply call Client#run optionally passing input image(s) and parameters, and await the results:

const results = await client.run({
  image: "https://raw.githubusercontent.com/Ikomia-dev/notebooks/main/examples/img/img_work.jpg"
});

Use the image attribute to pass an input image to your deployment. You can pass an URL, a base64 encoded string, a Buffer, an ArrayBuffer, a Uint8Array or a Blob.

If your deployment takes multiple images as inputs, use the images attribute instead of image and pass an array of input images.

const results = await client.run({
  images: [
    "https://raw.githubusercontent.com/Ikomia-dev/notebooks/main/examples/img/img_work.jpg",
    "https://raw.githubusercontent.com/Ikomia-dev/notebooks/main/examples/img/img_starry_night.jpg"
  ]
});

The Results object contains the output of your deployment. The number, type and value of your outputs depend on the deployment you are running, its settings and the inputs you provided.

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

If you want to run another task in your workflow, you can specify the taskName attribute in the Client#run method:

const results = await client.run({
  taskName: "infer_yolo_v10",
  image: "https://raw.githubusercontent.com/Ikomia-dev/notebooks/main/examples/img/img_work.jpg"
});

You can also set parameters for the output task using the parameters attribute:

const results = await client.run({
  taskName: "infer_mobile_segment_anything", // Default to the first leaf task
  image: "https://raw.githubusercontent.com/Ikomia-dev/notebooks/main/examples/img/img_work.jpg",
  parameters: {
   iou_thres: 0.88,
   cuda: true
  }
});

Tracking progress​

You can track the progress of your deployment by adding an onProgress callback:

const results = await client.run({
  image: "https://raw.githubusercontent.com/Ikomia-dev/notebooks/main/examples/img/img_work.jpg",
  onProgress: (progress) => {
    // {"runId": "v4d4mg96bu", "name": "EdgeDetection", "state": "PENDING", "uuid": "10591168-ba4b-4356-9d76-47de902a118e", "eta": [1000, 20000]}
    console.log(progress);
  }
});

This callback will be called multiple time during the polling process of the deployment. It passes an object containing the current state of the deployment execution and an interval of the estimated execution time in milliseconds (eta).

Accessing the results​

To access the results, you can use Results#getOutput method:

import {ImageIO, ObjectDetectionIO} from "@ikomia/ikclient/io";

const image = results.getOutput<ImageIO>(0);
// const image = results.getOutput(0); // If you don't use TypeScript

const objectDetection = results.getOutput<ObjectDetectionIO>(1);

The Results#getOutput method returns the output of the specified index.

If you are using TypeScript, you can pass a type argument to assert what type of output you expect to retrieve, which will help with autocompletion. We support the following standard types:

Non-standard types are returned as the base generic type TaskIO.

You can also use the Results#getOutputs method to get all outputs as an array:

const [image, objectDetection] = results.getOutputs<[ImageIO, ObjectDetectionIO]>();
// const [image, objectDetection] = results.getOutputs(); // If you don't use TypeScript