---
title: "Image classification"
canonical: https://docs.qvac.tether.io/sdk/v0.23/ai-capabilities/image-classification/
collection: "SDK"
package: "@qvac/sdk"
line: v0.23
current_line: false
---

# Image classification (/sdk/v0.23/ai-capabilities/image-classification)



## Overview

Image classification uses a **GGML** inference engine ([`@qvac/classification-ggml`](https://github.com/tetherto/qvac/tree/main/packages/classification-ggml)). Load a model using `modelType: "classification"` and a `modelSrc`. The `MOBILENETV3_3CLASS_V3_FP16` constant is a MobileNetV3-Small that classifies images into three labels: `"food"`, `"report"`, and `"other"`. Custom GGUF classifiers are supported by passing your own `modelSrc`.

Provide an image to `classify()` as a `Uint8Array` of either:

* an encoded **JPEG or PNG** buffer; or
* **raw RGB** bytes, alongside `width`, `height`, and `channels: 3`.

`classify()` returns `ClassificationResult[]` — an array of `{ label, confidence }` entries sorted by confidence in descending order. Use `topK` to limit the number of results returned, either as a load-time default (`modelConfig.topK`) or as a per-call override.

## Functions

Use the following sequence of function calls:

1. [`loadModel()`](/sdk/v0.23/reference/api#loadmodel)
2. [`classify()`](/sdk/v0.23/reference/api#classify)
3. [`unloadModel()`](/sdk/v0.23/reference/api#unloadmodel)

For how to use each function, see [SDK — API reference](/sdk/v0.23/reference/api/).

## Models

Supported model families and their file layouts:

* **MobileNetV3-Small**: single all-in-one `*.gguf` file — the base model or any fine-tune of the same architecture (converted to GGUF). Fine-tunes may define their own classes and labels; the label set is sourced from the GGUF metadata.

For models available as constants, see [SDK — Models](/sdk/v0.23/#models).

## Example

The following script classifies a JPEG image with the `MOBILENETV3_3CLASS_V3_FP16` model. Pass the path of a JPEG or PNG image as the first argument:

<Tabs>
  <Tab value="js" label="JavaScript" default>
    <WrapCode>
      ```js file=<rootDir>/packages/sdk/dist/examples/classification/classify-image.js title="classify-image.js" lineNumbers
      import fs from 'fs';
      import { loadModel, classify, unloadModel, MOBILENETV3_3CLASS_V3_FP16 } from '@qvac/sdk';
      /**
       * Classify an image with MobileNetV3-Small, which produces three classes:
       * "food", "report", "other".
       *
       * Usage: npx tsx examples/classification/classify-image.ts <image-path>
       */
      async function main() {
          const imagePath = process.argv[2];
          if (!imagePath) {
              console.error('Usage: npx tsx examples/classification/classify-image.ts <image-path>');
              process.exit(1);
          }
          const modelId = await loadModel({
              modelSrc: MOBILENETV3_3CLASS_V3_FP16,
              modelType: 'ggml-classification'
          });
          const image = fs.readFileSync(imagePath);
          const results = await classify({ modelId, image });
          console.log('Classification results:');
          for (const { label, confidence } of results) {
              console.log(`  ${label}: ${(confidence * 100).toFixed(1)}%`);
          }
          await unloadModel({ modelId });
      }
      main().catch(console.error);
      ```
    </WrapCode>
  </Tab>

  <Tab value="ts" label="TypeScript">
    <WrapCode>
      ```ts file=<rootDir>/packages/sdk/examples/classification/classify-image.ts title="classify-image.ts" lineNumbers
      import fs from 'fs'
      import { loadModel, classify, unloadModel, MOBILENETV3_3CLASS_V3_FP16 } from '@qvac/sdk'

      /**
       * Classify an image with MobileNetV3-Small, which produces three classes:
       * "food", "report", "other".
       *
       * Usage: npx tsx examples/classification/classify-image.ts <image-path>
       */
      async function main() {
        const imagePath = process.argv[2]
        if (!imagePath) {
          console.error('Usage: npx tsx examples/classification/classify-image.ts <image-path>')
          process.exit(1)
        }

        const modelId = await loadModel({
          modelSrc: MOBILENETV3_3CLASS_V3_FP16,
          modelType: 'ggml-classification'
        })

        const image = fs.readFileSync(imagePath)
        const results = await classify({ modelId, image })

        console.log('Classification results:')
        for (const { label, confidence } of results) {
          console.log(`  ${label}: ${(confidence * 100).toFixed(1)}%`)
        }

        await unloadModel({ modelId })
      }

      main().catch(console.error)
      ```
    </WrapCode>
  </Tab>

  <Tab value="python" label="Python">
    <WrapCode>
      ```python file=<rootDir>/packages/sdk-python/examples/classify_image.py title="classify_image.py" lineNumbers
      """Python port of packages/sdk/examples/classification/classify-image.ts.

      Classify an image with MobileNetV3-Small, which produces three classes:
      "food", "report", "other".

      JS's `classify` base64-encodes the image and returns the results; Python calls
      the generated stub, so the request carries the base64 image and the results
      are read off the final frame.

      RUN: python examples/classify_image.py <image-path>
      """

      from __future__ import annotations

      import asyncio
      import base64
      import sys
      from pathlib import Path

      from tetherto.qvac_sdk import (
          ClassifyRequest,
          Client,
          classify,
          load_model,
          unload_model,
      )
      from tetherto.qvac_sdk.models import MOBILENETV3_3CLASS_V3_FP16


      async def main() -> int:
          if len(sys.argv) < 2:
              print("Usage: python examples/classify_image.py <image-path>", file=sys.stderr)
              return 1

          image_path = sys.argv[1]

          async with Client() as client:
              t = client.transport
              try:
                  model_id = await load_model(
                      t,
                      model_src=MOBILENETV3_3CLASS_V3_FP16,
                      model_type="ggml-classification",
                  )

                  image = Path(image_path).read_bytes()
                  request = ClassifyRequest.model_validate(
                      {
                          "type": "classify",
                          "modelId": model_id,
                          "image": base64.b64encode(image).decode("ascii"),
                      }
                  )

                  results = []
                  async for response in classify(t, request):
                      if response.done:
                          results = response.results

                  print("Classification results:")
                  for result in results:
                      print(f"  {result.label}: {result.confidence * 100:.1f}%")

                  await unload_model(t, model_id)
              except Exception as error:
                  print(f"✖ {error}", file=sys.stderr)
                  return 1
          return 0


      if __name__ == "__main__":
          sys.exit(asyncio.run(main()))
      ```
    </WrapCode>
  </Tab>

  <Tab value="kotlin" label="Kotlin">
    <WrapCode>
      ```kotlin file=<rootDir>/packages/sdk-kotlin/examples/src/ClassifyImage.kt title="ClassifyImage.kt" lineNumbers
      // Kotlin port of packages/sdk/examples/classification/classify-image.ts.
      //
      // Classify an image with MobileNetV3-Small, which produces three classes:
      // "food", "report", "other".
      //
      // The load uses the typed `GgmlClassification` arm of the generated
      // `LoadModelRequest` union, which fixes `modelType` to "ggml-classification";
      // `modelSrc` is the registry source of `Models.MOBILENETV3_3CLASS_V3_FP16`.
      // `client.vision.classify()`
      // takes the image as base64, so the example encodes the file with
      // `java.util.Base64`, and returns the collected results.
      //
      // RUN: ./gradlew -p examples run -Pexample=ClassifyImage --args="<image-path>"

      import io.tether.qvac.sdk.QvacClient
      import io.tether.qvac.sdk.generated.Models
      import io.tether.qvac.sdk.generated.schema.LoadModelRequest
      import io.tether.qvac.sdk.generated.schema.LoadModelSrcRequest
      import io.tether.qvac.sdk.generated.schema.LoadModelSrcRequestGgmlClassification
      import io.tether.qvac.sdk.jvm.JvmBareKitTransport
      import io.tether.qvac.sdk.models
      import io.tether.qvac.sdk.vision
      import java.nio.file.Files
      import java.nio.file.Path
      import java.util.Base64
      import kotlin.system.exitProcess
      import kotlinx.coroutines.runBlocking

      fun main(args: Array<String>): Unit = runBlocking {
          if (args.isEmpty()) {
              System.err.println("Usage: ./gradlew -p examples run -Pexample=ClassifyImage --args=\"<image-path>\"")
              exitProcess(1)
          }

          val imagePath = args[0]

          val client = QvacClient(JvmBareKitTransport.connect())
          try {
              val loaded = client.models.load(
                  LoadModelRequest.LoadModelSrcRequest(
                      LoadModelSrcRequest.GgmlClassification(
                          LoadModelSrcRequestGgmlClassification(modelSrc = Models.MOBILENETV3_3CLASS_V3_FP16.src),
                      ),
                  ),
              )
              val modelId = loaded.modelId ?: error(loaded.error ?: "loadModel failed")

              val image = Files.readAllBytes(Path.of(imagePath))
              val results = client.vision.classify(modelId, Base64.getEncoder().encodeToString(image))

              println("Classification results:")
              for (result in results) {
                  println("  ${result.label}: ${"%.1f".format(result.confidence * 100)}%")
              }

              client.models.unload(modelId)
          } finally {
              client.close()
          }
      }
      ```
    </WrapCode>
  </Tab>
</Tabs>

<Callout type="success">
  **Tip:** all examples throughout this documentation are self-contained and runnable. For instructions on how to run them, see the [JS/TS quickstart](/sdk/v0.23/js-ts-sdk#quickstart), the [Python quickstart](/sdk/v0.23/python-sdk#quickstart), or the [Kotlin quickstart](/sdk/v0.23/kotlin-sdk#quickstart).
</Callout>
