Skip to main content

Abyssale Python SDK

Official Python client for the Abyssale API — generate images, videos, HTML5 banners and print-ready PDFs from your designs.

📖 Full reference: developers.abyssale.com/sdks/python — every method, configuration, error handling, retry behaviour and the polling helpers.

Install

pip install abyssale

Requires Python 3.10+. This release models API version v2026-10-19 — see CHANGELOG.md for the SDK-to-API version pairing, and abyssale.__api_version__ to read it at runtime.

Quick start

from abyssale import Abyssale

with Abyssale() as client:                      # reads ABYSSALE_API_KEY
    design = client.get_design("64238d01-d402-474b-8c2d-fbc957e9d290")

    banner = client.generate_image(design.id, {
        "elements": {"text_title": {"payload": "Summer sale — 40% off"}},
        "template_format_name": "facebook-feed",
    })
    print(banner.file.cdn_url)

Async is the same surface:

import asyncio
from abyssale import AsyncAbyssale

async def main():
    async with AsyncAbyssale() as client:
        accepted = await client.generate_multi_format_media(design_id, {
            "elements": {"text_title": {"payload": "Summer sale — 40% off"}},
            "template_format_names": ["facebook-feed", "instagram-post"],
        })
        result = await client.wait_for_generation_request(accepted.generation_request_id)
        for banner in result.banners:
            print(banner.file.cdn_url)

asyncio.run(main())

Methods return the result and raise on failure. Branch on the API's machine-readable id, never on the message:

from abyssale import AbyssaleAPIError

try:
    client.generate_image(design_id, {...})
except AbyssaleAPIError as err:
    print(err.status, err.id, err.message, err.errors)

What you get

  • 22 methods, sync and async, one per API operation, named after its operationId snake_cased, plus two wait_for_* polling helpers — every method
  • Typed responses, permissive request bodies — responses are pydantic models that never fail a 200, request bodies pass through untouched — request bodies and responses
  • A typed exception hierarchy carrying the API's id, errors and retry_after — errors
  • Narrow retries and a per-attempt timeout, configurable per client or by environment (ABYSSALE_API_KEY, ABYSSALE_TIMEOUT_MS, ABYSSALE_MAX_RETRIES, ABYSSALE_MAX_RETRY_WAIT_MS) — configuration · what is retried, and what is not
  • Webhook signature verification in abyssale.webhooks, which imports only the standard library — no client and no API key needed in a receiver process — signature verification

Examples

Runnable scripts are in examples/, including a complete webhook receiver. Each one names its own command:

ABYSSALE_API_KEY=your-key python examples/generate_image.py

Contributing

See AGENTS.md for the architecture, how to regenerate the models from the OpenAPI spec, and how to add an endpoint.

Metadata

Release files for abyssale 1.6.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for abyssale 1.6.0
File Size Uploaded Provenance Actions
abyssale-1.6.0.tar.gz 62.3 kB Without provenance Details for abyssale-1.6.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for abyssale 1.6.0
File Interpreter ABI Platform Actions
abyssale-1.6.0-py3-none-any.whl Python 3 none any Details for abyssale-1.6.0-py3-none-any.whl

Total release size: 128.8 kB

Release files / abyssale-1.6.0.tar.gz

Download URL abyssale-1.6.0.tar.gz
Size 62.3 kB
Tags Source
SHA-256 checksum
How to use checksums
ec1ae0613d876b6ab687f4f54b42492c209104d41cb5b87473eb6c8a1eaac51a
BLAKE2b-256 checksum
How to use checksums
b5c872876063f8d717f2ca437141253035bf39e02d244937f43af2d9dd7b8495
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.7

Release files / abyssale-1.6.0-py3-none-any.whl

Download URL abyssale-1.6.0-py3-none-any.whl
Size 66.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9502abdaa91ef1c8021400be30259fa28fceb2185cb937ab33f0921dcd894e2e
BLAKE2b-256 checksum
How to use checksums
b82c8de7dd41a6e5082495523f803cf89ea1d155fed57a055c63e8313333511a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.7

Security for abyssale 1.6.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page