Developers

Appearance

Image Generation via URL ​

This is the dynamic image id, not the design id

{dynamicImageId} is the id returned by POST /designs/{designId}/dynamic-image-url — not the design ID. The dynamic_image_url returned by that endpoint already includes the format segment; append your query string to it directly, or construct URLs manually from the {dynamicImageId}.

The URL of a dynamic image variant is:

https://img.abyssale.com/{dynamicImageId}[/{formatNameOrUid}]?{overrides}

The URL is public — no API key, no signature. Anyone holding it can render variants; see the security model.

The query-string grammar ​

Every query parameter is an element override — key=value, where the key names a layer of the design and the value is what you want changed. All available properties are listed under Element Properties.

Long form — layer_name.property_name=value:

?text_title.color=%23FF0000&text_title.font_size=64&company_logo.hidden=true

Short form — layer_name=value, the property being inferred from the layer's type:

Layer typelayer_name=value sets
text, button, qrcode (and any other text-carrying type)payload
image, logoimage_url
ratingrating_score

The exact rules:

  • URL-encode every value — colors' # becomes %23, URLs and spaces must be escaped. An empty value is a hard 400 with a reminder to URL-encode.
  • A key must contain exactly one dot for the long form; keys with more dots are silently ignored.
  • A short-form key must name a layer that exists on the rendered format — otherwise the parameter is silently dropped. Long-form property errors are caught at render and answer 400 Invalid Property: [layer.property] ….
  • If a key is repeated, only the first value is used.
  • A literal \n in a text value becomes a real line break.
  • hidden accepts true/false/1/0 (case-insensitive).

Example — a design with a text_title layer and a company_logo layer:

https://img.abyssale.com/a12b3c4d-5e6f-7890-abcd-ef1234567890?text_title=Welcome&text_title.color=%23FFFFFF&text_title.background_color=%23FF0000&company_logo=https%3A%2F%2Fcdn.example.com%2Flogo.png

How to select a format ​

The optional path segment after the id picks the format — by name or by uid (recommended: it survives renames). Omitted, the design's first format is rendered.

https://img.abyssale.com/{dynamicImageId}/instagram-story
https://img.abyssale.com/{dynamicImageId}/74c5ee10-c9e8-4433-90e3-3320bab8dff0

Format names and uids come from the creation response or Design Details. An unknown format answers 404.

Using text variables ​

As explained in the Text Layer documentation, text variables are replaced dynamically:

?vars.{variableName}={variableValue}

If a text layer contains {username} Smith, then ?vars.username=Alice renders Alice Smith. URL-encode the value like any other.

Output, caching and credits ​

  • The response is the image itself (correct Content-Type, typically image/jpeg; a design defaulting to PNG serves PNG). There is no output-type, quality or size parameter — the design decides.
  • Every unique query string is a distinct variant: rendered once (1 credit), then served from cache (Cache-Control: public, max-age=31104000 — 360 days; plus a server-side cache in test mode). A variant is immutable — to re-render after editing the design, change the query string (any difference creates a new variant, and consumes a new credit).
  • Responses allow any origin (Access-Control-Allow-Origin: *).
  • Finite dataset? Pre-generate every variant once upfront to warm the CDN cache — end users are then served from cache only, with no render latency.

Errors ​

Errors are returned as plain-text responses (no JSON envelope, no fallback image):

StatusWhen
400Empty parameter value, invalid property value (Invalid Property: …), or the dynamic image was deactivated.
401Your plan does not include Dynamic Images.
404Malformed or unknown dynamicImageId, unknown format, or the design no longer exists.
429Per-visitor limit (5 variants/24 h when enable_rate_limit is on), the 10 req/s per-image limit (test mode), or your credit balance is exhausted.
503Maintenance in progress.