C+ API reference

The native Config, Session, Frame, Input, and Output API.

import "ffi/api" as slab;

All objects are created with ::new() and free themselves at the end of their scope. Functions returning bool return false on failure; the reason is on the object (error_code(), error_message()).

Returned str values (names, labels, text, messages) borrow the object that returned them. They stay valid until that object's next mutating call or until it is freed. Read other values from the object before taking the string, and call .to_text() to keep a copy.

Functions

Function	Returns
`slab::version() -> str`	Runtime version, e.g. `0.1.0-ea.1`
`slab::backend_name(backend: i32) -> str`	`"CPU"`, `"GPU"`, `"NPU"`, `"AUTO"` or `"NONE"`

Constants

Group	Constants
Backend	`BACKEND_AUTO` 0, `BACKEND_CPU` 1, `BACKEND_GPU` 2, `BACKEND_NPU` 3 (`BACKEND_NE` = 3)
Data type	`DTYPE_F16` 1, `DTYPE_F32` 2, `DTYPE_I64` 3, `DTYPE_U8` 5
Pixel format	`PIXEL_RGB8` 1, `PIXEL_BGR8` 2, `PIXEL_RGBA8` 3, `PIXEL_BGRA8` 4, `PIXEL_GRAY8` 5
Resize	`RESIZE_STRETCH` 0, `RESIZE_LETTERBOX` 1, `RESIZE_CENTER_CROP` 2
Finish reason	`FINISH_NONE` 0, `FINISH_EOS` 1, `FINISH_STOP` 2, `FINISH_LENGTH` 3, `FINISH_CANCELLED` 4
Error	`OK` 0, `ERR_INVALID_ARG` 1, `ERR_IO` 2, `ERR_MODEL_INVALID` 3, `ERR_IMAGE_UNREAD` 4, `ERR_IMAGE_UNSUP` 5, `ERR_CTX_OVERFLOW` 6, `ERR_OUT_OF_MEMORY` 7, `ERR_GPU_UNAVAILABLE` 8, `ERR_BUSY` 9, `ERR_CANCELLED` 10, `ERR_NUMERICAL` 11, `ERR_UNSUPPORTED` 12, `ERR_VERIFY` 13, `ERR_INTERNAL` 14, `ERR_LICENSE` 15 (protected model), `ERR_RUNTIME_LICENSE` 16

Config

App-wide settings. A Session copies them when it is created, so later changes to the Config affect only new sessions.

Method	Description
`new() -> Config`	Create with defaults
`set_models_dir(path: str)`	Folder that relative model paths resolve against
`set_cache_dir(path: str)`	Writable folder for prepared-model caches
`set_skel_dir(path: str)`	Android Hexagon NPU: writable folder holding the QNN skel libraries
`set_backend(backend: i32)`	Default backend for new sessions (default `BACKEND_AUTO`)
`set_threads(threads: i32)`	CPU worker threads
`set_verify_weights(verify: bool)`	Hash-check all weights on open (slower open)
`probe_backend(backend: i32) -> bool`	Whether this device has that backend

Runtime license

Method	Description
`set_runtime_license(token: str) -> bool`	Verify and attach the license string. On failure, any previous license stays.
`set_runtime_license_bytes(bytes: *u8, length: usize) -> bool`	Same, for the 640-byte binary form
`clear_runtime_license()`	Detach; new sessions from this Config are unlicensed
`runtime_license_status() -> i32`	The attached license now: 0 OK, 1 missing, 10 not yet valid, 11 expired, 15 clock unavailable
`runtime_license_error() -> i32`	Reason the last license call failed (codes below)
`runtime_license_error_message() -> str`	Same, as text
`runtime_license_expires_at() -> u64`	Expiry, Unix seconds (0 if none)
`runtime_license_integrator_id() -> str`	Licensed integrator ID (hex)
`runtime_license_client_id() -> str`	Licensed client ID (hex)

License reason codes: 0 OK, 1 missing, 2 format, 3 issuer, 4 signature, 5 platform, 6 identity unavailable, 7 identity mismatch (wrong app), 8 release, 9 feature, 10 not yet valid, 11 expired, 12 memory, 13 invalid argument, 14 busy, 15 clock unavailable.

Protected models

Method	Description
`set_unlock_key(key32: *u8, key_id: u64) -> bool`	Install the 32-byte model key directly
`set_unlock_key_hex(hex64: str, key_id: u64) -> bool`	Same, as 64 hex characters
`set_issuer_public_key(pubkey65: *u8, app_id: u64) -> bool`	Trust a model-token issuer key
`set_license_token(token: str) -> bool`	Unlock with a model token checked on the device
`clear_unlock_key()`	Remove the installed key. Keys are process-wide; clear before installing a different one.

Frame

A decoded image. Immutable once loaded, so it can be shared by sessions on different threads.

Method	Description
`new() -> Frame`	Empty frame
`load_file(path: str) -> bool`	Decode a JPEG or PNG file
`load_encoded(bytes: *u8, len: usize) -> bool`	Decode JPEG or PNG bytes in memory
`set_pixels(data: *u8, length: usize, width: u32, height: u32, stride: usize, format: i32, orientation: u32, copy: bool) -> bool`	Use raw pixels, e.g. a camera frame. `stride` 0 means tightly packed. `orientation` is EXIF 1–8 (0 = upright). `copy = false` borrows `data`: keep it valid until every `run` or `start` using this frame (or a crop of it) has returned.
`crop_into(ref dst: Frame, x: i32, y: i32, w: i32, h: i32) -> bool`	Make `dst` a view of a region, without copying pixels
`width() -> u32`, `height() -> u32`	Size in pixels
`format() -> i32`	Pixel format
`stride() -> usize`	Bytes per row
`data_ptr() -> *u8`	Pixel data
`error_code() -> i32`, `error_message() -> str`	Last error

Session

One model. One operation at a time per session; separate sessions run in parallel.

Lifecycle

Method	Description
`new(ref cfg: Config) -> Session`	Create from a Config (copies its settings and license)
`inspect(path: str) -> bool`	Read the model's description without loading weights
`inspect_fd(fd: i32, base_offset: u64, length: u64) -> bool`	Same, from an open file region (e.g. inside an app bundle)
`check_backend(backend: i32) -> bool`	Dry run: can this backend run the inspected model? On `false`, the message names the unsupported operations or the memory limit
`estimated_memory_bytes() -> usize`	Memory the model needs
`open(path: str) -> bool`	Load the model and prepare it on a backend
`open_fd(fd: i32, base_offset: u64, length: u64) -> bool`	Same, from an open file region
`unload() -> bool`	Free the weights, keep the session and its settings
`reload() -> bool`	Load the weights again after `unload`
`active_backend() -> i32`	Backend the model runs on
`is_protected() -> bool`	Whether the model is encrypted
`is_generative() -> bool`	Whether it is a text-generation model

Settings (before `open`)

Method	Description
`set_backend(backend: i32)`	Request a backend. AUTO uses the model's preference, else NPU → GPU → CPU. An explicit request either succeeds or fails with a reason.
`set_warmup(warmup: bool)`	Run once during `open` so the first real run is fast
`set_batch_size(batch_size: i32)`	Images per run, within the model's supported range
`set_context_length(context_length: i32)`	Generative models: maximum tokens in the conversation
`set_activation_fp16(fp16: bool)`	Generative models: 16-bit activations

Image preprocessing (before or after `open`)

Defaults come from the model file. Calling one of these overrides it.

Method	Description
`set_resize_mode(mode: i32)`	`RESIZE_STRETCH`, `RESIZE_LETTERBOX` or `RESIZE_CENTER_CROP`
`set_letterbox_pad(pad_value: u8)`	Padding byte for letterboxing (default 114)
`set_color_bgr(bgr: bool)`	Feed BGR instead of RGB
`set_normalization(scale: f32, m0: f32, m1: f32, m2: f32, s0: f32, s1: f32, s2: f32)`	`value = (pixel * scale - mean) / std` per channel

Running

Method	Description
`run(ref inp: Input, ref out: Output) -> bool`	Run the model once. For a generative model, produces the whole answer.
`start(ref inp: Input, ref out: Output) -> bool`	Generative: read the prompt and begin an answer
`next_token(ref out: Output) -> i32`	Generative: produce the next piece of text. 1 = text in `out.text()`, 0 = finished, -1 = error
`cancel()`	Stop the current run or generation; safe from any thread
`reset() -> bool`	Generative: forget the conversation

Model description

Method	Description
`input_count() -> i32`, `output_count() -> i32`	Number of inputs and outputs
`input_name(idx: i32) -> str`, `output_name(idx: i32) -> str`	Tensor names
`input_dtype(idx: i32) -> i32`, `output_dtype(idx: i32) -> i32`	Data types
`input_dim(idx: i32, axis: i32) -> i64`, `output_dim(idx: i32, axis: i32) -> i64`	Dimension size; 0 past the last axis
`label_count() -> i32`, `label(class_idx: i32) -> str`	Class labels from the model file
`has_meta(key: str) -> bool`	Whether the model file has a setting
`meta_str(key: str) -> str`, `meta_i64(key: str) -> i64`, `meta_f64(key: str) -> f64`	Read a model file setting

Runtime license on a live session

Method	Description
`set_runtime_license(token: str) -> bool`	Renew this session's license without reloading the model. Must be the same integrator, client and app. Fails with "busy" during a run; retry after it.
`set_runtime_license_bytes(bytes: *u8, length: usize) -> bool`	Same, binary form
`runtime_license_status() -> i32`	As on Config
`runtime_license_error() -> i32`, `runtime_license_error_message() -> str`	As on Config
`runtime_license_expires_at() -> u64`	As on Config

Errors

Method	Description
`error_code() -> i32`	Last error (`ERR_*`)
`error_message() -> str`	Last error, as text

Input

Reusable. Call clear() before giving it different data. Each thread uses its own Input.

Images and tensors

Method	Description
`clear()`	Remove everything
`set_frame(ref f: Frame)`	Image for the model's first input
`set_named_frame(name: str, ref f: Frame)`	Image for a named input
`add_batch_frame(ref f: Frame) -> bool`	Add one image to a batch (up to 64)
`set_f32(idx: i32, data: *f32, elem_count: usize, copy: bool) -> bool`	Tensor for input `idx`
`set_named_f32(name: str, data: *f32, elem_count: usize, copy: bool) -> bool`	Tensor for a named input
`set_i64` / `set_named_i64`	Same, `*i64`
`set_f16` / `set_named_f16`	Same, `*u16` holding binary16 values
`set_u8` / `set_named_u8`	Same, `*u8`

With copy = false, Slab reads the buffer only during run or start; it may be reused or freed once they return.

Prompts (generative models)

Method	Description
`set_prompt(prompt: str)`	A single user message
`add_message(role: str, text: str) -> bool`	Add a `"system"`, `"user"` or `"assistant"` message (up to 16)
`add_image_message(role: str, ref f: Frame, text: str) -> bool`	Add a message with an image
`set_image_tiled(tiled: bool, longest_edge: u32)`	Split large images into tiles; `longest_edge` 512–2048
`set_max_tokens(max_new_tokens: i32)`	Answer length limit
`set_temperature(temperature: f32)`	0 = always the most likely token
`set_top_p(top_p: f32)`, `set_top_k(top_k: i32)`, `set_min_p(min_p: f32)`	Sampling limits
`set_repeat_penalty(penalty: f32)`	Discourage repetition
`set_seed(seed: u64)`	Repeatable sampling
`add_stop(stop: str) -> bool`	Stop when this text is produced
`set_json_schema(schema: str)`	Constrain the answer to JSON matching the schema
`set_amount_decimals(decimals: i32)`	Constrain the answer to a decimal amount with 1–9 decimals (0 = off)

Output

Reusable. Everything it returns stays valid until the next run, start or next_token into it, or until it is freed, even if the session is freed first. Each thread uses its own Output.

General

Method	Description
`latency_ms() -> f64`	Duration of the last run
`backend_used() -> i32`	Backend that ran it
`tensor_count() -> i32`	Number of output tensors
`f32_ptr(idx: i32) -> *f32`, `f32_len(idx: i32) -> usize`	Output tensor values
`scale_x() -> f32`, `scale_y() -> f32`, `pad_x() -> f32`, `pad_y() -> f32`	How the input image was fitted (for your own coordinate mapping)

Classification

Method	Description
`compute_top_k(tensor_idx: i32, k: i32, apply_softmax: bool) -> i32`	Rank the top `k` classes; returns how many
`top_class_id(rank: i32) -> i32`	Class index at a rank
`top_score(rank: i32) -> f32`	Score at a rank
`top_label(rank: i32) -> str`	Label at a rank ("" if the model has no labels)

Detection

Method	Description
`decode_boxes(score_threshold: f32, iou_threshold: f32, max_boxes: i32) -> i32`	Decode boxes, remove overlaps, map to the original image. Returns the count, or -1 if the model's output is not a supported detection layout (reason on the session).
`box_x1(i)`, `box_y1(i)`, `box_x2(i)`, `box_y2(i)` -> `f32`	Box corners in original image pixels
`box_score(i) -> f32`, `box_class_id(i) -> i32`, `box_label(i) -> str`	Score and class
`box_landmark_count(i) -> i32`, `box_landmark_x(i, pt) -> f32`, `box_landmark_y(i, pt) -> f32`	Keypoints, in original image pixels

Embeddings and images

Method	Description
`normalize_l2(tensor_idx: i32) -> bool`	Scale a tensor to unit length, in place
`cosine_similarity(idx_a: i32, ref other: Output, idx_b: i32) -> f32`	Similarity between two outputs' tensors
`to_frame(tensor_idx: i32, scale: f32, offset: f32, ref dst: Frame) -> bool`	Turn an image-shaped tensor into a Frame: `pixel = value * scale + offset`, clamped to 0–255

Text (generative models)

Method	Description
`text() -> str`	Text produced by the last `next_token`
`full_text() -> str`	The whole answer so far
`finish_reason() -> i32`	Why it stopped (`FINISH_*`)
`prompt_tokens() -> i32`	Tokens in the prompt
`cached_prompt_tokens() -> i32`	Prompt tokens reused from the previous turn
`generated_tokens() -> i32`	Tokens generated