Python SDK
The official Clipia Python SDK (PyPI clipia) — install, initialize the client and run the full generation cycle: submit, wait and result.
The official Clipia Python client ships on PyPI as clipia. It is built on httpx and offers a synchronous Clipia and a mirrored asynchronous AsyncClipia. The client wraps the public Queue API: submit a job, poll status, or use the high-level subscribe that polls to a terminal result.
Package name
On PyPI the package, import folder and CLI command are all named clipia. The base URL is https://api.clipia.ai, authenticated with an API key.
Quickstart
Install
pip install clipiaInitialize the client
import os
from clipia import Clipia
# Read the key from an environment variable — never hard-code it.
client = Clipia(api_key=os.environ["CLIPIA_API_KEY"])Full generation cycle
The high-level subscribe enqueues a job and polls it to a finished result:
out = client.subscribe(
"nano-banana-2",
input={"prompt": "a neon city in the rain, cinematic lighting"},
on_queue_update=lambda s: print(s.status),
poll_interval=1.0, # default
timeout=600.0, # default
)
print(out.output) # links to the finished media
print(out.cost) # cost in creditsManual queue control:
job = client.submit("nano-banana-2", input={"prompt": "..."})
status = client.status(job.request_id)
result = client.result(job.request_id)Catalog, account and webhooks
client.models.list()
client.models.get("nano-banana-2")
client.account.get() # balance, usage_30d
from clipia.webhooks import verify_signature
ok = verify_signature(secret, headers, body, tolerance_seconds=300)The async variant is from clipia import AsyncClipia with the same methods via await.
Error handling
Errors are raised as ClipiaApiError with .status and .code attributes. The SDK generates an Idempotency-Key on every submit by default, so retries are safe.
Sandbox: a key prefixed clipia_test_ returns a fixed result instantly and with no credit charge.
TypeScript SDK
The official Clipia TypeScript SDK (npm clipia-ai) — install, initialize the client, submit a job and wait for the generation result.
Best practices
Practices for a reliable Clipia API integration — idempotent retries, webhooks over polling, error and 429 handling with backoff, cost estimation, and storing request_id.