Note: we'll be using our home-built API connector Create an API connector. We could simplify this by using the 'official' Unicat client lib, but that wouldn't give the API insights because it is more high-level.
Note: at the end of the page, we show the same example while using the Unicat client lib.
We've uploaded an image and linked it to a record. Now we want to publish this record, and naturally we want to show the image as well.
Let's first fetch the record and the image asset.
from ccapi import UnicatApi
from .config import PROJECT_GID, SECRET_API_KEY
ccapi = UnicatApi("https://unicat.app", PROJECT_GID)
success, result = ccapi.connect(SECRET_API_KEY)
succes, result = ccapi.call("/records/get", {"record": "f2e64fe0-9ffa-4d9a-8750-d561d6542453"})
record = ccapi.data["records"][result["record"]]
succes, result = ccapi.call("/assets/get", { "asset": record["fields"]["en"]["image"] })
asset = ccapi.data["assets"][result["asset"]]
Uploaded assets are private by default. If we want to access them, we need to publish them, or publish a transformation of them - this includes resizing and cropping and the like. The results of those action include a public_url property, which you use to download the actual file.
Since we've already built our own API connector, we'll show how to use it - but afterwards, we'll delve into the details.
succes, result = ccapi.download(asset)
download_url = result["public_url"]
# or
options = {
"fill": "400,300",
"type": "jpg",
"dpr": 2,
"optimize": True,
}
succes, result = ccapi.transform(asset, options)
download_url = result["public_url"]
We can use the download_url as a regular, public url to fetch the asset (or preview).
You can stop reading now.
To get the original asset, you have to publish it using the dam/publish API.
This API expects a storage pathname, which is different from the pathname in the assets tree. The current implementation uses a gid+version-based filename. As an example, we have an svg file in /vector/example.svg, with gid 8af797af-7e52-43c9-9d6e-a66bd3028930 and version 3. The pathname will be 8af797af-7e52-43c9-9d6e-a66bd3028930~3.svg (we use the full gid, ~version, and the extension).
So, the URL to call will look like this:
dam_endpoint = "https://unicat.app/dam/p/" + PROJECT_GID
gid = asset["gid"]
version = asset["version"]
ext = asset["type"]
url = dam_endpoint + "/publish" + f"/{gid}~{version}.{ext}"
And the result of that call could be
{
"success": true,
"result": {
"public_url": "https://unicat.app/media/p/8be90d53-4c3d-46de-8b93-eca153e61cea/src/8af797af-7e52-43c9-9d6e-a66bd3028930~3.svg",
}
},
"data": {}
}
If that was decoded and stored in jsonresponse, we have the public download url:
download_url = jsonresponse["result"]["public_url"]
To get a preview of a file asset (a PDF, for instance), or just a resized or cropped version of an image asset, you have to transform it using the dam/transform API.
This API expects a storage pathname, which is different from the pathname in the assets tree. The current implementation uses a gid-based filename. As an example, we have an svg file in /vector/example.svg, with gid 8af797af-7e52-43c9-9d6e-a66bd3028930 and version 3. The pathname will be 8af797af-7e52-43c9-9d6e-a66bd3028930~3.svg (we use the full gid, ~version, and the extension).
So, the URL to call will look like this:
dam_endpoint = "https://unicat.app/dam/p/" + PROJECT_GID
gid = asset["gid"]
version = asset["version"]
ext = asset["type"]
url = dam_endpoint + "/transform" + f"/{gid}~{version}.{ext}"
We want to specify the transformation options too:
options = {
"fill": "400,300",
"type": "jpg",
"dpr": 2,
"optimize": True,
}
url+= "/" + "/".join(
f"{str(key)}={str(value)}" for key, value in options.items()
)
And the result of that call could be
{
"success": true,
"result": {
"public_url": "https://unicat.app/media/p/8be90d53-4c3d-46de-8b93-eca153e61cea/var/8af797af-7e52-43c9-9d6e-a66bd3028930@6c598674.jpg",
"dimensions": [800, 600],
"timing_ms": {
"transform": 0,
"optimize": 0
},
"request": "/8af797af-7e52-43c9-9d6e-a66bd3028930~3.svg/width=400,300/type=jpg/dpr=2/optimize=True",
"source": "/src/8af797af-7e52-43c9-9d6e-a66bd3028930~3.svg",
"target": "/var/8af797af-7e52-43c9-9d6e-a66bd3028930@6c598674.jpg",
"options": {
"width": "400,300",
"type": "jpg",
"dpr": "2",
"optimize": "True"
}
},
"data": {}
}
If that was decoded and stored in jsonresponse, we have the public download url:
download_url = jsonresponse["result"]["public_url"]
pip install unicat
Ok, here it goes:
from unicat import Unicat, UnicatTransform
from .config import PROJECT_GID, SECRET_API_KEY, LOCAL_ASSET_FOLDER
unicat = Unicat("https://unicat.app", PROJECT_GID, SECRET_API_KEY, LOCAL_ASSET_FOLDER)
if not unicat.connect():
raise Exception("Invalid connection settings")
language = unicat.project.default_language
# the gid is hard-coded here just to simplify the example -- you get it by other means normally
record = unicat.get_record("f2e64fe0-9ffa-4d9a-8750-d561d6542453")
asset = record.fields[language]["image"]
# download the original
local_pathname = asset.download()
# download a transformed version
transform = UnicatTransform(resize="fill", width=400, height=300, type="jpg", dpr=2, optimize=True)
local_pathname = asset.download_transformed(transform)
This will store the (transformed) asset locally, in the LOCAL_ASSET_FOLDER base folder, with the assets own name and path. You can change that name in the calls to download and download_transformed.
Documentation for the Unicat client lib is available here.