Unicat API Reference

Up - API Reference - Home

/dam/p/<project gid>/transform/<storage pathname>/<options>

Transform an asset for preview and production.

Returns (among other info) the URL you can use to fetch the transformed asset.

GET Request

GET /dam/p/<project gid>/transform/<storage pathname>/<options>
Authorization: Bearer <JWT>

storage pathname is the storage path name to the asset - not related to the path name as used in the assets data.

The current implementation uses a gid-based filename with versioning. As an example, we have an svg file in /vector/example.svg, with gid eddbe3b0-eb6a-4301-9700-c770df127456 and version 31. The pathname will be eddbe3b0-eb6a-4301-9700-c770df127456~31.svg.

options is a slash-separated list of name=value options, e.g. /width=400,400/dpr=2.

GET Options

Some options affect how the transformed file is named, and some options specify how the transformation should look. The order of the options is not relevant.

Naming options

/name=seo-optimized-name

Optional. Default: use source filename
Use this as the filename instead of the source filename. Mustn't include the extension.

/key=2x

Optional. Default: auto-generate a key from a hash of the options
If you make multiple transforms from the same file, you can use keys to individualize them. They are included in the filename after the name and before the extension. A key is prepended by a '@', so we would get /filename@2x.jpg. You can use @'s in filenames and in keys, just make sure that the combinations add up to a unique final filename.

/type=jpg

Options: jpg, png, or gif
Both extension and transformed file type. If you don't specify this, the source extension is used, which can lead to faulty results if it isn't one of the supported file types (jpg, png, or gif).

Request options

/force=true

Optional. Default: false
If force isn't enabled, no transformation is done if a file with the transform filename exists and is newer than the source.

/optimize=true

Optional. Default: false
We support pngcrush, jhead, jpegoptim, jpeg-recompress, gifsicle, scour, and svgo to strip down and compress the transformed file. Since this is a time-consuming process, it is disabled by default.

Transform options

/width=400
/width=400,300
/height=300
/height=400,300
/fit=400,300
/fill=400,300

Required. Choose one transform from width, height, fit, or fill
The value determines the dimensions of the resulting canvas. For width and height, if a single value is given, the other value is determined using the aspect ratio of the source. Note that resizing will always respect the aspect ratio. Placement of the resized source on the canvas is controlled by the hotspot, crop, and padding options.

• width - Resize source to fit canvas width. If both width and height are given, then the source is resized so the height is never exceeded. This may result in an image with some padding on the left/right sides, because the target canvas will always be the requested width.
• height - Resize source to fit canvas height. If both width and height are given, then the source is resized so the width is never exceeded. This may result in an image with some padding on the top/bottom sides, because the target canvas will always be the requested height.
• fit - Resize the image to fit completely inside the canvas.
• fill - Resize the image to completely fill the canvas, cropping the source if needed.

Values are capped at 5000 pixels.

/hs=0.5,0.5

Optional. Default: 0.5,0.5 (the center)
The hotspot serves two purposes: first to place the resized image on the canvas with the hotspot as close as possible to the center of the canvas, and second as the centerpoint for the crop transform if one is requested. The hotspot is given as an x,y coordinate, with values as a fraction of the width and height, respectively. Valid values are 0.0 through 1.0 for each, and they are separated by a comma, no spaces.

/crop=0.6,0.6

Optional. Default: don't crop
Use crop to select an area from the source that will then be resized to be placed on the canvas. NOTE: check if this works ok with width/height resizing and crops with a different aspect ratio from the source The crop is given as w,h dimensions, with values as a fraction of the width and height, respectively. Valid values are 0.0 through 1.0 for each, and they are separated by a comma, no spaces.

/padding=0,auto,0,auto

Optional. Default: auto,auto,auto,auto
Specify padding in the target image. The values are for top, right, bottom, and left padding (clockwise starting at top). If a value is set to auto, that padding will grow to fill available space. If two opposing sides have non-auto values, they will get at least the specified padding, plus half of the remaining available space each. If you want to anchor the image to the top-right of the canvas, you can specify 0,0,auto,auto.

Values are capped at 1000 pixels.

/bg=abcdef

Optional. Default: transparent (or white if transformed file doesn't support transparency)
Specify a background color to use for transparent areas in the source and for any padding added. There are two predefined options, transparent and white. Any other background color must be specified as an rgb hex value, similar to CSS but without the # sign. Use the full 6-character rgb hex, not a CSS shortcut like bbb.

/q=82

Optional. Default: 100
Lower quality leads to smaller filesizes, but higher quality looks better. This is a compromise, use your best judgment. Allowed values are 0 through 100.

/dpr=2

Optional. Default: 1
Device pixel ratio is abbreviated dpr, and is used to indicate the number of physical pixels the device screen has per logical pixel. You always specify the resizing and padding values in logical pixels. Regular screens have a dpr of 1. High resolution or retina screens have a dpr of 2 or 3. We support a max dpr of 4, just in case. A dpr of 2 means that for a requested width of 400, you get a transformed image with 800 (physical) pixels.

Success response

Note: unlike /api calls, a /dam call NEVER refreshes the JWT

{
    "success": true,
    "result": {
        "public_url": "https://unicat.app/media/p-8fdf8601-6ad0-405e-962a-89400ae69a41/var/eddbe3b0-eb6a-4301-9700-c770df127456@6c598674.jpg",
        "dimensions": [850, 850],
        "timing_ms": {
            "transform": 0,
            "optimize": 0
        },
        "request": "/eddbe3b0-eb6a-4301-9700-c770df127456~3.svg/width=425,425/type=jpg/dpr=2/key=6c598674",
        "source": "/src/eddbe3b0-eb6a-4301-9700-c770df127456~3.svg",
        "target": "/var/eddbe3b0-eb6a-4301-9700-c770df127456@6c598674.jpg",
        "options": {
            "width": "425,425",
            "type": "jpg",
            "dpr": "2"
        }
    },
    "data": {}
}

result

public_url use this url to fetch the transformed image
dimensions the width,height value for the transformed image - usually this is the same as the requested width and height, but if you use the 'width' or 'height' resizing option (or 'dpr') it may differ
timing_ms see how long the transform and optimize processes took, in milliseconds - if one or both of these values is 0, the process was skipped (perhaps because the target was already generated and the source wasn't modified since)

The other results are a reiteration of the request, with the values parsed. You'll find request, source, target, and options. These are for debugging purposes and may disappear in the future.

Error responses

400 Bad request - missing parameters or wrong type or value
401 Permission denied - missing or expired JWT
403 Forbidden - not a member of this project
422 Unprocessable entity - asset or parent asset doesn't exist