Hi there,

Building on top of the Abyssale API has meant hand-rolling HTTP requests since day one — right auth headers, right payload shape, your own retry logic if a request timed out. That's no longer the only option. Abyssale just shipped its first official SDKs:

• @abyssale/sdk for Node.js/TypeScript (now at 1.3.0),
• and abyssale for Python (now at 1.1.0).

Both SDKs wrap the core REST API — designs, generation, projects, workspace templates, exports, and, as of this release, webhook signing — in a typed, idiomatic client for their respective language, so integrating Abyssale into a codebase looks like using any other well-maintained SDK, not stitching together fetch calls.

@abyssale/sdk for Node.js / TypeScript

Install it with:

npm install @abyssale/sdk

Node.js 20.3 or later is required — not just Node 20. The retry middleware relies on AbortSignal.any, which only landed in 20.3.0, so installing on 20.0–20.2 succeeds but fails at runtime.

Configuration is entirely environment-variable driven — no constructor, no setup step beyond setting ABYSSALE_API_KEY. Note that the SDK throws at import time if that variable isn't set, which occasionally surprises people in test environments:

import abyssale from '@abyssale/sdk';

const { data, error } = await abyssale.generateImage('your-design-id', {
  elements: {
    title: { payload: 'Hello World' },
    background: { background_color: '#FF0000' },
  },
  template_format_name: 'facebook-post',
});

console.log(data?.file.cdn_url);

A few things worth knowing:

• Never throws on HTTP errors. Every method returns { data, error, response }, so error handling stays explicit instead of relying on try/catch around network calls.
• Automatic retries, deliberately narrow. 5xx is retried on reads only — a generation POST is never repeated, since a timeout doesn't mean the render didn't happen, and retrying it could bill you twice. A 429 carrying a Retry-After header gets the full retry ladder; a bare 429 gets a single one-second probe, since that status alone can mean either "out of credits" or "hit the gateway's per-second ceiling." feature_not_in_plan is never retried. Retry count is configurable via ABYSSALE_MAX_RETRIES.
• Built-in polling helpers. waitForGenerationRequest and waitForDuplicationRequest handle the poll loop for async jobs (multi-format generation, multi-page PDFs, workspace template duplication) so you don't have to write your own polling logic.
• Fully typed. Every request and response type is generated directly from the OpenAPI spec, so IDEs get full autocomplete on every field.
• Webhook signing, new in this release. Three methods for managing your webhook signing secret (list, create, delete), plus a signature verifier importable on its own from @abyssale/sdk/webhooks — it needs no API key at all, since verifying a signature is pure local cryptography, not an API call.

One caveat: the design-import surface is deliberately left out of the SDK for now, since it's still in Alpha and the format may change — the OpenAPI spec used to generate the client strips those endpoints so a routine regeneration can't accidentally reintroduce them before things stabilize.

→ npmjs.com/package/@abyssale/sdk

→ github.com/getabyssale/abyssale-sdk

→ developers.abyssale.com/sdks/nodejs

Abyssale for Python

The same core coverage is now available for Python teams, published to PyPI as abyssale, at 1.1.0.

pip install abyssale

from abyssale import abyssale, AbyssaleAPIError

try:
    banner = abyssale.generate_image(
        "your-design-id",
        elements={
            "title": {"payload": "Hello World"},
            "background": {"background_color": "#FF0000"},
        },
        template_format_name="facebook-post",
    )
    print(banner.file.cdn_url)
except AbyssaleAPIError as e:
    print("API error:", e.id)

The two SDKs are built on the same underlying API, but they don't handle errors the same way. Where the Node SDK returns { data, error } and never throws, the Python SDK raises AbyssaleAPIError on failure, carrying a machine-readable id you can match against. Worth keeping in mind if you're used to one and picking up the other.

Request bodies in Python are plain dicts by design rather than generated model classes — the elements schema is an anyOf with no discriminator, so a strict model would risk mis-coercing valid payloads.

Like the Node SDK, this release also adds webhook signing support via abyssale.webhooks: the same list/create/delete methods for your signing secret, plus a signature verifier that works without an API key configured.

And the same Alpha caveat applies here too: design-import endpoints are intentionally excluded from the generated client while that feature's format is still settling.

→ pypi.org/project/abyssale

→ github.com/getabyssale/abyssale-python-sdk

→ developers.abyssale.com/sdks/python

Why this matters

Every integration built directly against the raw REST API was solving the same problems over and over: retry logic that doesn't double-bill you, polling for async jobs, verifying webhook signatures by hand. With official, typed SDKs for both Node.js and Python — and now first-class webhook signing in both — that work is done once, centrally, and maintained alongside the API itself.

Questions about migrating an existing integration to one of the SDKs? Reach out at help@abyssale.com.