Create a dynamic image URL
Sample request
curl -X POST "https://api.abyssale.com/designs/$DESIGN_ID/dynamic-image-url" \
-H "x-api-key: $ABYSSALE_API_KEY"import abyssale from '@abyssale/sdk';
const designId = 'YOUR_DESIGN_ID';
const { data, error } = await abyssale.createDynamicImageUrl(designId);
if (error) console.error(error.id, error.message);
else console.log(data);from abyssale import Abyssale
design_id = "YOUR_DESIGN_ID"
with Abyssale() as client:
result = client.create_dynamic_image_url(design_id)
print(result)Example 200 response
{
"id": "a12b3c4d-5e6f-7890-abcd-ef1234567890",
"design_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"formats": [
{
"id": "one-format",
"uid": "11111111-2222-3333-4444-555555555555",
"width": 3333,
"unit": "px",
"height": 666,
"dynamic_image_url": "https://img.abyssale.com/a12b3c4d-5e6f-7890-abcd-ef1234567890/one-format"
},
{
"id": "another-format",
"uid": "66666666-7777-8888-9999-000000000000",
"width": 1920,
"unit": "px",
"height": 1080,
"dynamic_image_url": "https://img.abyssale.com/a12b3c4d-5e6f-7890-abcd-ef1234567890/another-format"
}
]
}Example 201 response
{
"id": "a12b3c4d-5e6f-7890-abcd-ef1234567890",
"design_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"formats": [
{
"id": "one-format",
"uid": "11111111-2222-3333-4444-555555555555",
"width": 3333,
"unit": "px",
"height": 666,
"dynamic_image_url": "https://img.abyssale.com/a12b3c4d-5e6f-7890-abcd-ef1234567890/one-format"
},
{
"id": "another-format",
"uid": "66666666-7777-8888-9999-000000000000",
"width": 1920,
"unit": "px",
"height": 1080,
"dynamic_image_url": "https://img.abyssale.com/a12b3c4d-5e6f-7890-abcd-ef1234567890/another-format"
}
]
}Example 400 error response
{
"id": "out_of_range",
"message": "formats[0].width: Must be greater than or equal to 1 and less than or equal to 5000.",
"errors": [
{
"path": "formats[0].width",
"code": "out_of_range",
"message": "Must be greater than or equal to 1 and less than or equal to 5000.",
"expected": {
"min": 1,
"max": 5000
},
"received": 99999999
}
]
}Creates a dynamic image URL for a given design (static designs only). Only one dynamic image is allowed per design — subsequent calls return the existing dynamic image (200 instead of 201). enable_rate_limit limits each visitor to 5 generations per 24 h, counted from a hash of IP + User-Agent; requests answered from cache do not count against it. enable_production_mode switches from test mode (variants saved to the workspace, 10 req/s per image) to production mode (built for scale: no per-image throttle, variants not saved). Production mode is not unlimited — the global 10 requests/second ceiling, your workspace credits and your bandwidth all still apply, and bandwidth is measured on every delivery including cache hits. A non-static design answers 400 template_not_static, and a design that is not in the CREATED status answers 400 template_not_active.
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.
Request body
enable_rate_limit boolean
Enable API rate limiting for this dynamic image Defaults to false.
enable_production_mode boolean
Enable Production mode for this dynamic image Defaults to false.
Response 200
Existing dynamic image retrieved
id string (uuid) always
Unique ID of the dynamic image
design_id string (uuid) always
Design ID associated with this dynamic image
formats array of DynamicImageFormat always
List of formats available for this dynamic image
Show child attributes
id string always
Identifier (name) of the format.
uid string (uuid) always
Unique UUID of the format — the last path segment of dynamic_image_url.
width number always
height number always
unit string always
Always px here; a dynamic image is only available on static designs.
dynamic_image_url string (uri) always
The dynamic image URL for this format.
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.
Response 201
Dynamic image successfully created
id string (uuid) always
Unique ID of the dynamic image
design_id string (uuid) always
Design ID associated with this dynamic image
formats array of DynamicImageFormat always
List of formats available for this dynamic image
Show child attributes
id string always
Identifier (name) of the format.
uid string (uuid) always
Unique UUID of the format — the last path segment of dynamic_image_url.
width number always
height number always
unit string always
Always px here; a dynamic image is only available on static designs.
dynamic_image_url string (uri) always
The dynamic image URL for this format.
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.
Errors
Every failure uses the shared error envelope — {id, message, errors?}. Branch on id, never on message. See Errors.
| Status | When |
|---|---|
400 | The design is not static (template_not_static) or not active (template_not_active). |
401 | Unauthorized — missing or invalid API key. |
404 | Design not found (template_not_found). |
429 | Too Many Requests. |
500 | Internal Server Error — an unexpected error occurred on our side. |