Uploading images

One common way to make images available to the image server is by using the Asset Library or direct access facilities within the Customizer. For detailed information, refer to the (see Image sources | Image-file-storage).

However, there are scenarios where images need to be added dynamically or through an API. These scenarios include, but are not limited to:

• A customer uploading a user-generated (UGC) image to be used for personalization purposes

• A custom ETL process uploading product images based on a catalog import

While both use cases follow a similar workflow, they may require different parameters depending on the specific upload path.

Making requests

Unlike rendering requests that utilize the CDN endpoint fx.images.drivecommerce.com, upload requests should always use the API endpoint - api.images.drivecommerce.com

The general request URL form shall be in the format:

https://api.images.drivecommerce.com/api/v1/<client name>/image/upload

Upload requests shall use POST HTTP method and submit the data using a multipart HTTP request.

For example: JavaScript code uploading an UGC image from an <input> element:

const formData = new FormData();

// Upload a file.
formData.append('file', file);

formData.append('min-width', '300');
formData.append('min-height', '300');

formData.append('fit', 'cover');

formData.append('fit-width', '2000');
formData.append('fit-height', '2000');

axios({
    method: 'post',
    url: '//api.images.drivecommerce.com/api/v1/image/client/upload/',
    data: formData,
    config: {
        headers: { 'Content-Type': 'multipart/form-data' },
    },
    onUploadProgress: (progressEvent) => {
        // Track upload progress in percents: (progressEvent.loaded / progressEvent.total) * 100;
    },
}).then((response) => {
    // Done, process the response.
}).catch((error) => {
    // Failed, read the error data.
    if (error && error.response && error.response.data) {
        const { data } = error.response;
    }
});

Authentication

Depending on the use case, some uploads may require authentication. To enable this functionality, please contact Drive Commerce support to obtain the API keys associated with your account.

Authentication parameters can be supplied using one of the following methods:

• Form Parameter: Include the authentication details directly within the form data.

• Authorization Header: Use the Authorization HTTP header to pass authentication credentials.

Form authorization

Submit the API key using apikey form parameter.

Header authorization

Submit the API key using Authorization Bearer credentials:

Authorization: Bearer <api-key>

User generated content vs permanent assets

The upload API intakes two types of image content.

User generated generated content

User-generated content (UGC) assets are designed to be uploaded by end users to add a personal touch to their custom products. Examples include printing a custom photo or etching a design. UGC assets are ephemeral by nature and are subject to deletion after a predefined period, typically soon after an order has been placed and potentially processed for manufacturing.

UGC uploads are intended to originate from public Internet contexts, such as a browser or mobile app. These upload actions do not require API authentication.

When uploading UGC, do not include the name parameter. The asset will automatically be assigned a randomly generated name, regardless of the original file or URL name.

Permanent assets

Permanent assets, such as product images, 3D models, and font files, are typically uploaded once and reused across multiple product renderings.

Unlike user-generated content, permanent assets are not deleted automatically.

To designate an asset as permanent, you must assign it a unique name using the name parameter.

It is the customer’s responsibility to ensure that asset names are unique. Uploading a new asset with an existing name will overwrite the previous asset, and this action cannot be undone

An API key is required when uploading permanent assets.

Specifying the image source

Assets—whether user-generated content (UGC) or permanent—can be uploaded using one of two methods:

• File Upload: Use the file parameter to provide a multipart form-encoded file source.

• Remote Copy: Use the copy-from parameter to specify an image source, either as a URL or as raw image data.

When using the copy-from parameter:

• If the value begins with the https:// prefix, it will be treated as an image URL.

• If no https:// prefix is present, the value will be treated as base64-encoded image data.

If the base64 data is corrupted or cannot be decoded as a valid image, the image server will return an error.

Validating input images

Uploaded images are always validated to ensure they contain valid image data. Additionally, extra constraint parameters can be used to enforce specific validation rules.

Cropping images

Images can be cropped during the upload process by specifying a set of parameters. All parameters must be specified at the same in order to trigger this functionality.

The cropping rectangle size and position may specify locations outside of the original image bounds. In such case, areas outside of image bounds will be left empty or will use the background color, if specified.

Fitting images to size

After the optional cropping step, uploaded images can be resized to specific dimensions. The target dimensions are specified using the following parameters:

The method used to arrange the image within the fitting rectangle is determined by the value of the fit parameter:

Adding image background

By default, images are uploaded as-is. However, a background color can be specified using the background parameter to serve as the backdrop for the resulting image.

Advanced functionality

Background removal

The image server can apply an AI model to automatically detect and remove the background from an image. This functionality works best with photographic content but, as with all AI models, may occasionally produce imprecise or unexpected results.

To enable background removal, use the photo-remove-background parameter and set its value to true.

Upload response

After the uploaded image is processed and ingested by the platform, the image server returns a response containing the description of the uploaded image.

For example:

{
    "name": "~z61L0553D114EMX7AH",
    "imageUrl": "//fx.images.drivecommerce.com/api/v1/image/drive-unit-test/~z61L0553D114EMX7AH",
    "jpgImageUrl": "//fx.images.drivecommerce.com/api/v1/image/drive-unit-test/~z61L0553D114EMX7AH.jpg",
    "pngImageUrl": "//fx.images.drivecommerce.com/api/v1/image/drive-unit-test/~z61L0553D114EMX7AH",
    "width": 1400,
    "height": 1400,
    "density": 72.0
}