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
|
||
All URLs are of the form:
/{customer id}/{product type identifier}/{product identifier}/{content type}/{parameters}
|
||
Example |
||
|
Customer id, is the id of the customer as provided by Cylindo. Product type identifier, string, is how to identify the product. |
||
| products, if you use the product code. Returns an image | ||
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 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: |
|
|
| 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 types. |
||
Example: |
||
|
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.*
* 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: |
||
| AR (3D files) Exists, get if there exists an AR file for the product. Works in the same way as for getting the AR file, but only checks if the file exists. This is much faster than downloading the file in order to check if it exists. In stead 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. | ||
Example: |
||
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 the 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. |
||
Example:
|
||
| 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. |
||
| https://content-v2.cylindo.com/api/v2/4965/products/EMMA_ARMCHAIR/frames/1/?feature=LEGS:SQUARELEG_OW&feature=UPHOLSSSSSSTERY:YELLOW&ignoreunknownfeatures=true | ||
| filename, common for all requests returning a file is that the filename can be specified before the list of parameters. To specify the file name use {pre URL}/{filename}?{parameters}. | ||
Example: |
||
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:
|
||
Example: |
||
| 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 | ||
Example: |
|
|
zoom, string, specifies the source image size used for cropping. Default value is "4k". The following values can be used
|
||
Example |
||
| background, hex, specify the background colour as RGB in hex format. Default is FFFFFF. | ||
Example: |
||
|
encoding, string, used for specifying the image format to return. If not specified then it will try to get it from the http accept header, else from the possible filename extension else defaults to jpg-90. The possible values are
|
||
Example: |
||
| version, int, to get another version than what is set as default. Should only be used for testing new products or product versions. Will be slower than normal requests if specified. | ||
Example: |
||
|
In general the larger the image requested or worked on the longer time it will take to process. |
||
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 pre sets: api/v2/{accountNumber}/materials/{id}/image/{name.extension}
|
||
|
||
Example: |
||
|
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}
|
||
Example: |
||
| Material swatch preset | ||
|
Pre sets If not specified otherwise, materials will be fetched using the below pre sets.
|
||
|
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. |
||
Example: |
||
Error handling |
||
| In case of an error (http 5xx) or an image is not available (http 404) then 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: |
||
Examples |
||
| Example 1: For customer 4508 and product code PAIDESOFA showing frame 3 and returning a jpeg image named sofa.jpg. The Image is resize 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. | ||
content.cylindo.com/api/v2/4508/products/PAIDGESOFA/frames/3/sofa.jpg?size=512& |
||
| 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 | ||
content.cylindo.com/api/v2/4508/products/PAIDGESOFA/frames/3/
|
