Python SDK

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

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

Имя пакета

В PyPI пакет, import-папка и CLI-команда называются clipia. Базовый URL — https://api.clipia.ai, авторизация по API-ключу.

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

Установка

pip install clipia

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

import os
from clipia import Clipia

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

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

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

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)    # стоимость в кредитах

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

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

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

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.

Обработка ошибок

Ошибки приходят как ClipiaApiError с атрибутами .status и .code. SDK по умолчанию генерирует Idempotency-Key на каждый submit, поэтому повторы безопасны.

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