---
title: Python SDK
description: "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.

<Callout type="info" title="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.
</Callout>

## Quickstart

<Steps>

<Step>

### Install

```bash
pip install clipia
```

</Step>

<Step>

### Initialize the client

```python
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"])
```

</Step>

<Step>

### Full generation cycle

The high-level `subscribe` enqueues a job and polls it to a finished result:

```python
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
```

</Step>

</Steps>

Manual queue control:

```python
job = client.submit("nano-banana-2", input={"prompt": "..."})
status = client.status(job.request_id)
result = client.result(job.request_id)
```

## Catalog, account and webhooks

```python
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`.

<Callout type="info" title="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.
</Callout>

Sandbox: a key prefixed `clipia_test_` returns a fixed result instantly and with no credit charge.