Cerul TypeScript 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

npm install cerul

Quick Start

import { cerul } from "cerul";

const client = cerul(); // reads CERUL_API_KEY

const result = await client.search({ query: "Sam Altman on AGI timeline" });

for (const r of result.results) {
  console.log(r.title, r.url);
}

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

Examples

// Search with filters
const result = await 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
console.log(result.answer);

// Check credits
const usage = await client.usage();
console.log(`${usage.credits_remaining} credits remaining`);

Configuration

const client = cerul({
  apiKey: "cerul_sk_...",   // or CERUL_API_KEY env var
  timeout: 30_000,          // default 30s
  retry: true,              // retry 429/5xx/network errors
});

Error Handling

import { CerulError } from "cerul";

try {
  await client.search({ query: "test" });
} catch (error) {
  if (error instanceof CerulError) {
    console.error(error.status, error.code, error.message);
  }
}

Features

• Zero dependencies — native fetch (Node 18+, Bun, Deno, Cloudflare Workers)
• Full TypeScript types — complete type definitions included
• Retry with backoff — 429 reads Retry-After, 5xx exponential backoff
• Network error retry — timeouts and connection errors also retried when retry: true

Links

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

License

MIT