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-21 — 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.7.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.7.0
File Size Uploaded Provenance Actions
abyssale-1.7.0.tar.gz 63.7 kB Without provenance Details for abyssale-1.7.0.tar.gz

Built distribution (wheel)

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

Total release size: 131.3 kB

Release files / abyssale-1.7.0.tar.gz

Download URL abyssale-1.7.0.tar.gz
Size 63.7 kB
Tags Source
SHA-256 checksum
How to use checksums
0406eab8cb986707ae1170c1f02925419cc94b337f5641af3c7f3960c2a2e442
BLAKE2b-256 checksum
How to use checksums
e9a7135ae4e35c8bc5da0fdebce5dc6b2277987e534566d78da73db428a7de30
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.7.0-py3-none-any.whl

Download URL abyssale-1.7.0-py3-none-any.whl
Size 67.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
b0e15c183672b337b9d45e533e4474c3103e6ac4ad7b786a8505350e02d25f4f
BLAKE2b-256 checksum
How to use checksums
5171fa8fce5190f1b95be8a253b01ce69b35160018ce39165cadf50381a9acd1
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.7.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