CCerul

Start here

Quickstart Guide

Get up and running with the Cerul API in under 5 minutes. Learn how to make your first search request and understand the response format.

5 min read4 sections← Back to docs

Guide

Start here

Built to be operator-readable before you wire in automation.

Read time

5 min read

Quick enough for onboarding, specific enough for implementation.

Focus

Practical API use

Examples, request shape, and the minimum context needed to ship.

01

Get your API key

Before making any requests, you need an API key. Sign up for a free account at cerul.ai and create your first API key from the dashboard. The free tier includes 1,000 credits to get started.

  • Create account at https://cerul.ai
  • Navigate to Dashboard > API Keys
  • Click 'Create new key'
  • Copy your key (starts with 'cerul_')

02

Make your first request

Use curl to make a test request. Replace YOUR_CERUL_API_KEY with your actual API key. This example searches for b-roll footage of coastal highways.

first_request.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",
    "search_type": "broll",
    "max_results": 3
  }'

03

Understanding the response

The API returns a JSON object containing an array of results. Each result includes a direct video_url you can use to download or embed the video, along with metadata like duration, source, and relevance score.

first_response.jsonJSON
{
  "results": [
    {
      "id": "pexels_28192743",
      "score": 0.89,
      "title": "Aerial drone shot of coastal highway",
      "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"
    }
  ],
  "credits_used": 1,
  "credits_remaining": 999
}

04

Using the video URL

The video_url in the response is a direct link to the video file. You can use this URL to embed the video in your application, download it for processing, or serve it to your users. The URL is valid for 24 hours.

  • video_url: Direct link to MP4 file
  • thumbnail_url: Preview image
  • duration: Length in seconds
  • License info included for compliance

Continue Reading

Explore more guides or try the API in the dashboard.

All GuidesOpen Dashboard