API documentation

This API allows users to search and download video clips from a diverse database, ideal for media platforms, educational content providers, and archival research.
Every request must have parameter api-key for authentication. You can obtain it here (PRO subscription is required)

Authentication

API Key

  • Required: An API key is necessary for all requests.
  • Usage: Include api_key=YOUR_API_KEY in the query string.
  • Security: Treat your API key as sensitive information to prevent unauthorized access.
  • All integers can be used as ranges (e.g., 2005-2010 or 2005- or -2005).

Base URL

All API requests should be initiated to: https://api.clip.cafe/.

Rate Limits

PRO: 10 requests per minute, up to 10 000 requests and 1000 downloads per month.
PRO+: 60 requests per minute, up to 50 000 requests and 5000 downloads per month.
PRO++: 600 requests per minute, up to 500 000 requests and 50000 downloads per month.
Pricing

Search Video Clips

Method: GET
Purpose: Retrieves video clips based on specified search criteria
Response: JSON object containing an array of clips with detailed metadata.

Query Parameters:

  • api_key (string) YOUR_API_KEY (mandatory).
  • title (string) Search by video title.
  • actors (string) Search by actors' names.
  • characters (string) Search by character's names.
  • slug (string) Search by unique slug.
  • transcript (string) Search within video transcripts.
  • captions (string) Search within video captions (semantic search).
  • imdb (string) Search by IMDb identifier.
  • movie_imdbscore (string) Search by IMDb score.
  • movie_metascore (string) Search by Meta Score.
  • movie_director (string) Search by director's name.
  • movie_writer (string) Search by writer's name.
  • movie_title (string) Search by movies title.
  • movie_slug (string) Search by movie slug.
  • movie_actors (string) Search by actors in movie.
  • movie_summary (string) Search by movie summary.
  • movie_slug (string) Search by movie slug.
  • sort (string) Sort results by a specific field (asc or desc. Default: score).
  • movie_year (int) Filter by release year. Range queries allowed (e.g., 2005-2010).
  • duration (int) Filter by clip duration in seconds. Range queries allowed.
  • views (int) Filter by number of views. Range queries allowed.
  • likes (int) Filter by number of likes. Range queries allowed.
  • clipID (int) Search by specific clip ID. Range queries allowed.
  • season (int) Filter by TV show season number. Range queries allowed.
  • episode (int) Filter by TV show episode number. Range queries allowed.
  • size (int) Number of results to return per page. (Default: 10)
  • from (int) Offset for results (used for pagination).(Default: 0)
  • order (string) Determines the sort direction for each field specified in the sort parameter. Accepts a comma‑separated list of sort directions (Example: order=desc,asc)
  • sort (string) Specifies the field or fields by which to sort the search results. You can provide a single field or multiple comma‑separated fields (Example: sort=title,views).

Example Request:

GET /?api_key=YOUR_API_KEY&duration=3&movie_title=matrix&actors=keanu+reeves HTTP/1.1
Host: api.clip.cafe

Response:

{
    "took": 1,
    "timed_out": false,
    "_shards": { "total": 1, "successful": 1, "skipped": 0, "failed": 0 },
    "hits": {
        "total": { "value": 2, "relation": "eq" },
        "max_score": 21.314917,
        "hits": [
            {
                "_index": "videoclips",
                "_id": "369707",
                "_score": 21.314917,
                "_source": {
                    "clipID": 369707,
                    "title": "Oh my God",
                    ... (clip data) ...
                }
            }
        ]
    }
}

Download Video Clips

To download a video clip, you need to provide your API key and the unique download key for the clip. The download key is a unique identifier for each clip that is generated when the search is made. Download keys are valid for 5 minutes.

Method: GET
Purpose: Download a specific video clip.
Response: Binary stream of the video clip.

Query Parameters:

  • api_key (string) YOUR_API_KEY (mandatory).
  • slug (string) Unique identifier for the clip (mandatory).
  • key (string) Unique download key (mandatory).

Example Request:

GET /?api_key=YOUR_API_KEY&slug=clip-slug&key=DOWNLOAD_KEY HTTP/1.1
Host: api.clip.cafe

Error Codes

  • 200 OK: Successful request.
  • 400 Bad Request: Invalid request format or parameters.
  • 401 Unauthorized: Missing or invalid API key.
  • 403 Forbidden: Access denied.
  • 404 Not Found: Resource not found.
  • 429 Too Many Requests: Rate limit exceeded.
  • 500 Internal Server Error: Server error.

Support

For support(any kind), contact us at api@clip.cafe