CCerul

Documentation

Cerul API Documentation

Video understanding search API for AI agents. Search what is shown in videos, not just what is said.

Start in 5 minutesTry the dashboard

Setup

5 min

From API key to first search request.

Tracks

2

Knowledge retrieval and b-roll search on one API.

Path

HTTP + skill

Start with direct calls, then package repeatable workflows.

Quick Example

The primary workflow is request in, evidence-rich results out. Use these samples as your first smoke test.

KNOWLEDGE SEARCHFind insights from interviews and talks
knowledge-search.shBASH
curl "https://api.cerul.ai/v1/search" \
  -H "Authorization: Bearer $CERUL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Sam Altman views on AI video generation tools",
    "search_type": "knowledge",
    "max_results": 3,
    "include_answer": true
  }'
B-ROLL SEARCHFind stock footage and clips
broll-search.shBASH
curl "https://api.cerul.ai/v1/search" \
  -H "Authorization: Bearer $CERUL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cinematic drone shot of coastal highway",
    "search_type": "broll",
    "max_results": 5
  }'

Getting Started

Cerul API Overview

The Cerul API provides video understanding capabilities for AI agents. Search what is shown in videos, not just what is said. All API requests are made to the base URL with your API key included in the Authorization header.

  • Base URL: https://api.cerul.ai
  • All requests require Bearer token authentication
  • JSON request and response bodies
  • UTF-8 encoding required

Authentication

API Key Authentication

All API requests must include your API key in the Authorization header using the Bearer token format. You can create and manage API keys from your dashboard.

  • Include API key in every request
  • Use 'Authorization: Bearer YOUR_API_KEY' header
  • Keep your API keys secure
  • Rotate keys periodically from the dashboard
auth.shBASH
curl "https://api.cerul.ai/v1/search" \
  -H "Authorization: Bearer YOUR_CERUL_API_KEY" \
  -H "Content-Type: application/json"

Search Endpoint

POST /v1/search

The search endpoint is the primary interface for retrieving video content. Use search_type to specify whether you want b-roll footage or knowledge segments. The endpoint returns matching results with metadata and direct video URLs.

  • search_type: 'broll' for stock footage
  • search_type: 'knowledge' for educational content
  • max_results: 1-50 (default: 10)
  • include_answer: true for AI-generated summaries
search_broll.shBASH
curl "https://api.cerul.ai/v1/search" \
  -H "Authorization: Bearer YOUR_CERUL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "cinematic drone shot of coastal highway at sunset",
    "search_type": "broll",
    "max_results": 5,
    "filters": {
      "min_duration": 5,
      "max_duration": 30,
      "source": "pexels"
    }
  }'

Usage Endpoint

GET /v1/usage

Check your current usage, credit balance, and rate limits. This endpoint is useful for monitoring your consumption and preventing unexpected quota exhaustion.

  • Returns current tier information
  • Shows credits used and remaining
  • Includes rate limit status
  • Real-time credit tracking
usage.shBASH
curl "https://api.cerul.ai/v1/usage" \
  -H "Authorization: Bearer YOUR_CERUL_API_KEY"

Response Format

Understanding API Responses

API responses follow a consistent JSON structure. Successful requests return HTTP 200 with result data. Errors return appropriate HTTP status codes with detailed error messages.

  • Results array contains video matches
  • Each result includes direct video URL
  • Score indicates relevance (0.0-1.0)
  • Metadata varies by search_type
response.jsonJSON
{
  "results": [
    {
      "id": "pexels_28192743",
      "score": 0.89,
      "title": "Aerial drone shot of coastal highway",
      "description": "Cinematic 4K drone footage of winding coastal road at golden hour",
      "video_url": "https://videos.pexels.com/video-files/28192743/abc123.mp4",
      "thumbnail_url": "https://images.pexels.com/photos/28192743/pexels-photo-28192743.jpeg",
      "duration": 18,
      "source": "pexels",
      "license": "pexels-license"
    }
  ],
  "credits_used": 1,
  "credits_remaining": 999,
  "request_id": "req_abc123xyz"
}

Next Steps

Ready to start building? Check out the guides or open the dashboard.

Read QuickstartOpen Dashboard