Image Loading¶

Introduction¶

The SDK supports creating script and applications to efficiently load large amounts of images from cloud or local directories into the VibeIQ platform.

This process encompasses the tasks of managing file uploads and linking these files to their corresponding Items in VibeIQ.

Covered Concepts¶

Authenticating using Contrail SDK or cURL
Uploading files with Contrail SDK or cURL.
Linking images to Items using Contrail SDK or cURL.

End Product of this Tutorial¶

Images will be uploaded platform as File entities.
Images will be assigned to Items via Content and will be visible on the item in VibeIQ applications.

Authentication¶

App Authentication

If your image load is running as part of an app action, you do not need to explicitly authenticate, and can skip this section. App actions are authorized automatically during runtime.

To authenticate with Contrail, you can use API key and organization slug.

image_load_script.ts

import { login } from "@contrail/sdk";
await login({ orgSlug: process.env.USER_ORG, apiKey: process.env.API_KEY });

Loading New Images¶

Images can be imported as files into the VibeIQ platform using the SDK method: Files.createAndUploadFileFromBuffer.

The example script assumes there is a subdirectory called images in the current directory the script is being run at, where all the image files are located. The contentType selected for these images is image/jpeg. Feel free to adapt these options to your needs.

image_load_script.ts

import {login, Files, Entities} from '@contrail/sdk';
import * as fs from "fs/promises"
import * as path from "node:path";

const pLimit = require('p-limit');
const limit = pLimit(10);

const loginCredentials = {
  orgSlug: process.env.USER_ORG,
  apiKey: process.env.API_KEY,
};

async function loadImages() {
  await login(loginCredentials);

  let fileUploadOperations = [];
  let contentToCreate = [];
  const contentType = "image/jpeg";
  const imagesToUpload = await fs.readdir('./images');

  for (const fileName of imagesToUpload) {
    const promise = limit(async () => {
      try {
        const arrayBuffer = await fs.readFile(`./images/${fileName}`);

        const imageBuffer = Buffer.from(new Uint8Array(arrayBuffer));
        const createdFile = await new Files().createAndUploadFileFromBuffer(
          imageBuffer,
          contentType,
          fileName,
          null,
          24 * 60 * 60 * 1000
        );

        contentToCreate.push({
          copyFileId: createdFile.id,
          contentType,
          fileName,
        })
      } catch (e) {
        console.log(
          `Failed to upload image`,
          e
        );
      }
    });
    fileUploadOperations.push(promise);
  }
  await Promise.all(fileUploadOperations);

Loading New Images Using cURL¶

Request Pre-Signed Information¶

First, request pre-signed information from the vibeIQ API. This information grants you temporary access to upload the image securely to an S3 bucket. Run the following cURL command to create the file and get the required pre-signed details:

curl -X POST "https://api.vibeiq.com/prod/api/files" \
  -H "x-api-key: $API_KEY" \
  -H "x-api-org: $USER_ORG" \
  -H "Content-Type: application/json" \
  -d '{
    "contentType": "image/jpeg",
    "fileName": "image",
    "ttl": 86400
  }'

When the request is successful, the API will return a response containing the following details:

File metadata (including fileKey and id).
A pre-signed S3 URL and upload form information (uploadPost). The uploadPost section contains the critical information you need to upload your image to the S3 bucket.
Other AWS-specific authorization fields.

{
  "contentType": "image/jpeg",
  "fileName": "image",
  "ttl": 86400,
  "fileKey": "0FYWOhu9p50/some-file-key/775d-8284-4c8d-b454-4509f9ebe92e",
  "fileBucket": "bucket-name",
  "fileUrl": "https://api.vibeiq.com/prod/api/files/downloadUrl/0FYWOhu9NMilc8d-b454-4509f9ebe92e",
  "createdOn": "2025-03-17T21:43:18.511Z",
  "updatedOn": "2025-03-17T21:43:18.511Z",
  "createdById": "9-4sss39qP",
  "updatedById": "9-4sunF4439qP",
  "orgId": "0FYWOhilep50",
  "id": "fkS4cOA25o5IX",
  "uploadPost": {
    "url": "https://s3.amazonaws.com/prod-contrail-file-content-bucket",
    "fields": {
      "key": "0FYWOhu9p50/some-file-key/775d-8284-4c8d-b454-4509f9ebe92e",
      "bucket": "prod-contrail-file-content-bucket",
      "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
      "X-Amz-Credential": "A0000000/17000/us-east-1/s3/aws4_request",
      "X-Amz-Date": "20250317T214318Z",
      "X-Amz-Security-Token": "IQoJbAIncgQjVi3some-security-code6G2dGuFFO/XolLglSgc+jNb0W4sF7rGvcWauKvqByjx4ob5yIAE4qAO7mSawTHKwIyy1Q==",
      "Policy": "eyJleHBpcmF0aW9uIjoiMjAyNS0wMy0xN1Lsome-policy-codeSxbImVxIiwiJQiLCIwiaW1hZ2UvanBTzdtU2F3VEhLd0l5eTFRPT0ifV19",
      "X-Amz-Signature": "b1c224f08a25d94f3387b908some-signature-68ce560c50fa65676c1b497401db3b",
      "x-amz-meta-fileName": "image",
      "x-amz-meta-uploaderId": "9-4NZnF4439qP",
      "x-amz-meta-orgId": "0FYWOhilep50",
      "x-amz-meta-contentType": "image/jpeg",
      "x-amz-meta-fileId": "fkS4c25o5IX"
    }
  },
  "downloadUrl": "https://prod-contrail-file-content-bucket.s3.amazonaws.com/0FYWOh9Milep50de10d-8284-4c8d-b454-4509f9ebe92e?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAXGPNJ5%2F20250317%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20250317T214318Z&X-Amz-Expires=86400&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEPb%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJIMEYCIQCYBp%2FRbTHTUUrpWBy9c3tqpfuLcnhIv2ONaNzsiaOfMgIhAIncgQjVi36G2dGz2U9EfHfGaFCoZulRa3Rz3Q8iKiF3KpMDCE8QAxoMNDk0OTU1NzgyMDA2Igy5rGbRF9IWTdl7KTkq8AKDSBmbz7bRyonZiiQuROgPuFFO%2FXolLg%2Bm%2FDQ%2FOa1a3jn6pUp2Ij0jigzC417R7y%2B9oITWQ3Ixe%2BLwzY4C5mob2kyW%2FUDB3PaO9T306xvT2wPSgc%2BjNb0W4sF7rGvcWKtHCctPJ6TR4899GKDUnmgfTpIbokDC1ypARaAMeBAuId1q7%2Fm298Qi2WPGYhur985IigzEtJ16pVeMGYCSfz1GF8lvfTYLxZFISf52aqglXAQDtKSo0A24bOi%2F96Zm8m8GSIB75oUYaWkrErt3aI8ieu8i%2BJzWEy2K7s9VqxCYuAyxOWW4muhVMhYTVKhvjZpA%2FcTGZDb66mtJjPuKOmfrNpml8JTPpmL7oSA3FVE3v7a423l0EMjrt5DFXeAuvHE7iGYWjws5u%2B3QwVQQ0PuTKUTm7E6eL8TTcCumqee4rrP7sEhiVbpXKvn9jLI8tTtjWCtwWeDMFvLFUaYfabJCdfwxyBSztxfqi7rSN9o5vzCxquK%2BBjqcAZasSaGGDmjjAQF%2B%2BpHdIxzkZowSSAWAt6qN7VA7e9%2BPHztDDgrSZnyM0gCpoTZWK7DcWCxQCCpC6MNlXmGsUIHmNM4JFm%2F9xBsim%2BUkYLTAWC23mZkk7xpN%2FtMiyF1C%2BwtcDlWB79kAFU7zsPG32PKcU8znJ1jP7zYzOT0ofG6eMAPauKvqByjx4ob5yIAE4qAO7mSawTHKwIyy1Q%3D%3D&X-Amz-Signature=9aa9bc64b8c34e47aecd1ba2588f9a3cd912d63da120de03be2e7a2e439e6967&X-Amz-SignedHeaders=host&response-content-disposition=attachment%3B%20filename%3Dimage",
  "adminDownloadUrl": "https://admin.vibeiq.com/org/your-org-name/files/fkS4o5IX/download"
}

Upload the File to the S3 Bucket¶

Using the uploadPost data from the previous step, upload the file to S3.

curl -X POST 'https://s3.amazonaws.com/prod-contrail-file-content-bucket' \
  -H 'Content-Type: multipart/form-data; boundary=----WebKitFormBoundary123456' \
  -F 'key=0FYWOhu9p50/some-file-key/775d-8284-4c8d-b454-4509f9ebe92e' \
  -F 'bucket=prod-contrail-file-content-bucket' \
  -F 'x-amz-meta-contentType=image/jpeg' \
  -F 'Content-Type=image/jpeg' \
  -F 'X-Amz-Algorithm=AWS4-HMAC-SHA256' \
  -F 'X-Amz-Credential=A0000000/17000/us-east-1/s3/aws4_request' \
  -F 'X-Amz-Date=20250317T214318Z' \
  -F 'X-Amz-Security-Token=IQoJbAIncgQjVi3some-security-code6G2dGuFFO/XolLglSgc+jNb0W4sF7rGvcWauKvqByjx4ob5yIAE4qAO7mSawTHKwIyy1Q==' \
  -F 'Policy=eyJleHBpcmF0aW9uIjoiMjAyNS0wMy0xN1Lsome-policy-codeSxbImVxIiwiJQiLCIwiaW1hZ2UvanBTzdtU2F3VEhLd0l5eTFRPT0ifV19' \
  -F 'X-Amz-Signature=b1c224f08a25d94f3387b908some-signature-68ce560c50fa65676c1b497401db3b' \
  -F 'x-amz-meta-fileName=image' \
  -F 'x-amz-meta-uploaderId=9-4NZnF4439qP' \
  -F 'x-amz-meta-orgId=0FYWOhilep50' \
  -F 'x-amz-meta-fileId=fkS4c25o5IX' \
  -F 'file=@/path/to/image.jpeg'

Linking Images to Items¶

You can link images to items by creating a Content entity. The Content entity acts as a link between a file and an item.

To create a Content entity, you need to provide the following data:

contentHolderReference: A reference to the item the image will be linked to, in the format item:<item ID>.
contentType: The content type of the image being uploaded (e.g., image/jpeg).
copyFileId: The ID of the file you created in the previous step.

image_load_script.ts

  const tasks = contentToCreate.map((content) =>
  limit(async () => {
    try {
      const itemFederatedId = content.fileName.split("_")[0];

      // Fetch the item based on its federated ID
      const item = await new Entities().get({
        entityName: 'item',
        federatedId: itemFederatedId,
      });

      // Create the content linked to the item
      const resultingContent = await new Entities().create({
        entityName: 'content',
        object: {
          contentHolderReference: `item:${item.id}`,
          contentType,
          copyFileId: content.copyFileId,
        },
      });
    } catch (e) {
      console.log(`Failed to create content for ${content.fileName}`, e);
    }
  })
);

// Wait for all the mapped tasks to finish
await Promise.all(tasks);
}

This will successfully attach an image to each of the Items provided the Items federated IDs are indicated in the file names.

Linking images to items using cURL¶

curl -X POST '{{baseURL}}/content' \
  -H 'x-api-key: $API_TOKEN' \
  -H 'x-api-org: $USER_ORG' \
  -H 'Content-Type: application/json' \
  -d '{
  "contentHolderReference": "item:mkzvjUlEFzKv-jUc",
  "contentType": "image/jpeg",
  "copyFileId": "jhQntcifRfjQkQ0G"
}'

Some iterative method will be required to run this request automatically for all items and images.