Build with Cerul
Add video understanding to your AI agents with one API call. Search across visual scenes, speech, and on-screen text — get back timestamped results with relevance scores and source links.
Step 1
Get your API key
Sign up at cerul.ai and your default API key is ready in the dashboard. New accounts start with 100 signup credits and 10 free searches per day. Add a credit card when you want the 300-credit monthly free tier.
Step 2
Make your first search
Replace YOUR_CERUL_API_KEY with your actual key. This searches across visual scenes, speech, and on-screen text in one call.
search.sh
curl "https://api.cerul.ai/v1/search" \
-H "Authorization: Bearer YOUR_CERUL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "Sam Altman views on AI video generation",
"include_answer": true
}'Step 3
Understand the response
Each result includes a relevance score, timestamps, source metadata, and a tracking URL that redirects to the original video.
response.json
{
"results": [
{
"id": "unit_hmtuvNfytjM_1223",
"score": 0.92,
"url": "https://cerul.ai/v/a8f3k2x",
"title": "Sam Altman on AGI Timeline",
"snippet": "AGI is coming sooner than most people expect.",
"transcript": "AGI is coming sooner than most people expect, and the roadmap gets clearer once model capability and product reliability converge.",
"thumbnail_url": "https://i.ytimg.com/vi/hmtuvNfytjM/hqdefault.jpg",
"keyframe_url": "https://cdn.cerul.ai/frames/hmtuvNfytjM/f0123.jpg",
"duration": 7200,
"source": "youtube",
"speaker": "Sam Altman",
"timestamp_start": 1223.0,
"timestamp_end": 1345.0
}
],
"answer": "Summary grounded in matched evidence.",
"credits_used": 2,
"credits_remaining": 998,
"request_id": "req_9f8c1d5b2a9f7d1a8c4e6b02"
}Daily free
Today: 10 / 10 free searches reset every UTC day
Sign in to see your live remaining count here. The first 10 searches each day still cost 0 credits.
Step 4
Check your usage
Monitor your credit balance, daily free allowance, wallet breakdown, and rate limits before scaling traffic.
usage.sh
curl "https://api.cerul.ai/v1/usage" \
-H "Authorization: Bearer YOUR_CERUL_API_KEY"
# Response:
# {
# "tier": "free",
# "credits_used": 128,
# "credits_remaining": 872,
# "wallet_balance": 872,
# "daily_free_remaining": 7,
# "daily_free_limit": 10,
# "rate_limit_per_sec": 1,
# "api_keys_active": 1
# }