Content API

The <cylindo-viewer> fetches all its resources from Cylindo's servers. You can also fetch the resources yourself and use them in your own images. For example as a hero-image or for creating your own product configurator with swatches from live data.

Functions

The following section describes the functions and their behaviour in the Content API v2. The base URL for all requests is:

https://content.cylindo.com/api/v2

API URL Structure

Each API request follows a standardized URL structure to access different resources:

/{customer_id}/{product_type_identifier}/{product_identifier}/{content_type}/{parameters}

Below is the breakdown of each URL component:

URL Component	Description
Customer Id	Unique identifier for the customer, provided by Cylindo.
Product Type Identifier	String identifier used to categorize the product.
Product Identifier	Specific code or identifier for the product.
Content Type	Type of content to retrieve, e.g., images, frames, AR files.
Parameters	Additional query parameters for the request, such as size, color, etc.

Example

<img
  src="https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/frames/1/chair.png"
  alt="emma armchair example"
/>

Configuration

You can use the configuration function to check if Cylindo have a visualisation of your product and which features and options the product is available in.

Example

content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/configuration

List Customer Products

The listcustomerproducts function allows you to retrieve a list of products rendered in Cylindo. This is a good way to add verification on your side and to add any checks on what is available on the website and what Cylindo has rendered.

Example

content.cylindo.com/api/v2/4965/listcustomerproducts

Content Type

Content type, string, specifies what kind of content to retrieve. Currently the following types are supported

Frames

Get a specific frame number from the 360 Viewer. To specify the frame number, do it like {pre URL}/frames/{frame number}/{parameters}.

As default there are 32 frames for a complete 360 and frame 1 is the front facing image.

Example

<img
  src="https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/frames/9/chair.png"
  alt="emma armchair example"
/>

AR (3D files)

Get the low poly AR file for your product. You can specify if you want to request .usdz files which is the format used by Apple (iOS, iPadOS) or .GLTF/.GLB which are used on Android. The filename and feature array for your AR file must be specified.

You can also access OBJ, FBX, and DAE file.

Example

https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/AR/EmmaArmchair.glb?
feature=LEGS:METAL_LEGS&feature=UPHOLSTERY:YELLOW

ARQR

Get a QR code image that can be scanned to open the AR file of a product on iOS or Android devices. The parameters for a specific product configuration is the same as for AR files or image frames. When requesting the QR code you can pass in a redirect url. The consumer will be redirected to the url when closing the AR experience on their device.*

    redirect_url parameter needs to be included to direct client back from ar.cylindo.com to your product page.

Android

*On iOS the consumer will be redirected to the url you pass in. On Android the experience varies depending on camera app used to scan the QR code. Some camera apps direct user back to phone homescreen, other back to browser.

Example

<img
  src="https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/ARQR/EmmaArmchair?
feature=LEGS:METAL_LEGS&feature=UPHOLSTERY:YELLOW&redirect_url=https://cylindo.com"
  alt="QR code for product"
/>

AR (3D files) Exists

If it exists, get an AR file for the product. This endpoint works in the same way as for getting the AR file, but it only checks if the file exists. This makes it much faster than downloading the file in order to check if it exists. Instead of making a get request, make a head request. You still have to specify the device type by setting the file type to .usdz or gltf since not all files are generated for all devices.

fetch(
  "https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/AR/EmmaArmchair.glb?feature=LEGS:METAL_LEGS&feature=UPHOLSTERY:YELLOW",
  {
    // Head request
    method: "HEAD",
  }
).then(({ ok }) =>
 // Code to check if the file exists
);

External media

External media linked to your product can be accessed through the Content API using their unique IDs. You can find, add, view, and manage these external media resources within the Media tab of your product.

Use the following API call to fetch the media:

api/v2/{accountNumber}/products/{code}/staticcontent/{id}/{name.extension}

Example

<img
  src="https://content.cylindo.com/api/v2/5098/products/ARMCHAIR-PDP/staticcontent/f68ee704-c36b-410d-96cc-9b54f4119661/external-media.png"
  alt="rock formation on a beach, retrieved from picsum"
/>

Parameters

It is not required to specify any parameters. If no parameters are specified the default content configuration is returned.

The following parameters are available for all requests:

Feature

string specifies a feature to include.

There can be multiple of these parameters. It must be of the type {feature code}:{option code} where feature code is the identifier of the feature and option code is the selected value of that feature. If a feature parameter is not valid, by default, for the given product, an error is returned specifying what is wrong. If using configuration alias, then the list of features is populated with what has been set up.

<img
  src="https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/frames/1/chair.png?
  feature=LEGS:SQUARELEG_OW&feature=UPHOLSTERY:YELLOW"
  alt="emma armchair example with yellow upholstery"
/>

Ignore Unknown Features

ignoreunknownfeatures

Please note that if a flag "ignoreunknownfeatures=true" is added to the query, any unknown feature will be ignored and an image will be returned instead of an error.

<img
  src="https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/frames/1/chair.png?
  feature=LEGS:SQUARELEG_OW&feature=UNKNOWN_FEATURE:YELLOW
  &ignoreunknownfeatures=true"
  alt="emma armchair example with unknown feature UNKNOWN_FEATURE"
/>

Filename

The filename can be specified before the list of parameters. This is common for all requests returning a file. To specify the file name use {pre URL}/{filename}?{parameters}.

<img
  src="https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/frames/1/
  Armchair.png"
/>

Image Parameters

All requests for images support the following parameters:

Size

Specifies the size of the image. The value must be between 0 and 4096. If 0 or not specified the crop size if specified or else the default size for the given product is used. Can be specified in 3 ways:

• int, the size of the longer edge
• (int), same as above
• (int:width, int:height), the full image size. Will pad with background to keep aspect ratio

<img
  src="https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/frames/1/
  ?size=(521,320)"
  alt="emma armchair with specific size"
/>

Crop

(int:x, int:y, int:width, int:height), used to crop the image to the specified square. The source image dimensions are specified in the zoom parameter

<img
  src="https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/frames/31/
  ?crop=(1900,700,1024,1024)"
  alt="emma armchair example with crop"
/>

Zoom

string specifies the source image size used for cropping. Default value is "4k". The following values can be used

Values	Sizes
"4k" or "large"	** 4096 * 4096 **
"2k" or "medium"	** 2048 * 2048 **
"1k" or "small"	** 1024 * 1024 **

<img
  src="https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/frames/31/?crop=(500,300,512,512)
  &zoom=2k"
  alt="emma armchair example with 2k Zoom"
/>

Background

hex specify the background colour as RGB in hex format. Default is FFFFFF.

<img
  src="https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/frames/31/
  ?background=e6b6ad"
  alt="emma armchair example with a specific background"
/>

Encoding

string used for specifying the image format to return. If not specified, it will first be guessed from the http-accept header, then from the possible filename extension. It defaults to jpg-90. The possible values are:

• jpg with an optional -{1-100} for JPEG and optional quality.
• png for PNG.

<img
  src="https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/frames/31/
  ?encoding=png"
  alt="emma armchair example in png encoding"
/>

Version

int to get another version than what is set as default.

caution

Should only be used for testing new products or product versions, as it will be slower than normal requests if specified.

<img
  src="https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/frames/1/chair.png
  ?version=2"
  alt="emma armchair example with a specific version"
/>

Materials

Material swatches can be requested either with the Material ID or with the product id specifying the feature & option for the material swatch.

Fetch with Material ID

Use the following API call to fetch a material using our presets:

api/v2/{accountNumber}/materials/{id}/image/{name.extension}

section	Description
id	is the "Key" that can be found in the Portal under a material page in the Material
name.extension	string, specify your filename and an extension (jpg, png or webp)

<img
  src="https://content.cylindo.com/api/v2/4965/materials/ff0788a9-e1d3-479c-9444-2fd2e5064cde/image/red.jpeg?size=300"
  alt="material cylindo red"
/>

Fetch Materials by Product

It's also possible to fetch an image of a material swatch by passing the parameters for a product and the specific feature & option.

api/v2/{account}/products/{code}/material/{name.extension}?feature={feature}:{option}

<img
  src="https://content.cylindo.com/api/v2/4965/products/SNOWMAN_CYLINDO/material/blue.jpg?&feature=SCARF:BLUE&size=300"
  alt="material cylindo blue"
/>

Material Swatch Preset

Presets

If not specified otherwise, materials will be fetched using the below presets.

Presets	Value
** Resolution **	1k
** Size **	64 x 64 px
** Position **	Top Left Corner

Specify Resolution, Size and Position in your API call

Add the below parameters to specify resolution, size and position:

api/v2/{accountNumber}/materials/{id}/image/{name.extension}?size=xxx&crop=(x,y,width,height)

note

All values are specified in pixels

<img
  src="https://content.cylindo.com/api/v2/4965/products/SNOWMAN_CYLINDO/material/blue.jpg?size=256&crop=(200,200,300,300)&version=9&feature=SCARF:BLUE"
  alt="material cylindo blue cropped"
/>

Error Handling

In case of an error (http 5xx) or an image not being available (http 404), a message specifying what is wrong will be returned. This message can be used to debug what might be wrong with the request.

Example

Request for an invalid feature configuration will return a 404 and a descriptive error message

Request: https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/frames/1/?feature=LEGS:SQUARELEG_OW&feature=UPHOLSTERY:BROWN

Response: An option with the specified code 'UPHOLSTERY/BROWN' does not exist on product '4965:'EMMA_ARMCHAIR' v2'.

Examples

Example 1

For customer 4508 and product code PAIDESOFA showing frame 3 and returning a JPEG image named sofa.jpg.

The Image is resized to the longer edge being 512 pixels. Having set the feature FABRIC COLOR to BLUE and the feature PILLOWS to PILLOWS_1. The background color is set to 999999.

<img
  src="https://content.cylindo.com/api/v2/4508/products/PAIDGESOFA/frames/3/sofa.jpg?size=512&
  feature=FABRIC COLOR:BLUE&feature=PILLOWS:PILLOWS_1&background=999999"
/>

Example 2

For customer 4508 and products code PAIDESOFA showing frame 3 and returning a png image named sofa_zoom.png. In a 2k resolution the image is cropped from 300, 300 and 700 pixels down and to the right.

The resulting image is then resized to 512 pixels

<img
  src="https://content.cylindo.com/api/v2/4508/products/PAIDGESOFA/frames/3/
  sofa_zoom.jpg?size=512&crop=(300,300,700,700)&zoom=2k"
/>