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_ возвращает фиксированный результат мгновенно и без списания кредитов.
TypeScript SDK
Официальный TypeScript SDK Clipia (npm clipia-ai) — установка, инициализация клиента, постановка задачи в очередь и ожидание результата генерации.
Рекомендации
Практики для надёжной интеграции с Clipia API — идемпотентность на ретраях, вебхуки вместо опроса, обработка ошибок и 429 с backoff, оценка стоимости и хранение request_id.