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-07 — 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.5.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.5.0
File Size Uploaded Provenance Actions
abyssale-1.5.0.tar.gz 61.7 kB Without provenance Details for abyssale-1.5.0.tar.gz

Built distribution (wheel)

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

Total release size: 128.0 kB

Release files / abyssale-1.5.0.tar.gz

Download URL abyssale-1.5.0.tar.gz
Size 61.7 kB
Tags Source
SHA-256 checksum
How to use checksums
37117dae0b47a64270e59cae4b805c88c692e4a1b72461df625c8743e13cc0c6
BLAKE2b-256 checksum
How to use checksums
86062fd37e9e2a33783ee230a4f8ac27235e9bc31bb3d9d9b82f723a21598be4
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.5.0-py3-none-any.whl

Download URL abyssale-1.5.0-py3-none-any.whl
Size 66.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
e47fea9289f25bffaab8a0c409e45370b5f48619c8f647fb116e29e786d34bf2
BLAKE2b-256 checksum
How to use checksums
72f5c5ca4469eb4620ad8cbee826cfa086ff597b3e0ef8ae089c043cf6502d90
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.5.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