SDK de Python
Referencia del SDK oficial constaia para Python 3.9+: clientes síncrono y asíncrono, entradas, opciones, paginación, errores, concurrencia y webhooks.
constaia es el SDK oficial para Python. Trae un cliente síncrono (Constaia) y otro asíncrono
(AsyncConstaia) sobre httpx, respuestas tipadas con TypedDict, errores tipados, reintentos, límite de
concurrencia en el cliente y verificación de webhooks. Requiere Python ≥ 3.9. Versión actual: 0.2.0.
pip install constaiaPrimeros pasos
from constaia import Constaia
client = Constaia() # lee CONSTAIA_API_KEY
analysis = client.analyze(
"dni_valid.jpg",
expect="es_dni",
checks={"not_expired": True, "holder": {"full_name": "María García López"}},
language="es",
)
verdict = analysis["verdict"]
if verdict and verdict["status"] == "valid":
print(analysis["fields"]["document_number"]["value"]) # 12345678Z
elif verdict and verdict["status"] == "review":
print("Revisión manual:", analysis["warnings"])
else:
for reason in verdict["reasons"] if verdict else []:
print(reason["code"], reason["message"])Con una clave ck_test_… no se gastan créditos y la respuesta depende del nombre del fichero. Ver
Modo test.
Asíncrono
import asyncio
from constaia import AsyncConstaia
async def main() -> None:
async with AsyncConstaia() as client:
analysis = await client.analyze(file_url="https://example.com/dni.jpg", expect="es_dni")
print(analysis["verdict"])
async for item in client.analyses.list(status="completed"):
print(item["id"])
asyncio.run(main())El cliente asíncrono tiene los mismos métodos con await. Ciérralo con await client.close() (o con async with).
Configuración
import httpx
from constaia import Constaia
client = Constaia(
api_key="ck_live_...", # por defecto: CONSTAIA_API_KEY
base_url="https://api.constaia.com", # por defecto; o CONSTAIA_BASE_URL
timeout=60.0, # segundos por intento
max_retries=2, # 0 desactiva los reintentos
max_concurrency=4, # peticiones en vuelo a la vez; el resto espera en el cliente
default_headers={"X-Team": "ops"},
http_client=httpx.Client(proxy="http://proxy:8080"), # opcional
)Crea un cliente por proceso y reutilízalo: comparte conexiones y el límite de concurrencia.
Qué ficheros acepta
analyze() y classify() reciben exactamente una de estas entradas:
| Entrada | Ejemplo |
|---|---|
Ruta (str o pathlib.Path) | client.analyze("scans/dni.jpg") |
| Bytes | client.analyze(data, filename="dni.jpg") |
| Fichero binario abierto | client.analyze(open("dni.pdf", "rb")), UploadedFile de Django, FileStorage.stream de Flask |
Tupla (nombre, bytes) | client.analyze(("dni.jpg", data)) |
| URL remota | client.analyze(file_url="https://example.com/dni.jpg") |
| Base64 | client.analyze(file_base64=b64, filename="dni.jpg") |
JPEG, PNG, WEBP, HEIC y PDF, hasta 20 MB y 30 páginas en análisis síncrono. El SDK lee el fichero una vez en memoria para que los reintentos envíen los mismos bytes.
Opciones
Los nombres son los de la API (snake_case). Como async es palabra reservada en Python, la opción se llama
async_.
analysis = client.analyze(
"dni.jpg",
expect=["es_dni", "es_nie", "passport"], # sin expect: veredicto contra el tipo detectado
checks={
"not_expired": True,
"min_age_years": 18,
"holder": {"full_name": "María García López", "document_number": "12345678Z"},
"require_fields": ["birth_date"],
},
extract=True, # o tu propio JSON Schema (dict)
storage="none", # "none" | "temporary" | "persistent"
ttl_hours=24, # con "temporary"
keep_results=True,
async_=False, # True → 202 y webhook
export=["xlsx", "json"],
metadata={"registration_id": "123"},
language="es",
idempotency_key="registration-123-dni", # opcional: la tuya
timeout=90,
)Cada opción se explica en POST /v1/analyze y Comprobaciones.
processing
processing="sovereign" | "standard" elige qué proveedores de IA pueden procesar el documento; la respuesta trae
analysis["processing"] con el perfil, la región y los proveedores usados. Ver Residencia de datos.
Métodos
client.analyze(file, **opciones)
client.classify(file, expect="invoice") # 0,2 créditos
client.analyses.get("an_01J…")
page = client.analyses.list(limit=50, status="completed", type="es_dni", metadata={"event": "42"})
page.data, page.has_more # primera página
for a in client.analyses.list(type="es_dni"): # iterar recorre todas las páginas
print(a["id"])
recent = client.analyses.list().to_list(200)
client.analyses.delete("an_01J…")
client.analyses.export("an_01J…", "xlsx", save_to="analisis.xlsx") # devuelve los bytes
# Revisión humana (solo clave secreta)
for a in client.reviews.list(status="pending"): # más antiguos primero, todas las páginas
print(a["id"])
original = client.analyses.file("an_01J…") # bytes; NotFoundError file_not_stored si ya no está
client.analyses.review("an_01J…", decision="approve", reason="Datos correctos", idempotency_key="review-an_01J…")
client.batches.create(items=[{"file_url": "https://example.com/1.pdf"}], options={"expect": "invoice"})
client.batches.create(files=["a.jpg", "b.pdf"], options={"expect": "payment_receipt"})
client.batches.get("bat_01J…")
client.document_types.list(language="es")
client.document_types.get("medical_certificate_sport")
endpoint = client.webhook_endpoints.create(
url="https://example.com/webhooks/constaia",
events=["analysis.completed", "analysis.review_required"],
)
endpoint["secret"] # whsec_… — solo aparece ahora
client.webhook_endpoints.list()
client.webhook_endpoints.get("we_01J…")
client.webhook_endpoints.delete("we_01J…")
client.balance()
client.usage(from_="2026-09-01", to="2026-09-30")analyses.list() devuelve la primera página (.data, .has_more, .next_page()); al iterarla, el SDK pide las
siguientes con starting_after. En el cliente asíncrono, await da la primera página y async for las recorre
todas. Ver Paginación.
Tipos
Las respuestas son dict normales con la misma forma que el JSON de la API, tipados con TypedDict
(constaia.types.Analysis, Classification, Batch, WebhookEndpoint…). mypy y pyright comprueban los nombres
de los campos; en tiempo de ejecución no se valida nada, así que los campos nuevos de la API no rompen versiones
antiguas del SDK.
from constaia.types import Analysis
def is_ok(a: Analysis) -> bool:
return a["verdict"] is not None and a["verdict"]["status"] == "valid"Errores
Todas las excepciones heredan de ConstaiaError, con message, status, type, code, param y request_id.
| Clase | Cuándo |
|---|---|
InvalidRequestError | 400, 409, 413, 415, 422 (code, param). |
AuthenticationError | 401. |
InsufficientCreditsError | 402. |
PermissionDeniedError | 403. |
NotFoundError | 404. |
RateLimitError | 429 tras agotar los reintentos (retry_after). |
APIError | 5xx (por ejemplo 503 live_mode_unavailable). |
APIConnectionError / APITimeoutError | Problemas de red. |
WebhookVerificationError | Firma de webhook no válida. |
from constaia import (
ConstaiaError,
InsufficientCreditsError,
InvalidRequestError,
RateLimitError,
)
try:
client.analyze("dni.jpg", expect="es_dni")
except InvalidRequestError as e:
print(e.code, e.param) # p. ej. unsupported_file_type, file
except InsufficientCreditsError:
notify_billing()
except RateLimitError as e:
print(f"reintenta en {e.retry_after} s")
except ConstaiaError as e:
print(e.status, e.type, e.request_id)Todos los códigos, en Errores.
Reintentos, concurrencia y límites
- Reintenta 429, 408, 409
idempotency_in_progress, 5xx (salvo 501) y errores de red hastamax_retriesveces, esperandoRetry-After(hasta 60 s) o con backoff exponencial y jitter. - Envía la misma
Idempotency-Keyen cada reintento: un análisis reintentado no se cobra dos veces. - Mantiene como máximo
max_concurrencypeticiones en vuelo por cliente (hilos o tareas asyncio); las demás esperan. - Expone las últimas cabeceras de límite:
client.balance()
client.last_rate_limit # RateLimit(limit=10, remaining=9, reset=1, policy='10;w=1', retry_after=None)
client.last_request_id # "req_…": inclúyelo si escribes a soporteCon varios procesos o workers, el límite por clave es compartido: mantén max_concurrency × procesos cerca de tu
límite de peticiones por segundo. Ver Límites de uso.
Webhooks
import constaia
event = constaia.webhooks.verify(raw_body, headers, "whsec_...") # lanza WebhookVerificationError
if event["type"] == "analysis.completed":
save(event["data"])Pasa siempre el cuerpo sin procesar (request.body en Django, request.get_data() en Flask,
await request.body() en FastAPI). Tolerancia por defecto: 300 s (tolerance=). Para tus tests,
constaia.webhooks.sign(payload, secret) genera cabeceras válidas. Más en Webhooks.
Guías por framework
Django y DRF
Vista de subida, APIView y webhook con csrf_exempt.
Flask
request.files y webhook con get_data().
FastAPI
UploadFile con el cliente asíncrono.
Celery
Tareas con reintentos, idempotencia y concurrencia.
Plantillas, expedientes, sesiones y privacidad
El SDK también cubre client.templates, client.dossiers, client.sessions, client.analytics() y client.analyses.delete_by_metadata() / export_by_metadata(). Los campos y ejemplos están en Plantillas, Expedientes, Sesiones y claves publicables, Analítica y Privacidad avanzada.
Siguientes pasos
SDK de PHP
Referencia de constaia/constaia-php para PHP 8.1+: instalación con Composer, entradas, opciones, métodos, paginación, excepciones, reintentos y webhooks.
Widget de subida
Referencia de @constaia/widget, el web component <constaia-upload> para capturar documentos en el navegador sin exponer tu clave. React, Vue y cualquier framework.