# Abyssale Developer Documentation > Official API reference and developer guides for Abyssale — a creative automation platform for generating images, videos, print-ready PDFs, and HTML5 banner ads programmatically via REST API, dynamic image URLs, or webhooks. Designs are created in the editor or from JSON via Design Import, then rendered synchronously (one static image) or asynchronously (many formats and every output type). - Base URL: https://api.abyssale.com - Auth: `x-api-key` header on every request. Test with `POST /auth`. - Rate limits: a global ceiling of 10 requests/second, plus a per-workspace budget per endpoint tier (polling 600/min, read 120/min, validation 120/min, write 60/min). Generation endpoints have no tier budget. - Errors: one envelope on every endpoint at every status — `{id, message, errors?}`. Branch on `id`, never on `message`. There is no `403`; an unentitled key answers `401 api_access_denied`. - Design types: `static`, `animated`, `printer`, `printer_multipage`. The type decides the output file types and whether the design is authored in pixels/hex or physical units/CMYK. - Webhooks: deliveries are signed with `X-Abyssale-Signature: t=…,v1=…` (HMAC-SHA256 over `"v1:webhook:" + t + "." + raw_body`) once the workspace has fetched a secret from `GET /signing-secret`; signing is opt-in and deliveries are unsigned until then. Verify against the RAW body, check every `v1`, and deduplicate on `X-Abyssale-Delivery-Id`. ## Getting Started - [Introduction](https://developers.abyssale.com/): Official developer documentation for Abyssale — generate images, videos, HTML5 banner ads, and PDFs via REST API, dynamic URLs, or webhooks. - [Quickstart](https://developers.abyssale.com/rest-api/quickstart): Go from an Abyssale API key to a generated image in four calls. The shortest path through the REST API, with copy-pasteable cURL, Node.js and Python. ## REST API - [Overview](https://developers.abyssale.com/rest-api/overview-rest-api): Abyssale REST API overview: the object model (projects, designs, formats, layers), creating designs via import, generating assets sync or async, versioning, errors, and where every concept is documented. - [Authentication](https://developers.abyssale.com/rest-api/authentication): How to authenticate Abyssale API requests using the x-api-key header. Generate and manage API keys from your Workspace settings. - [Rate limits](https://developers.abyssale.com/rest-api/rate-limits): Abyssale REST API rate limits: the global 10 requests/second ceiling, the per-endpoint budget for every endpoint, the X-RateLimit headers to pace against, and how to tell a throttle apart from a credit or plan refusal. - [Credits](https://developers.abyssale.com/rest-api/credits): What an Abyssale API request costs: generation credits and AI credits, the per-format rule, the price of every output type, how print PDFs are billed by pixel area, and what happens when a balance runs out. - [Layers Overview](https://developers.abyssale.com/rest-api/layers-overview): Why layer properties are documented twice — once for generation-time overrides, once for import-time authoring — and how the two relate. - [Designs](https://developers.abyssale.com/rest-api/designs/): List all designs in your Abyssale workspace and retrieve details on design types: Static, Animated GIF, Video, HTML5, and Print. - [List Designs](https://developers.abyssale.com/rest-api/designs/list-designs): GET /designs — list every design in your Abyssale workspace, filter by project or design type, with visibility rules and response shape. - [Design Details](https://developers.abyssale.com/rest-api/designs/design-details): Retrieve details for a specific Abyssale design including its name, type, formats, and dynamic image URL via GET /designs/{designId}. - [Design Format Details](https://developers.abyssale.com/rest-api/designs/design-format-details): Retrieve format-level details for an Abyssale design including width, height, and format name via GET /designs/{designId}/formats/{formatId}. - [Designs vs Workspace Templates](https://developers.abyssale.com/rest-api/designs/vs-workspace-templates): The difference between a design and a workspace template in the Abyssale API: which one you have, how to list each, and how to convert one into the other. - [Export a Design](https://developers.abyssale.com/rest-api/designs/as-import): Export an existing Abyssale design as a ready-to-import JSON payload. Returns a POST /designs/import/json body that recreates the design as-is — use it to clone, version, fork, or diff designs. Supports static, printer, animated, and multi-page print designs. - [Design Import](https://developers.abyssale.com/rest-api/designs/import/): Create an Abyssale design from a single JSON payload. Tool-agnostic, AI-agent friendly, and built on the same element-centric schema the Designs API returns. - [Create Import](https://developers.abyssale.com/rest-api/designs/import/create): Submit a design structure to Abyssale's JSON Design Import endpoint. Returns the import ID, links, and one upload descriptor per asset that needs uploading. - [Upload Assets](https://developers.abyssale.com/rest-api/designs/import/upload-assets): Upload image and logo layer assets to the presigned S3 URLs returned by the Create Import endpoint. - [Validate Import](https://developers.abyssale.com/rest-api/designs/import/validate): Validate an uploaded design import and queue it for backend processing. Verifies every expected S3 asset is in place and returns a direct link to the import in the Abyssale dashboard. - [Check Status](https://developers.abyssale.com/rest-api/designs/import/status): Poll the current status of a design import. Tracks the full lifecycle from WAITING_FOR_VALIDATION through DONE or FAILED, with polling-cadence guidance and structured warnings. - [Warnings & Error Codes](https://developers.abyssale.com/rest-api/designs/import/status-warnings-and-errors): Reference catalog of Design Import warning codes and error codes — the error envelope, per-code meanings, and the build-phase failure codes. - [Example designs](https://developers.abyssale.com/rest-api/designs/import/examples): Sixteen ready-to-import Abyssale designs — static, animated and print. Download the JSON, set your project, POST it. - [Animated Imports](https://developers.abyssale.com/rest-api/designs/import/animated): Import animated (video) designs with type: animated. Authored in pixels and hex colors like static, plus a required animation timeline, per-layer tweens, and video/audio layers. - [Print Imports](https://developers.abyssale.com/rest-api/designs/import/print): Import single-page print PDF designs with type: printer. Authored in physical units (mm/in), pt font sizes, and CMYK colors, with bleed and safe-zone support. - [Multi-Page Print Imports](https://developers.abyssale.com/rest-api/designs/import/printer-multipage): Import multi-page print PDF designs with type: printer_multipage. Print setup is declared once at the top level — every page shares the same size — and pages[] carries only per-page background color and layers. - [Colors & Gradients](https://developers.abyssale.com/rest-api/designs/import/colors): Color and gradient grammar shared across the API — hex, Abyssale's linear-gradient syntax, and CMYK for print designs. - [Layer Types](https://developers.abyssale.com/rest-api/designs/import/layer-types/): Reference for every layer type accepted by Design Import — text, image, logo, shape, button, rating, qrcode, group, illustration, plus video and audio on animated designs. - [Text](https://developers.abyssale.com/rest-api/designs/import/layer-types/text): The `text` layer type for Design Import — rich text that auto-fits its bounding box. - [Image](https://developers.abyssale.com/rest-api/designs/import/layer-types/image): The `image` layer type for Design Import — raster or vector image with fitting, masks, filters, and overlays. - [Logo](https://developers.abyssale.com/rest-api/designs/import/layer-types/logo): The `logo` layer type for Design Import — a simplified image layer for brand logos. - [Shape](https://developers.abyssale.com/rest-api/designs/import/layer-types/shape): The `shape` layer type for Design Import — a vector shape from 24 built-in geometries. - [Button](https://developers.abyssale.com/rest-api/designs/import/layer-types/button): The `button` layer type for Design Import — a text label on a filled, rounded background. - [Rating](https://developers.abyssale.com/rest-api/designs/import/layer-types/rating): The `rating` layer type for Design Import — a row of stars indicating a 0–100% rating. - [QR Code](https://developers.abyssale.com/rest-api/designs/import/layer-types/qrcode): The `qrcode` layer type for Design Import — a scannable QR code with an optional center icon. - [Group](https://developers.abyssale.com/rest-api/designs/import/layer-types/group): The `group` layer type for Design Import — a container binding several layers together, with optional auto-layout and masking. - [Illustration](https://developers.abyssale.com/rest-api/designs/import/layer-types/illustration): The `illustration` layer type for Design Import — a named SVG from a built-in library, optionally recoloured. - [Video](https://developers.abyssale.com/rest-api/designs/import/layer-types/video): The `video` layer type for Design Import — an MP4 or WebM clip on an animated design, with mute and opacity. - [Audio](https://developers.abyssale.com/rest-api/designs/import/layer-types/audio): The `audio` layer type for Design Import — an MP3 or WAV track on an animated design, with volume and mute. - [Workspace Templates](https://developers.abyssale.com/rest-api/workspace-templates): List your Abyssale workspace templates and their categories, and duplicate a template into a project to turn it into a generatable design. - [Use a Workspace Template](https://developers.abyssale.com/rest-api/workspace-templates/use): Duplicate a workspace template into a project with POST /workspace-templates/{id}/use — the asynchronous flow that turns a template into a ready-to-generate design. - [Generation](https://developers.abyssale.com/rest-api/generation/): Abyssale Generation API overview: synchronous single-image generation and asynchronous batch generation for images, videos, GIFs, print PDFs and HTML5 banners — inputs, results, costs and every option in one place. - [Design Information](https://developers.abyssale.com/rest-api/generation/design-information): How to identify design IDs and format names for use in Abyssale generation API requests. - [Generate Single Image](https://developers.abyssale.com/rest-api/generation/synchronous-generation/generate-single-image): Synchronously generate a single image via POST /banner-builder/{designId}/generate. Supports JPEG, PNG, WEBP, AVIF, and Web PDF output formats. - [Asynchronous](https://developers.abyssale.com/rest-api/generation/asynchronous-generation/): Asynchronously generate multiple formats of images, videos, GIFs, HTML5 banners, or PDFs in one API call. Results are delivered via webhook callback. - [Multi-Format Images](https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-multi-format-images): Generate multiple image formats asynchronously from a single Abyssale design. Supports JPEG, PNG, WEBP, AVIF output with webhook notification on completion. - [Multi-Format Videos](https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-multi-format-videos): Generate multiple video formats asynchronously from an Abyssale Animated design. Supports MP4 output with webhook notification on completion. - [Multi-Format Animated GIFs](https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-multi-format-animated-gifs): Generate multiple animated GIF formats asynchronously from an Abyssale Animated design. Webhook notification sent on completion. - [HTML5 Banner Ads](https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-html5-banner-ads): Generate multiple HTML5 banner ad formats asynchronously from an Abyssale HTML5 design. Returns a ZIP archive via webhook callback. - [Multi-Format PDFs](https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-multi-format-pdfs-for-printing): Generate multiple print-quality PDF formats asynchronously from an Abyssale printer design. CMYK color support. one PDF link per format, delivered via webhook. - [Multi-Page PDF](https://developers.abyssale.com/rest-api/generation/asynchronous-generation/generate-multi-page-pdf-for-printing): Generate a single multi-page print PDF asynchronously from an Abyssale printer_multipage design. Each element set becomes one page, delivered as one PDF link via webhook. - [Visual Versioning](https://developers.abyssale.com/rest-api/generation/visual-versioning): Use Abyssale visual versioning to update previously generated images without changing their public sharing URL. Requires the generation ID. - [Element Properties](https://developers.abyssale.com/rest-api/generation/element-properties): Customize Abyssale design elements via API: Text, Button, Image, Logo, Shape, Rating, Illustration, QR Code, Video, and Audio properties reference. - [Root](https://developers.abyssale.com/rest-api/generation/element-properties/root): Customize the background of every Abyssale design format via the root element: background color — solid hex, linear gradient, or CMYK print colors. - [Text](https://developers.abyssale.com/rest-api/generation/element-properties/text): Text element properties for Abyssale API: font, color, size, weight, alignment, stroke, shadow, auto-resize, line height, and partial text markup syntax. - [Button](https://developers.abyssale.com/rest-api/generation/element-properties/button): Button element properties for Abyssale API: label text, font, color, background, border, corner radius, and shadow customization. - [Image](https://developers.abyssale.com/rest-api/generation/element-properties/image): Image element properties for Abyssale API: image URL, fitting type (cover, contain, fill), alignment, opacity, and overlay color. - [Logo](https://developers.abyssale.com/rest-api/generation/element-properties/logo): Logo element properties for Abyssale API: logo image URL, fitting type, alignment, and automatic background removal. - [Shape](https://developers.abyssale.com/rest-api/generation/element-properties/shape): Shape element properties for Abyssale API: fill color, stroke, gradient, opacity, and shadow customization for geometric design elements. - [Rating](https://developers.abyssale.com/rest-api/generation/element-properties/rating): Rating element properties for Abyssale API: numeric value, maximum stars, fill color, and empty state color for star or custom rating displays. - [Illustration](https://developers.abyssale.com/rest-api/generation/element-properties/illustration): Illustration element properties for Abyssale API: select and customize illustrations from the Abyssale library by ID, color, and opacity. - [QR Code](https://developers.abyssale.com/rest-api/generation/element-properties/qr-code): QR Code element properties for Abyssale API: destination payload, foreground and background colors, and the center icon. - [Video](https://developers.abyssale.com/rest-api/generation/element-properties/video): Video element properties for Abyssale API: video URL, trim via URL query, audio muting and visibility for animated designs. - [Audio](https://developers.abyssale.com/rest-api/generation/element-properties/audio): Audio element properties for Abyssale API: audio URL, volume, and playback speed for adding soundtracks to MP4 generations. - [Errors](https://developers.abyssale.com/rest-api/generation/errors): Every error the Abyssale Generation API returns: status codes, machine-readable ids, what triggers each one and how to react. - [Fonts](https://developers.abyssale.com/rest-api/fonts): List all fonts available in your Abyssale workspace, including Google Fonts and custom uploaded fonts, via the GET /fonts endpoint. - [Asset Export](https://developers.abyssale.com/rest-api/asset-export): Asynchronously export previously generated Abyssale assets — images, videos, GIFs, HTML5 bundles, print PDFs — as a single ZIP archive, delivered via webhook. - [Projects](https://developers.abyssale.com/rest-api/projects): List and create projects in your Abyssale workspace to organize designs. Use the Projects API to manage project collections programmatically. - [Annexes](https://developers.abyssale.com/rest-api/annexes): Complete list of AI-detectable object labels supported by Abyssale's auto-focus feature for smart image cropping and composition. - [Endpoint Catalog](https://developers.abyssale.com/rest-api/endpoint-catalog): Every Abyssale REST API endpoint in one table — method, path, what it does, its rate-limit tier, and a link to its full guide. - [Changelog](https://developers.abyssale.com/rest-api/changelog): Dated changelog for the Abyssale REST API — breaking changes, additions, fixes and deprecations, newest first. ## SDKs - [Node.js](https://developers.abyssale.com/sdks/nodejs): Reference for @abyssale/sdk, the official Node.js and TypeScript SDK: installation, environment configuration, every method with its endpoint, error handling, retry behaviour and the polling helpers. - [Python](https://developers.abyssale.com/sdks/python): Reference for abyssale, the official Python SDK: installation, configuration, every method with its endpoint, the exception hierarchy, retry behaviour and the polling helpers. ## Dynamic Images - [Overview](https://developers.abyssale.com/dynamic-images/overview-dynamic-images): Abyssale Dynamic Images overview: mint one public URL per static design, then render personalized variants on the fly with query parameters — no API call per image. - [Create a Dynamic Image by API](https://developers.abyssale.com/dynamic-images/create-a-dynamic-image-by-api): Create a Dynamic Image URL for an Abyssale design via POST /designs/{designId}/dynamic-image-url. Only one dynamic image is allowed per design. - [Image Generation via URL](https://developers.abyssale.com/dynamic-images/image-generation-via-url): Generate Abyssale dynamic image variants by appending element overrides as URL query parameters — grammar, shorthand keys, format selection, variables, caching and errors. ## Webhooks - [Overview](https://developers.abyssale.com/webhooks/overview-webhooks): Abyssale webhooks: receive real-time HTTP POST notifications when image generation, exports, or design changes complete. Includes payload structure and setup guide. - [Signature verification](https://developers.abyssale.com/webhooks/signature-verification): Verify Abyssale webhook deliveries with the X-Abyssale-Signature header: fetch a signing secret, check the HMAC-SHA256 signature, rotate the secret, and deduplicate on the delivery id. - [All Events](https://developers.abyssale.com/webhooks/events/): All Abyssale webhook event types: NEW_BANNER (image ready), NEW_BANNER_BATCH (batch ready), NEW_EXPORT (ZIP ready), TEMPLATE_STATUS (design changed). - [Banner Events](https://developers.abyssale.com/webhooks/events/banner-events): Abyssale NEW_BANNER and NEW_BANNER_BATCH webhook event payloads. Triggered when a single image or batch generation completes successfully. - [Global Events](https://developers.abyssale.com/webhooks/events/global-events): Abyssale NEW_EXPORT webhook event payload. Triggered when an asynchronous ZIP export of generated images is ready for download. - [Design Events](https://developers.abyssale.com/webhooks/events/design-events): Abyssale TEMPLATE_STATUS webhook event payload. Triggered when a design is published or its status changes in the Abyssale workspace. ## MCP - [Overview](https://developers.abyssale.com/mcp/overview): Abyssale's remote MCP server lets Claude Code, Claude.ai, ChatGPT/Codex, and Cursor browse your designs and projects, generate banners, videos and PDFs, and import new designs — without writing code against the REST API. - [Authentication](https://developers.abyssale.com/mcp/authentication): How the Abyssale MCP server authenticates a connecting client via OAuth, what role you need, and what each permission scope grants. - [Skills](https://developers.abyssale.com/mcp/skills): Ready-made Claude Skills that teach an AI client complete Abyssale workflows on top of the MCP server — install one and describe what you want instead of chaining tool calls yourself. - [Tools reference](https://developers.abyssale.com/mcp/tools-reference): Every tool the Abyssale MCP server exposes: purpose, parameters, required scope, and an example call and response. - [Permissions](https://developers.abyssale.com/mcp/permissions): What each Abyssale MCP tool can actually do — read-only vs. mutating, credit spend, and what data it touches — to inform before you authorize it. - [Changelog](https://developers.abyssale.com/mcp/changelog): Version history of the Abyssale MCP server. Follows Keep a Changelog and Semantic Versioning. ## API Reference - [All endpoints](https://developers.abyssale.com/api-reference/): Every Abyssale REST API endpoint with its parameters, request body, responses, and error codes — generated from the OpenAPI specification. ## Authentication - [Verify an API key](https://developers.abyssale.com/api-reference/verifyApiKey): Check that an API key is usable, and find out which workspace it belongs to. ## Designs - [List all designs](https://developers.abyssale.com/api-reference/listDesigns): Retrieve all designs available in your Abyssale workspace. - [Get design details](https://developers.abyssale.com/api-reference/getDesign): Retrieve the full specification of a design: its formats (dimensions and preview URLs), all configurable elements with their properties, and any template variables defined in text layers. - [Get format details](https://developers.abyssale.com/api-reference/getDesignFormat): Retrieve detailed information for a specific format within a design, including dimensions, unit, preview URL, dynamic image URL, element layout, and variables. ## Asset Generation - [Generate an image (synchronous)](https://developers.abyssale.com/api-reference/generateImage): Synchronously generate a single image from a design. - [Generate multiple formats (asynchronous)](https://developers.abyssale.com/api-reference/generateMultiFormatMedia): Asynchronously generate multiple formats of an image, video, GIF, HTML5 banner, or PDF in a single API call. - [Generate a multi-page PDF (asynchronous)](https://developers.abyssale.com/api-reference/generateMultiPagePdf): Asynchronously generate a multi-page print-ready PDF from a printer_multipage design. - [Poll async generation request status](https://developers.abyssale.com/api-reference/getGenerationRequest): Poll the status of an asynchronous generation request. ## Webhooks - [Get the webhook signing secret](https://developers.abyssale.com/api-reference/getSigningSecret): Retrieve the workspace's webhook signing secret, creating it on the first call and returning the same value on every call after that. - [Rotate the webhook signing secret](https://developers.abyssale.com/api-reference/rotateSigningSecret): Issue a new signing secret and keep the previous one valid for 24 hours. - [End the rotation overlap early](https://developers.abyssale.com/api-reference/revokeSigningSecret): Invalidate the previous secret, ending the 24-hour overlap early. ## Fonts - [List available fonts](https://developers.abyssale.com/api-reference/listFonts): Retrieve all fonts available in your Abyssale workspace, including Google Fonts and any custom fonts you have uploaded. ## Credits - [Get remaining credits](https://developers.abyssale.com/api-reference/getCredits): Remaining generation and AI credits for the caller's workspace, for the current billing period. ## Exports - [Export generated assets as a ZIP archive (asynchronous)](https://developers.abyssale.com/api-reference/exportBanners): Asynchronously package a set of previously generated assets — any output type (JPEG, PNG, WEBP, AVIF, PDF, MP4, GIF, HTML5 bundle) — into a single ZIP archive for download. ## Files - [Get generated file](https://developers.abyssale.com/api-reference/getFile): Retrieve the metadata and download URLs for a previously generated file (image, video, GIF, HTML5 banner, or PDF). ## Projects - [List projects](https://developers.abyssale.com/api-reference/listProjects): Retrieve all projects in your workspace. - [Create a project](https://developers.abyssale.com/api-reference/createProject): Create a new project to organize your designs. ## Workspace Templates - [List all workspace templates](https://developers.abyssale.com/api-reference/listWorkspaceTemplates): Retrieve the organisation-level master designs shared across your workspace. - [List workspace template categories](https://developers.abyssale.com/api-reference/listWorkspaceTemplateCategories): The categories that group your workspace templates. - [Duplicate a workspace template into a project](https://developers.abyssale.com/api-reference/duplicateWorkspaceTemplate): Copy a shared workspace template into one of your projects, creating an editable design instance. - [Poll template duplication request status](https://developers.abyssale.com/api-reference/getDuplicationRequest): Poll the status of a template duplication request. ## Design Import - [List imports](https://developers.abyssale.com/api-reference/listDesignImports): List this company's JSON template imports, newest first. - [Create a design from JSON](https://developers.abyssale.com/api-reference/createDesignImport): Submit a template structure as JSON. - [Get import status](https://developers.abyssale.com/api-reference/getDesignImport): Poll the status of a JSON template import. - [Validate an import and queue it](https://developers.abyssale.com/api-reference/validateDesignImport): Call this after every entry of uploads[] has been POSTed to S3. - [Export a design as an import payload](https://developers.abyssale.com/api-reference/getDesignAsImport): Return an existing design — any type, printer_multipage included — serialized into the exact shape POST /designs/import/json accepts. ## Dynamic Images - [Create a dynamic image URL](https://developers.abyssale.com/api-reference/createDynamicImageUrl): Creates a dynamic image URL for a given design (static designs only). ## Optional - [OpenAPI reference](https://developers.abyssale.com/api-reference/): Full request and response schemas for every endpoint, browsable. Every operation is also listed individually below. - [OpenAPI specification (YAML)](https://developers.abyssale.com/api.yaml): The machine-readable spec behind the reference — operation ids, parameters, schemas. The exact file the reference pages are generated from. - [Node.js SDK on npm](https://www.npmjs.com/package/@abyssale/sdk): `npm install @abyssale/sdk` — the official Node/TypeScript client. - [Python SDK on PyPI](https://pypi.org/project/abyssale/): `pip install abyssale` — the official Python client. - [Every page in one file](https://developers.abyssale.com/llms-full.txt): The full text of every page listed above, in the same order — fetch this instead of crawling.