Cerul Python SDK

The video search layer for AI agents.

Teach your AI agents to see — search by meaning across visual scenes, speech, and on-screen content.

Docs · Website · Main Repo ·

Install

pip install cerul

Quick Start

from cerul import Cerul

client = Cerul()  # reads CERUL_API_KEY

for r in client.search(query="Sam Altman on AGI timeline"):
    print(r.title, r.url)

Get a free API key at cerul.ai/dashboard.

Examples

# Search with filters
result = client.search(
    query="Jensen Huang on AI infrastructure",
    max_results=5,
    ranking_mode="rerank",
    include_answer=True,
    filters={"speaker": "Jensen Huang", "published_after": "2024-01-01"},
)

# AI-generated answer
print(result.answer)

# Check credits
usage = client.usage()
print(f"{usage.credits_remaining} credits remaining")

Async

from cerul import AsyncCerul

async with AsyncCerul() as client:
    result = await client.search(query="attention mechanism explained")

Configuration

client = Cerul(
    api_key="cerul_sk_...",   # or CERUL_API_KEY env var
    timeout=30.0,             # default 30s
    retry=True,               # retry 429/5xx/network errors
)

Error Handling

from cerul import CerulError

try:
    client.search(query="test")
except CerulError as e:
    print(e.status_code, e.code, e.message)

Links

• CLI — curl -fsSL https://cli.cerul.ai/install.sh | bash
• TypeScript SDK — npm install cerul
• Main repo — docs, skills, remote MCP

License

MIT