Quickstart

Four calls, start to finish: prove your key works, find a design, render an image, open the URL. Everything here uses a design you already built in the Abyssale editor — creating one from JSON is a separate journey, linked at the bottom.

Base URL	https://api.abyssale.com
Auth	x-api-key: {YOUR-API-KEY} on every request
You need	A workspace with at least one static design

Every snippet below reads your key from the environment, so set it once:

export ABYSSALE_API_KEY="{YOUR-API-KEY}"

1. Get your API key

In app.abyssale.com → Workspace settings → API Key → Create new API key. The key appears after ~30 seconds; copy it with the icon on the right. Reading it requires an Admin role — full walkthrough with screenshots on Authentication.

2. Check the key works

curl -X POST -H "x-api-key: $ABYSSALE_API_KEY" https://api.abyssale.com/auth
# {"company":"Acme Inc."}

A 200 returns your workspace name — useful when you hold several keys and need to know which one you're testing. Anything wrong with the key answers 401; the two cases (unauthorized vs api_access_denied) are on Authentication.

3. Get a design ID

curl -H "x-api-key: $ABYSSALE_API_KEY" \
  "https://api.abyssale.com/designs?type=static"

[
  {
    "id": "64238d01-d402-474b-8c2d-fbc957e9d290",
    "name": "Ad campaign fall 2025",
    "type": "static",
    "project_id": "9d1f2b7c-5a44-4c3e-9f21-0b8e6d4a1c73",
    "project_name": "Fall campaigns",
    "preview_url": "https://production-banners.s3-eu-west-1.amazonaws.com/templates/…/a9b3c668.png"
  }
]

Save one id — the rest of this page uses it:

export DESIGN_ID="64238d01-d402-474b-8c2d-fbc957e9d290"

Empty array?

The API only sees designs whose project is on your Projects page. A design at the workspace root is a workspace template and is listed separately — you duplicate it into a project to generate from it.

4. Generate an image

You can render straight away, with no overrides — the design's saved content is used:

curl -X POST \
  -H "x-api-key: $ABYSSALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' \
  "https://api.abyssale.com/banner-builder/$DESIGN_ID/generate"

{
  "id": "5978e8d9-ab34-4735-a2cb-fe95c2c56251",
  "file": {
    "type": "jpeg",
    "cdn_url": "https://cdn.abyssale.com/e0d292f2-…/996739f4-….jpeg",
    "filename": "996739f4-b563-428a-a6e8-dd3cb8bd03d4.jpeg"
  },
  "format": { "id": "facebook-feed", "width": 1200, "height": 628, "unit": "px" }
}

Open file.cdn_url in a browser. That's your first generated asset.

5. Change something

Overrides go in elements, keyed by layer name. To learn the names your design uses, read it back — the response lists every format and every element with its current values (see Design Information):

curl -H "x-api-key: $ABYSSALE_API_KEY" \
  "https://api.abyssale.com/designs/$DESIGN_ID"

Then override the ones you want:

curl -X POST \
  -H "x-api-key: $ABYSSALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "template_format_name": "facebook-feed",
    "elements": {
      "text_title": { "payload": "Summer sale — 40% off", "color": "#FFFFFF" },
      "image": { "image_url": "https://example.com/hero.jpg", "fitting_type": "cover" }
    }
  }' \
  "https://api.abyssale.com/banner-builder/$DESIGN_ID/generate"

Two rules that catch everyone once:

• Every element value must be an object. {"text_title": "Hi"} answers 400 invalid_payload; write {"text_title": {"payload": "Hi"}}.
• template_format_name is optional — omit it and the design's first format is rendered.

Every overridable property, per layer type, is on Element Properties.

When something fails

Every endpoint answers with the same envelope, at every status. Branch on id, never on the message text:

{ "id": "template_not_found", "message": "Design not found" }

Status	Likely id	Meaning
400	invalid_payload	Field-level detail is in errors[]
401	unauthorized	Key unknown, revoked, or missing
404	template_not_found	Wrong design ID, or its project isn't yours
429	rate_limit_exceeded	Out of credits, or the 10 requests per second ceiling
429	request_rate_limited	Too fast for this route's budget — see Rate limits

Full list: Errors.

Where to go next

• More than one image per call — Asynchronous Generation renders every format and every output type (video, GIF, HTML5, print PDF) in one request, and delivers results by webhook.
• Create designs from JSON — Design Import builds a design from a single payload, no editor involved.
• No API call per image — Dynamic Images mints one public URL whose query string is the personalization.
• The whole model — Overview explains projects, designs, formats, layers and visuals, and links to every reference page.
• Staying in JavaScript — the Node.js SDK reference lists every method, the environment variables it reads, and the polling helpers that replace a hand-written wait loop.