SDK de Python — Clipia Docs

El cliente oficial de Clipia para Python se publica en PyPI como clipia. Está construido sobre httpx, funciona con Python 3.9+ y ofrece un cliente síncrono Clipia y uno asíncrono AsyncClipia con los mismos métodos. Cubre la cola de generación (submit, status, result), el método de alto nivel subscribe, el catálogo de modelos con estimaciones de precio y los datos de la cuenta.

Paquete

El paquete y el módulo se llaman ambos clipia, versión actual 1.5.0. La URL base es https://api.clipia.ai. El SDK no lee variables de entorno por sí solo: pase la clave explícitamente en api_key.

Inicio rápido

Instalación

pip install clipia

Cliente

import os
from clipia import Clipia

# Lea la clave de una variable de entorno; no la escriba en el código
clipia = Clipia(api_key=os.environ["CLIPIA_KEY"])

Además de api_key, el constructor acepta base_url (solo https://) y un timeout HTTP (60 segundos por defecto). Use el cliente como gestor de contexto (with Clipia(...) as clipia:) o ciérrelo con clipia.close().

Generar y esperar el resultado

subscribe pone la tarea en cola y consulta su estado hasta que termina:

out = clipia.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,   # valor por defecto, segundos
    timeout=600.0,       # valor por defecto, segundos
)

if out.status == "COMPLETED":
    print(out.output)  # enlaces al contenido generado
    print(out.cost)    # coste en créditos
else:
    print(out.error)

subscribe también devuelve el control con FAILED, así que compruebe status. El cliente reintenta por sí solo los errores transitorios de consulta (red, 429, 5xx). Si la tarea no termina dentro de timeout, lanza ClipiaTimeoutError; la tarea sigue ejecutándose y puede obtenerla igualmente por su request_id.

Control manual de la cola

job = clipia.submit(
    "nano-banana-2",
    input={"prompt": "..."},
    webhook_url="https://example.com/clipia-webhook",  # opcional
)

status = clipia.status(job.request_id)
result = clipia.result(job.request_id)
# result.pending es True mientras la tarea está IN_QUEUE o IN_PROGRESS

Clave de idempotencia

El SDK genera una Idempotency-Key nueva en cada llamada a submit. Por sí sola, eso solo protege esa llamada concreta: si vuelve a llamar a submit tras un error de red sin una clave propia, se crea una segunda tarea. Para que un reintento sea seguro, pase su propio idempotency_key y reutilícelo en el reintento: consulte Idempotencia.

Catálogo, precio y cuenta

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

estimate = clipia.models.estimate("nano-banana-2", {"prompt": "a neon city"})
print(estimate.credits)

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

El catálogo y la cuenta se devuelven como diccionarios (TypedDict); las respuestas de la cola y de la estimación son objetos con atributos. models.list() puede incluir modelos LLM sin slug: consulte Catálogo de modelos.

Parámetros ignorados

Si input contiene una clave que el modelo no aplicará (una errata, un parámetro de otro modelo), submit y models.estimate aceptan la solicitud como de costumbre y devuelven la clave en warnings, con un elemento por cada clave. Cuando se aceptan todos los parámetros, la lista está vacía.

# job es la respuesta de submit de la sección anterior
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. …

# La misma comprobación antes de ejecutar nada: la estimación no cobra nada
estimate = clipia.models.estimate("nano-banana-2", {"prompt": "..."})
print(estimate.warnings)  # [] — se aceptaron todos los parámetros

La clase InputWarning y el atributo warnings se añadieron en la versión 1.5.0. subscribe devuelve el resultado de la generación, que no incluye advertencias: para leerlas, llame a submit o a models.estimate. Los valores de code y las demás reglas están en Parámetros ignorados.

Cliente asíncrono

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": "a cat"})
        print(out.output)

asyncio.run(main())

Verificación de webhooks

from clipia.webhooks import verify_signature

ok = verify_signature(
    secret=os.environ["CLIPIA_WEBHOOK_SECRET"],
    headers=request.headers,
    body=raw_body,           # el cuerpo bruto de la petición, str o bytes
    tolerance_seconds=300,   # valor por defecto
)

La función devuelve True o False y nunca lanza excepciones ante una entrada mal formada. Cada clave de API tiene su propio secreto de webhook: consulte Webhooks.

Gestión de errores

Cualquier respuesta que no sea 2xx se convierte en un ClipiaApiError con los atributos status, code, type y message. ClipiaTimeoutError es su subclase para cuando vence el tiempo de espera de subscribe.

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)

Los códigos de error figuran en la página Errores.

Sandbox

Una clave con el prefijo clipia_test_ devuelve un resultado predefinido al instante sin cobrar créditos. Consulte Sandbox.

En esta página