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-11-10 — 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

  • 30 methods, sync and async, one per API operation, named after its operationId snake_cased, plus three 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.10.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.10.0
File Size Uploaded Provenance Actions
abyssale-1.10.0.tar.gz 70.5 kB Without provenance Details for abyssale-1.10.0.tar.gz

Built distribution (wheel)

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

Total release size: 143.5 kB

Release files / abyssale-1.10.0.tar.gz

Download URL abyssale-1.10.0.tar.gz
Size 70.5 kB
Tags Source
SHA-256 checksum
How to use checksums
98bdef0075257666b5d55c9a3d2a22775f5eb816140649b953e68327b10d5169
BLAKE2b-256 checksum
How to use checksums
31cd121f86b1f7f10b2b4a54ab921ab5d597297333ae397ccc37028a3fcb6fa3
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.10.0-py3-none-any.whl

Download URL abyssale-1.10.0-py3-none-any.whl
Size 72.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
2484e4173ceb877626660de6047f35e1be8f212c74cd4452e94fcb7ffd6fccf0
BLAKE2b-256 checksum
How to use checksums
47d756a6763ac709d293231e94a7c4cd2f4015c4fce367f4655f0b7e2d86dd28
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.10.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