API Reference

/search

Search the FrameFlow catalog by keyword, category, resolution, or duration. Supports semantic AI matching and boolean operators.

{
  "query": "drone aerial coastline sunset",
  "resolution": "4K",
  "duration_min": 5,
  "duration_max": 30,
  "license": "standard",
  "page": 1,
  "per_page": 20
}

Response (200 OK)

{
  "total": 1842,
  "page": 1,
  "per_page": 20,
  "results": [
    {
      "id": "ff-8a3c91e0",
      "title": "Aerial Coastal Highway at Golden Hour",
      "duration_sec": 12,
      "resolution": "3840x2160",
      "fps": 60,
      "codec": "H.265",
      "tags": ["drone", "aerial", "coastline", "highway", "sunset"],
      "contributor": "Mira Chen",
      "license": "standard",
      "preview_url": "https://cdn.frameflow.dev/preview/ff-8a3c91e0.webm",
      "download_url": "https://cdn.frameflow.dev/clip/ff-8a3c91e0.mp4"
    }
  ]
}

/downloads

Request a licensed download URL for a specific clip. The returned URL expires after 15 minutes and is single-use.

{
  "clip_id": "ff-8a3c91e0",
  "format": "mp4",
  "quality": "original"
}

Response (200 OK)

{
  "clip_id": "ff-8a3c91e0",
  "download_url": "https://cdn.frameflow.dev/secure/ff-8a3c91e0_20241215_abc.mp4?token=eyJhbG...",
  "expires_at": "2024-12-15T14:30:00Z",
  "file_size_bytes": 487392768,
  "license_agreement": "https://frameflow.dev/licenses/standard"
}

/users/me

Retrieve the authenticated user's profile, subscription tier, and remaining monthly download allowance.

Response (200 OK)

{
  "id": "usr-4f7b22d1",
  "email": "dev@acmediastudio.co",
  "plan": "professional",
  "downloads_used": 47,
  "downloads_limit": 200,
  "credits_balance": 1250,
  "created_at": "2023-06-12T09:00:00Z"
}

/users/me/preferences

Update user preferences including default resolution, proxy download behavior, and notification settings.

{
  "default_resolution": "4K",
  "auto_convert_to_prores": false,
  "email_notifications": true
}

Response (200 OK)

{
  "id": "usr-4f7b22d1",
  "preferences": {
    "default_resolution": "4K",
    "auto_convert_to_prores": false,
    "email_notifications": true
  },
  "updated_at": "2024-12-15T13:14:22Z"
}

/collections

Create a curated collection of clips for project organization. Collections are private by default and shared via API key.

{
  "name": "Q1 Campaign — Urban Motion",
  "description": "City timelapses and aerials for the January rebrand",
  "clip_ids": ["ff-8a3c91e0", "ff-b2d44f11", "ff-e9a00c33"]
}

Response (201 Created)

{
  "id": "col-771a9e0f",
  "name": "Q1 Campaign — Urban Motion",
  "clip_count": 3,
  "created_at": "2024-12-15T13:20:00Z"
}

/clip/{id}/metadata

Fetch full metadata for a single clip, including AI-generated tags, color histogram data, and contributor royalty split.

Response (200 OK)

{
  "id": "ff-8a3c91e0",
  "title": "Aerial Coastal Highway at Golden Hour",
  "contributor": {
    "name": "Mira Chen",
    "id": "cont-33f1a009",
    "royalty_pct": 70
  },
  "ai_tags": ["drone", "aerial", "coastline", "highway", "sunset", "golden-hour", "asphalt", "ocean"],
  "color_palette": ["#f4a261", "#264653", "#e9c46a", "#2a9d8f"],
  "audio": false,
  "safe_for_commercial": true
}

Header Format

Authorization: Bearer ff_live_sk_8a3c91e0d4f722b1...

Never expose your secret key (ff_live_sk_) in client-side code. Use your publishable key (ff_live_pk_) for browser-based search operations.

Key Types

Publishable key (ff_live_pk_) — Read-only access to search and metadata endpoints. Safe for frontend use.

Secret key (ff_live_sk_) — Full access including downloads, user management, and collection creation. Server-side only.

Free Tier

60 requests per minute

10 download requests per hour

Professional Tier

600 requests per minute

200 download requests per hour

Enterprise Tier

6,000 requests per minute

Unlimited download requests

JavaScript / TypeScript

npm install @frameflow/sdk

import { FrameFlow } from '@frameflow/sdk';

const ff = new FrameFlow({
  apiKey: process.env.FRAMEFLOW_API_KEY
});

const results = await ff.search({
  query: 'timelapse city night',
  per_page: 10
});

Version 2.4.1 — Supports Node.js 18+ and modern browsers. TypeScript definitions included.

Python

pip install frameflow

from frameflow import FrameFlow

ff = FrameFlow(api_key="ff_live_sk_...")

clips = ff.search(
    query="aerial mountain lake",
    resolution="4K",
    per_page=20
)

for clip in clips:
    print(clip.title, clip.duration_sec)

Version 1.8.3 — Python 3.9+. Async support via frameflow.asyncio.

Ruby

gem install frameflow

require 'frameflow'

ff = FrameFlow::Client.new(api_key: ENV['FRAMEFLOW_API_KEY'])

results = ff.search(query: 'underwater coral reef', per_page: 15)

Version 0.9.7 — Ruby 3.0+. Compatible with Rails via the frameflow-rails plugin.

Go

go get github.com/frameflow/frameflow-go

import "github.com/frameflow/frameflow-go"

client := frameflow.New(os.Getenv("FRAMEFLOW_API_KEY"))

results, _ := client.Search(&frameflow.SearchParams{
  Query:   "drone forest canopy",
  PerPage: 20,
})

Version 1.2.0 — Go 1.21+. Full context and cancellation support.

PHP

composer require frameflow/frameflow-php

use FrameFlow\Framework;

$ff = new Framework($_ENV['FRAMEFLOW_API_KEY']);

$clips = $ff->search([
  'query' => 'slow motion water droplets',
  'per_page' => 10
]);

Version 3.1.2 — PHP 8.1+. PSR-18 HTTP client compliant.

cURL Quick Start

No SDK? Use cURL directly for rapid prototyping:

curl -X GET "https://api.frameflow.dev/v1/search?query=timelapse&per_page=5" \
  -H "Authorization: Bearer ff_live_sk_..."