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"
/>
![emma armchair example](https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/frames/1/chair.png)
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
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"
/>
![emma armchair example](https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/frames/9/chair.png)
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.
*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
);
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"
/>
![emma armchair example with yellow upholstery](https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/frames/1/chair.png?feature=LEGS:SQUARELEG_OW&feature=UPHOLSTERY:YELLOW)
Ignore Unknown Features
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"
/>
![emma armchair example with unknown feature UNKNOWN_FEATURE](https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/frames/1/chair.png?feature=LEGS:SQUARELEG_OW&feature=UNKNOWN_FEATURE:YELLOW&ignoreunknownfeatures=true)
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"
/>
![emma armchair](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.
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"
/>
![emma armchair example with a specific version](https://content.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/frames/1/chair.png?version=2)
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"
/>
![material cylindo red](https://content.cylindo.com/api/v2/4965/materials/ff0788a9-e1d3-479c-9444-2fd2e5064cde/image/red.jpeg?size=300)
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 cylindo blue](https://content.cylindo.com/api/v2/4965/products/SNOWMAN_CYLINDO/material/blue.jpg?&feature=SCARF:BLUE&size=300)
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)
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"
/>
![material cylindo blue cropped](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)
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
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"
/>
![Sofa example for documentation](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"
/>
![Sofa example for documentation](https://content.cylindo.com/api/v2/4508/products/PAIDGESOFA/frames/3/sofa_zoom.jpg?size=512&crop=(300,300,700,700)&zoom=2k)