Python SDK

Официальный Python-клиент Clipia публикуется в PyPI как clipia. Он построен на httpx, работает на Python 3.9+ и даёт синхронный Clipia и асинхронный AsyncClipia с теми же методами. Клиент покрывает очередь генераций (submit, status, result), высокоуровневый subscribe, каталог моделей с оценкой цены и данные аккаунта.

Быстрый стартСкопировать ссылку на раздел

pip install clipia

import os
from clipia import Clipia

# Ключ берите из переменной окружения, не вписывайте его в код
clipia = Clipia(api_key=os.environ["CLIPIA_KEY"])

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

if out.status == "COMPLETED":
    print(out.output)  # ссылки на готовые медиа
    print(out.cost)    # стоимость в кредитах
else:
    print(out.error)

subscribe возвращает результат и при FAILED, поэтому проверяйте status. Кратковременные ошибки опроса (сеть, 429, 5xx) клиент повторяет сам. Если задача не завершилась за timeout, выбрасывается ClipiaTimeoutError; задача при этом продолжает выполняться, и её можно забрать по request_id.

Ручное управление очередьюСкопировать ссылку на раздел

job = clipia.submit(
    "nano-banana-2",
    input={"prompt": "..."},
    webhook_url="https://example.com/clipia-webhook",  # необязательно
)

status = clipia.status(job.request_id)
result = clipia.result(job.request_id)
# result.pending == True, пока задача в IN_QUEUE или IN_PROGRESS

Каталог, цена и аккаунтСкопировать ссылку на раздел

catalog = clipia.models.list()        # {"data": [...]}
model = clipia.models.get("nano-banana-2")

estimate = clipia.models.estimate("nano-banana-2", {"prompt": "неоновый город"})
print(estimate.credits)

account = clipia.account.get()
# {"account_id": ..., "balance": {"credits": ...}, "usage_30d": {"requests": ..., "credits_spent": ...}}

Каталог и аккаунт возвращаются как словари (TypedDict), ответы очереди и оценки — как объекты с атрибутами. В models.list() могут прийти LLM-модели без slug — см. «Каталог моделей».

Проигнорированные параметрыСкопировать ссылку на раздел

Если в input есть ключ, который модель не применит (опечатка, параметр другой модели), submit и models.estimate принимают запрос как обычно, а ключ возвращают в warnings — по элементу на каждый. Когда все параметры приняты, список пуст.

# job — ответ submit из раздела выше
for w in job.warnings:
    print(w.code, w.parameter, w.message)
    # unknown_parameter aspect_ration Parameter "aspect_ration" is not recognized and was ignored. …

# То же до запуска: оценка ничего не списывает
estimate = clipia.models.estimate("nano-banana-2", {"prompt": "..."})
print(estimate.warnings)  # [] — все параметры приняты

Класс InputWarning и атрибут warnings появились в версии 1.5.0. subscribe возвращает итог генерации, предупреждений в нём нет: чтобы их прочитать, вызывайте submit или models.estimate. Значения code и остальные правила — в разделе «Проигнорированные параметры».

Асинхронный клиентСкопировать ссылку на раздел

import asyncio
from clipia import AsyncClipia

async def main():
    async with AsyncClipia(api_key=os.environ["CLIPIA_KEY"]) as clipia:
        out = await clipia.subscribe("nano-banana-2", input={"prompt": "кот"})
        print(out.output)

asyncio.run(main())

Проверка вебхуковСкопировать ссылку на раздел

from clipia.webhooks import verify_signature

ok = verify_signature(
    secret=os.environ["CLIPIA_WEBHOOK_SECRET"],
    headers=request.headers,
    body=raw_body,           # сырое тело запроса, str или bytes
    tolerance_seconds=300,   # по умолчанию
)

Функция возвращает True или False и не выбрасывает исключений на некорректных данных. Секрет вебхуков свой у каждого API-ключа — см. «Вебхуки».

Обработка ошибокСкопировать ссылку на раздел

Любой ответ не из диапазона 2xx превращается в ClipiaApiError с атрибутами status, code, type, message и, если сервер прислал Retry-After, retry_after в секундах. ClipiaTimeoutError — его подкласс для истёкшего timeout в subscribe: status равен 0, code — poll_timeout, request_id хранит идентификатор задачи, которая продолжает выполняться.

from clipia import ClipiaApiError

try:
    clipia.submit("nano-banana-2", input={"prompt": "..."})
except ClipiaApiError as e:
    print(e.status, e.code, e.type, e.message)

Коды ошибок — на странице «Ошибки».

ПесочницаСкопировать ссылку на раздел

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