Table of Contents
Export API
04. April 2025
Table of Contents
There are two ways of using CMS export in integrations:
- Interactively - by embedding the CMS export widget into a third-party application
- Automatically - by using the export API.
This article describes how to use the export API.
Programmatic export using the API
Using the export API assumes that all parameters for exporting an asset are either predefined or already known otherwise (for example, entered by a user through a custom interface in a third-party application). An asset can then be exported using the following request:
|
|
|
with request body:
|
|
|
where in the request:
| Attribute | Type | Value |
|---|---|---|
| width | Integer |
Width of the exported image (in pixels). Set to zero (0) to either use the original width or calculate the width from the specified height and original aspect ratio For remarks and examples, see Size and aspect ratio. |
| height | Integer |
Height of the exported image (in pixels). Set to zero (0) to either use the original height or calculate the height from the specified width and original aspect ratio For remarks and examples, see Size and aspect ratio. |
| publication | String |
An identifier of the place where the export is used. This is a free-form string that will be shown in the export management dialog. |
| preset | URL (String) | URL of a CMS export preset to be used for supplying additional parameters. |
API response
On success, the response is:
|
|
|
with response body:
|
|
|
where:
| Attribute | Type | Value |
|---|---|---|
export.source |
URL (Asset) |
URL of the exported asset. Can be used to access the details of the asset using the API or to display the details in a browser. |
export.json |
URL (object) |
JSON representation of the export. Identical to this JSON representation |
export.image |
URL (JPEG image) | Processed and exported asset (normal version) |
export.highCompression |
URL (JPEG image) | Processed and exported asset (smaller file size and potentially reduced quality) |
export.doubleResolution |
URL (JPEG image) | Processed and exported asset (doubled resolution, for Retina and similar displays) |
export.widget |
URL (HTML) |
An HTML widget containing the processed and exported asset with a tooltip and caption and optional additional behavior, if enabled during export Can be embedded using an iFrame. |
export.size.w |
Integer | Width of the exported image (normal version) in pixels |
export.size.h |
Integer | Height of the exported image (normal version) in pixels |
caption.label |
String | Caption string, if specified during export |
caption.tooltip |
String | Tooltip string, if specified during export |
publication.text |
String | Name of publication (free-form string), if specified during export |
metadata |
Dictionary |
Metadata of the asset when it was exported. The keys in this dictionary are the field numbers (as strings). The values are either strings (for regular fields) or arrays of strings (for bag fields). |
Size and aspect ratio
The size of the exported image is specified using the width and height parameters in the request.
If both parameters are set to zero (0), then the asset is exported in its original dimensions.
If exactly one of the parameters is non-zero, then that dimension of the exported image will be exactly as specified, whereas the other dimension (given as zero) will be calculated from it such that the original aspect ratio of the image is maintained. For example, if the image is 4:3, and the width in the request is set to 400, the height will be 300.
Note: It is not allowed to set both dimensions to non-zero values. Doing so will result in a response of 400 Bad Request. This is because specifying both dimensions would require cropping the image, which is currently not supported in the export API. Also, if images need to be cropped, you may typically want the user to select a crop frame. In this case, we recommend using the CMS export widget.
If your original images are all a specific known size (800x600, for example) and you want images to be exported in that same size, set both parameters to zero.
Example
Consider exporting a source asset of size 4000x3000:
| Width | Height | Exported width | Exported height |
|---|---|---|---|
| 0 | 0 | 4000 | 3000 |
| 400 | 0 | 400 | 300 |
| 0 | 600 | 800 | 600 |
| 400 | 400 | Bad request | Bad request |
Getting the preset URL
To use a preset with the export API, you must first create an export preset manually and share it.
To get the URL of the preset, you can use the browser's development console while displaying the list of presets in the CMS export dialog or a web debugging tool such as Fiddler. You should see a GET request to a URL /fotoweb/me/presets/export, which should contain an entry for your preset, such as:
|
|
|
The value of the href attribute is the preset parameter to be used in the export API.
Notifications when exported assets change
If you've made an integration using the Export API and would like to be notified when an asset changes, you can use asset webhooks to trigger a notification.