Get format details
Sample request
curl -X GET "https://api.abyssale.com/designs/$DESIGN_ID/formats/$FORMAT_SPECIFIER" \
-H "x-api-key: $ABYSSALE_API_KEY"import abyssale from '@abyssale/sdk';
const designId = 'YOUR_DESIGN_ID';
const formatSpecifier = 'YOUR_FORMAT_SPECIFIER';
const { data, error } = await abyssale.getDesignFormat(designId, formatSpecifier);
if (error) console.error(error.id, error.message);
else console.log(data);from abyssale import Abyssale
design_id = "YOUR_DESIGN_ID"
format_specifier = "YOUR_FORMAT_SPECIFIER"
with Abyssale() as client:
result = client.get_design_format(design_id, format_specifier)
print(result)Example 200 response
{
"animation": {
"duration": 8,
"screenshot_at_s": 8
},
"design": {
"type": "static",
"category_name": "string",
"id": "64238d01-d402-474b-8c2d-fbc957e9d290",
"name": "Ad campaign fall 2025",
"created_at": 1649942114,
"updated_at": 1649942114
},
"elements": [
{
"name": "headline",
"type": "text",
"settings": {
"is_mandatory": false
},
"attributes": [
{
"id": "background_color",
"help": "6 or 8 digits hexadecimal background color (i.e. #F3F3F3) of the banner",
"value": "#FFFFFF"
}
],
"layout": {
"x": 0,
"y": 0,
"width": 3333,
"height": 666
},
"layer_ids": [
"string"
],
"hidden": false,
"locked": false,
"group": {
"auto_layout": false,
"direction": "string",
"placement": "string",
"gap": 0
},
"mask": {
"shape": "string",
"width": 0,
"height": 0,
"center_x": 0,
"center_y": 0,
"rx": 0,
"ry": 0,
"rotation": 0,
"radius": 0
},
"animation": {
"start_at_s": 0,
"end_at_s": 0
}
}
],
"variables": {
"name": "{name}",
"title": "{title}"
},
"version": "v2026-08-21",
"id": "facebook-post",
"uid": "9b57d65e-eb2c-4a74-a51e-4482917c248a",
"width": 1200,
"height": 1200,
"unit": "px",
"preview_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/e0d292f2-ec21-11e9-a539-3c408bf94155/a9b3c668-7b84-4924-adf0-815dae727d32.png",
"dynamic_image_url": "https://img.abyssale.com/ecf1fe8c-5392-48c2-b6d2-665183a18fe5/9b57d65e-eb2c-4a74-a51e-4482917c248a",
"dpi": 300,
"bleed_size": 3.5,
"safe_size": 5
}Example 401 error response
{
"message": "Unauthorized: missing or invalid API key.",
"id": "unauthorized"
}Retrieve detailed information for a specific format within a design, including dimensions, unit, preview URL, dynamic image URL, element layout, and variables. Useful for inspecting a single format before generating or building dynamic image URLs.
Behaviour, limits and caveats
For printer designs the response additionally carries the format's print settings read-only: dpi (integer render DPI computed at import time, capped at 300), and bleed_size / safe_size (floats in the design's unit, 0 when the zone is off). All three are always present on a printer format; a design with no stored print settings reports the renderer's own defaults (dpi: 300, zones 0).
For animated designs the response additionally carries the design's animation object (duration, screenshot_at_s — seconds), per-element animation timing/tween data, and video/audio media attributes — the same read surface as GET /designs/{designId}.
This endpoint is always the advanced view. Unlike GET /designs/{designId}, it needs no i=advanced parameter: it always returns the full property set and always injects the format's group layers, flattened to this single format (layout, the group block, and the computed hidden / locked are plain values, not keyed by format name). A group that does not exist in the requested format is not emitted.
Multipage print designs (printer_multipage): a multipage design is one document — it has no formats, and its pages are not addressable through this endpoint. Any formatSpecifier yields 404 with id: format_not_found. Read the whole document with GET /designs/{designId} or export it with GET /designs/{designId}/as-import.
Path parameters
designId string (uuid) required
Unique identifier (UUID) of the design. A value that is not a UUID does not match the route and answers 404 with id: endpoint_not_found.
formatSpecifier string required
Format name or UID.
More about formatSpecifier
Format name or UID. Prefer the UID — it survives a rename.
Not applicable to printer_multipage designs: they have no formats, so every value here answers 404 with id: format_not_found. See the endpoint description.
Response 200
Format details retrieved successfully
animation DesignAnimation
Animated designs only. The design's timeline, read-only (all values in seconds).
Show child attributes
duration number | null
Timeline length in seconds.
screenshot_at_s number | null
The moment the HTML5 backup screenshot is taken (seconds). Null on designs created before it was recorded that never stored it; always set on imported designs.
design DesignFormatSummary
The design a format belongs to, as returned nested in GET /designs/{designId}/formats/{formatSpecifier}.
Show child attributes
type string
One of "static", "printer", "animated", "printer_multipage".
category_name string | null
Deprecated. Deprecated alias of the project name — see Design.category_name.
id string (uuid) always
Unique identifier (UUID) of the design.
name string always
Name of the design.
created_at integer
updated_at integer
elements array of DesignFormatElement
The design's elements as they stand in this format: attribute values and layout are the requested format's, not maps keyed by format name (see DesignFormatElement). Group layers are included, flattened to this format.
Show child attributes
name string always
Layer name (root is a special element that allows to customize the image background color.)
type string always
Layer type. container is the design's own root wrapper, not a layer you can author or override — skip it when walking the tree. code, listed last, is a marginal animated-only custom HTML/JS layer, read-only in the same way. One of "container", "text", "button", "image", "logo", "shape", "illustration", "rating", "qrcode", "video", "audio", "group", "code".
settings object
Show child attributes
is_mandatory boolean
Whether the element is mandatory
attributes array of object
Show child attributes
id string
Attribute identifier
help string
Help text for the attribute
value string | number | boolean
The attribute's value in the requested format. Usually a string; a video/audio layer's media attributes are typed (video_duration/max_volume numbers, video_muted/audio_muted booleans).
layout ElementLayout
The element's box in the requested format.
More about layout
An element's box. Integers in pixels on static/animated; floats in the design's physical unit (mm/in) on printer.
Show child attributes
x number
y number
width number
height number
layer_ids array of string
group layers only — the names of the layers this group contains.
hidden boolean
group layers only — computed visibility in this format.
locked boolean
group layers only — computed lock state in this format.
group GroupLayout
group layers only — auto-layout settings in this format.
More about group
Auto-layout settings of a group layer. Empty on animated designs — the platform stores no auto-layout there. direction, placement and gap appear only when auto_layout is on.
Show child attributes
auto_layout boolean
direction string
placement string
gap number
Pixels on static/animated; a physical-unit float on printer.
mask GroupMask
Masked group layers only — the mask geometry in this format.
More about mask
Mask geometry of a masked group layer.
Show child attributes
shape string always
width number
height number
center_x number
center_y number
rx number
ry number
rotation number
radius number | object
animation ElementAnimationTiming
group layers on animated designs only.
More about animation
Animated designs only — the element's own timeline window, in seconds.
Show child attributes
start_at_s number | null
end_at_s number | null
variables DesignVariables
Variables used within the text layers of the design. Keys are variable names (without braces), values are the placeholder as written in the design (e.g. "{name}").
Show child attributes
<variable-name> string
One entry per variable name.
version string
The API version that produced this response, named by release date (vYYYY-MM-DD). Pattern ^v\d{4}-\d{2}-\d{2}$.
More about version
The API version that produced this response, named by release date (vYYYY-MM-DD). Stamped as a top-level field on JSON object bodies, success and error alike, so a client can always tell which contract answered. There is no version-selection parameter — a single version is maintained at a time.
Two kinds of body are not stamped. Array bodies (the listings) carry no envelope. And a body that already has a version key of its own is left alone — which in practice means Banner, whose version is the generated file's integer counter. So GET /banners/{bannerId} and the synchronous generate are the two responses that do not tell you which contract answered.
The value changes when a new version is released. Match the vYYYY-MM-DD shape rather than pinning today's literal, or your client breaks on the next release.
id string always
Unique identifier (name) of the format.
uid string (uuid) always
Unique UUID of the format
width number always
Width of the format
height number always
Height of the format
unit string
Unit of measurement for dimensions
preview_url string (uri)
Preview Image URL of the format
dynamic_image_url string (uri)
URL of the existing dynamic image for this format.
dpi integer
Printer designs only. Render DPI of the format, computed at import time (capped at 300; large formats degrade to stay within the renderer's pixel budget). Read-only — not an import field.
bleed_size number
Printer designs only. Bleed size as a float in the design's unit (mm/in). Always present on a printer format; 0 means the zone is off.
safe_size number
Printer designs only. Safe-zone size as a float in the design's unit (mm/in). Always present on a printer format; 0 means the zone is off.
Errors
Every failure uses the shared error envelope — {id, message, errors?}. Branch on id, never on message. See Errors.
| Status | When |
|---|---|
401 | Unauthorized — missing or invalid API key. |
404 | Format not found (format_not_found). |
429 | Too Many Requests. |
500 | Internal Server Error — an unexpected error occurred on our side. |