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
operationIdsnake_cased, plus twowait_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,errorsandretry_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.
Links
- Abyssale — the product this SDK talks to
- Documentation
- API reference
- OpenAPI spec — the contract this SDK is generated from
- Source
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.