Skip to main content

Upload API

The kittl.upload.image namespace uploads image data from your extension as Blob values (including browser File objects). In the app sandbox these methods are asynchronous and return SdkResult; check isOk before reading result.

See the Image Upload API reference for a compact summary, SDK scopes for manifest requirements, and Adding Images for placing images on the canvas after upload.

upload​

Use kittl.upload.image.upload to store an image as a durable upload tied to the user’s upload library. The resolved value is an array of UserImageUpload objects: { id, objectName, mimeType }. Use objectName as the src argument to kittl.design.image.addImage (see Adding Images).

Parameters​

Pass { blob }, where blob is image bytes. A browser File from a file input is a Blob, so you can pass it directly.

Scope Required

Declaring uploads:create in your app manifest is required for this method. See SDK scopes.

Example: upload then add to the design​

const uploadResult = await kittl.upload.image.upload({ blob: fileBlob });

if (uploadResult.isOk && uploadResult.result.length > 0) {
    const { objectName } = uploadResult.result[0];

    const addResult = await kittl.design.image.addImage({
        src: objectName,
        size: { width: 300, height: 300 },
        position: {
            absolute: { left: 50, top: 50 },
        },
    });

    if (addResult.isOk) {
        console.log('Image added:', addResult.result);
    }
} else if (!uploadResult.isOk) {
    console.error('Upload failed:', uploadResult.error);
}

uploadTemp​

Use kittl.upload.image.uploadTemp when you need a temporary upload: the result describes a short-lived asset, not a full UserImageUpload record. Each entry has the shape { objectId, mimeType } (there is no objectName or library id).

Typical uses include previews or intermediate steps where you do not want to persist a file in the user’s uploads. Whether a temp objectId is accepted in every API that takes an image src depends on the host; when supported, you can pass objectId as src the same way as objectName from upload.

The public scopes table does not list uploadTemp separately. Until it does, include uploads:create if your app uses upload APIs, or confirm the exact scope during manifest review.

Example: temporary upload​

const tempResult = await kittl.upload.image.uploadTemp({ blob: previewBlob });

if (tempResult.isOk && tempResult.result.length > 0) {
    const { objectId, mimeType } = tempResult.result[0];
    console.log('Temp object:', objectId, mimeType);

    // When the host accepts temp references for canvas images:
    const addResult = await kittl.design.image.addImage({
        src: objectId,
        size: { width: 200, height: 200, applyViewportScale: false },
        position: { relative: { to: 'viewport', location: 'center' } },
    });

    if (!addResult.isOk) {
        console.error('Could not add temp image:', addResult.error);
    }
} else if (!tempResult.isOk) {
    console.error('Temp upload failed:', tempResult.error);
}

For durable images that should remain in the user’s uploads, prefer upload and objectName instead of uploadTemp.