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 clipia

Initialize 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 credits

Manual 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.