Create a Dynamic Image by API

Creates a dynamic image URL for a given design. Only one dynamic image is allowed per design — subsequent calls return the existing URL without modifying it.

Also available from Design Details

The dynamic_image_url for each format is also returned by the Get Design Details endpoint once the dynamic image has been created.

POST/designs/{designId}/dynamic-image-urlAPI Reference

Path parameters

Parameter	Type	Required	Description
designId	string (uuid)	Yes	Unique identifier of the design. Must be a static design.

Request body

The request body is optional — omit it, or send {}, to keep both defaults.

Field	Type	Required	Description
enable_rate_limit	boolean	No	Defaults to false. Caps each visitor at 5 generations per 24 h, counted per IP + User-Agent. Requests served from cache do not count. Applies in both modes — set it on any URL exposed to an untrusted audience.
enable_production_mode	boolean	No	Defaults to false (test mode). See the table below.

Production mode drops the per-image rate limit and stops recording variants in your workspace, which also means no NEW_BANNER webhook. Full comparison: Test mode vs production mode.

Sample request

curl -X POST \
  -H "x-api-key: {YOUR-API-KEY}" \
  -H "Content-Type: application/json" \
  -d '{"enable_rate_limit": true, "enable_production_mode": true}' \
  https://api.abyssale.com/designs/{designId}/dynamic-image-url

Response

Field	Type	Description
id	string (uuid)	Unique ID of the dynamic image.
design_id	string (uuid)	ID of the associated design.
formats	array	List of formats available for this dynamic image. Each item includes id, uid, width, height, unit, and dynamic_image_url.

Response example

Idempotent

Returns 200 if a dynamic image already exists for the design (idempotent), or 201 on first creation. The response body is identical in both cases.

{
  "id": "a12b3c4d-5e6f-7890-abcd-ef1234567890",
  "design_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "formats": [
    {
      "id": "facebook-post",
      "uid": "9b57d65e-eb2c-4a74-a51e-4482917c248a",
      "width": 1200,
      "height": 1200,
      "unit": "px",
      "dynamic_image_url": "https://img.abyssale.com/a12b3c4d-5e6f-7890-abcd-ef1234567890/9b57d65e-eb2c-4a74-a51e-4482917c248a"
    },
    {
      "id": "instagram-story",
      "uid": "c4d81f22-30aa-4e17-9d61-7c5a2f0b8e93",
      "width": 1080,
      "height": 1920,
      "unit": "px",
      "dynamic_image_url": "https://img.abyssale.com/a12b3c4d-5e6f-7890-abcd-ef1234567890/c4d81f22-30aa-4e17-9d61-7c5a2f0b8e93"
    }
  ]
}

The URL carries the format's uid

The returned dynamic_image_url addresses the format by its uid. At render time the path segment accepts either the uid or the format name (…/facebook-post works too), and omitting it entirely renders the design's first format.

Errors

Status	id	When
400	template_not_static	The design is not a static design — dynamic images support static only.
400	template_not_active	The design is deleted or otherwise not active.
404	template_not_found	Unknown design UUID, or a design belonging to another workspace.

Related

• Image Generation via URL — use the dynamic_image_url to generate images
• Design Details — retrieve dynamic_image_url for each format once created
• Overview — Dynamic Images — credits, caching, and bandwidth
• Node.js SDK · Python SDK — every method, config, retries and the polling helpers