---
title: Python SDK
description: "Официальный Python SDK Clipia (PyPI clipia) — установка, инициализация клиента и полный цикл генерации: submit, ожидание и результат."
---

Официальный Python-клиент Clipia публикуется в PyPI как `clipia`. Он построен на `httpx` и предлагает синхронный `Clipia` и зеркальный асинхронный `AsyncClipia`. Клиент оборачивает публичный Queue API: постановку задачи, опрос статуса и высокоуровневый `subscribe`, который поллит до терминального результата.

<Callout type="info" title="Имя пакета">
В PyPI пакет, import-папка и CLI-команда называются `clipia`. Базовый URL — `https://api.clipia.ai`, авторизация по API-ключу.
</Callout>

## Быстрый старт

<Steps>

<Step>

### Установка

```bash
pip install clipia
```

</Step>

<Step>

### Инициализация клиента

```python
import os
from clipia import Clipia

# Читайте ключ из переменной окружения — не зашивайте его в код.
client = Clipia(api_key=os.environ["CLIPIA_API_KEY"])
```

</Step>

<Step>

### Полный цикл генерации

Высокоуровневый `subscribe` ставит задачу в очередь и опрашивает её до готового результата:

```python
out = client.subscribe(
    "nano-banana-2",
    input={"prompt": "неоновый город под дождём, кинематографичный свет"},
    on_queue_update=lambda s: print(s.status),
    poll_interval=1.0,   # по умолчанию
    timeout=600.0,       # по умолчанию
)

print(out.output)  # ссылки на готовые медиа
print(out.cost)    # стоимость в кредитах
```

</Step>

</Steps>

Ручной контроль очереди:

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

## Каталог, аккаунт и вебхуки

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

Асинхронный вариант — `from clipia import AsyncClipia` с теми же методами через `await`.

<Callout type="info" title="Обработка ошибок">
Ошибки приходят как `ClipiaApiError` с атрибутами `.status` и `.code`. SDK по умолчанию генерирует `Idempotency-Key` на каждый `submit`, поэтому повторы безопасны.
</Callout>

Песочница: ключ с префиксом `clipia_test_` возвращает фиксированный результат мгновенно и без списания кредитов.