---
title: SDK de Python
description: "El SDK oficial de Clipia para Python (PyPI clipia 1.5.0): clientes Clipia y AsyncClipia, cola de generación, catálogo y estimaciones de precio, verificación de webhooks y errores."
icon: FileCode
---
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.
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 [#quickstart]
### Instalación
```bash
pip install clipia
```
### Cliente
```python
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:
```python
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 [#queue]
```python
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
```
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](/es/docs/api-reference/idempotency).
## Catálogo, precio y cuenta [#catalog]
```python
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](/es/docs/api-reference/models).
## Parámetros ignorados [#warnings]
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.
```python
# 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](/es/docs/api-reference/submit#warnings).
## Cliente asíncrono [#async]
```python
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 [#webhooks]
```python
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](/es/docs/api-reference/webhooks).
## Gestión de errores [#errors]
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`.
```python
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](/es/docs/api-reference/errors).
## Sandbox [#sandbox]
Una clave con el prefijo `clipia_test_` devuelve un resultado predefinido al instante sin cobrar créditos. Consulte [Sandbox](/es/docs/getting-started/sandbox).