ProcessFlow: Image thumbnails

ProcessFlow can crop and resize a raster image that already lives in tenant storage, then write a JPEG next to the rest of that tenant’s files. Use tf.image.thumbnail from step code. The step sandbox does not decode images itself. The platform reads the source, crops it, and writes the destination.

This is separate from text extraction. Use imageOcr when you need the words in a picture, and use tf.image.thumbnail when you need a smaller JPEG.

Call tf.image.thumbnail from a process step

The helper is on the injected image service, also available as tf.image. It requires the api capability, which is included in the platform default capability list. Both paths are tenant-relative. They must stay inside that tenant’s storage. Do not pass absolute paths, .., or another tenant’s files.

fit: "cover" center-crops the source to the requested aspect ratio, then resizes it to width × height. That is the setting to use for a fixed thumbnail such as 320×180 (16:9). contain and inside fit the whole image inside the box and pad with black. fill stretches to the exact pixel size.

Transparent pixels are flattened onto black before the JPEG is written. An animated GIF or animated WebP uses the first frame.

const thumb = await tf.image.thumbnail({
  source_path: "uploads/shot.png",
  dest_path: "CDN/video-reel/clip-thumb.jpg",
  width: 320,
  height: 180,
  fit: "cover",
  format: "jpeg",
  quality: 85
});

return {
  success: true,
  data: {
    thumbnail_path: thumb.path,
    width: thumb.width,
    height: thumb.height,
    bytes: thumb.bytes
  }
};

A failed call throws. Catch it and return your step’s usual error shape:

try {
  const thumb = await tf.image.thumbnail({
    source_path: sourcePath,
    dest_path: destPath,
    width: 320,
    height: 180,
    fit: "cover",
    quality: 85
  });
  return { success: true, data: thumb };
} catch (error) {
  const message = error && typeof error === "object" && "message" in error ? String(error.message) : "Thumbnail failed";
  return { success: false, error: { code: "THUMBNAIL_FAILED", message } };
}

Options

The return value is { path, width, height, bytes }. path is the destination path you asked for. width and height are the written JPEG size. bytes is the file size.

Run a thumbnail step through the ProcessFlow API

Call the process that contains the step. Pass the source path in input_data. You do not call the thumbnail helper over HTTP from your own application. The platform calls it while the step runs.

curl -X POST "https://<YOUR_DOMAIN>/api/v1/processflow?action=execute-process" \
  -H "X-API-Key: <API_KEY>" \
  -H "X-Tenant-ID: <TENANT_ID>" \
  -H "Content-Type: application/json" \
  -d '{
    "process_id": "<PROCESS_ID>",
    "input_data": {
      "source_path": "uploads/shot.png",
      "dest_path": "CDN/video-reel/clip-thumb.jpg"
    },
    "async": false
  }'

{
  "success": true,
  "data": {
    "execution_id": "<ENTITY_ID>",
    "status": "completed",
    "output": {
      "success": true,
      "data": {
        "thumbnail_path": "CDN/video-reel/clip-thumb.jpg",
        "width": 320,
        "height": 180,
        "bytes": 8421
      }
    }
  }
}

Limits and failures

SVG files are rejected, including an SVG renamed to .png. A path that leaves tenant storage is rejected. An empty file fails before a thumbnail is written.

If the call fails, check that the source exists in this tenant, the extension matches the file contents, and the step’s api capability is enabled.

See also

• ProcessFlow: Image OCR
• Process environment variables
• Process sandbox tf API reference