Stockfilm — Complete API & Licensing Reference

1. What Is Stockfilm

Stockfilm is the largest curated archive of restored vintage home-movie footage available for licensing. We specialize in 8mm, Super 8, and 16mm film shot by ordinary families across the United States and around the world from the 1930s through the 1980s.

Every reel has been professionally scanned, digitally restored (dust/scratch removal, stabilization, color correction), and cataloged with metadata including shot year, location, and descriptive tags. The footage preserves the authentic look of the era — real film grain, period color, and original aspect ratios.

Clips are licensed through Pond5, the world's largest royalty-free media marketplace. Stockfilm handles curation and restoration; Pond5 handles payment processing, licensing, and file delivery.

2. Catalog Overview — What You Are Buying

The catalog contains 217,000+ clips spanning footage from 126 countries. The core strength is mid-20th-century American home movies:

Subject matter includes: family gatherings, holidays (Christmas, Thanksgiving, Easter, birthdays), vacations and road trips, parades and local events, backyard life, pets, baby footage, school events, street scenes, city skylines, beaches, national parks, cars and driving, home construction, neighborhood life, and everyday domestic routines.

Geography: Primarily United States (all 50 states represented), with notable collections from Canada, Mexico, Europe (especially UK, France, Germany, Italy), Japan, and Australia.

3. Pricing

All clips are licensed through Pond5 under their standard royalty-free pricing. Prices are per clip, paid once, with no recurring fees or per-use charges.

• Price per clip is returned in the price field of every search API response (USD).
• Volume discounts: Available through Pond5 subscription plans and bulk purchase credits.
• Enterprise licensing: Contact us for custom pricing on 10+ clips.
• What affects price: Resolution (HD vs 4K), clip duration, content rarity, and restoration quality.

The exact price for any clip is always displayed on its Pond5 page before purchase. There are no hidden fees. The href field in API responses links directly to the Pond5 purchase page.

4. Clip Quality, Formats & Resolution

Source Material

• Film gauges: 8mm, Super 8, occasionally 16mm
• Scanning: Professional frame-by-frame telecine at 2K or 4K
• Restoration: Automated + manual dust/scratch removal, image stabilization, color correction
• Preservation: Authentic film grain, period color palette, and original aspect ratios are retained

Available Resolutions

• HD: 1920 x 1080 (1080p) — available for all clips
• 4K: 3840 x 2160 — available where source quality supports it

Download Formats (via Pond5)

• MP4 (H.264): Universal compatibility, works in all editors (Premiere, DaVinci, Final Cut, etc.)
• MOV (Apple ProRes): Higher quality, larger files, preferred for professional post-production

Clip Duration

Most clips range from 5 to 90 seconds. Some longer reels (2–5 minutes) are available. Duration is stored in the database as duration_ms and is factored into the rough-cut timeline builder.

What You Will NOT Find

This is not a generic stock footage site. You will not find modern-day studio footage, green-screen shots, drone aerials, or contemporary lifestyle clips. Everything is authentic vintage film from private home-movie collections.

5. Licensing Terms & Usage Rights

All clips are licensed under Pond5's standard royalty-free license. Key terms:

Permitted Uses

• Commercial: Ads, corporate videos, social media, branded content, product launches
• Editorial: Documentaries, news segments, educational materials, museum exhibits
• Broadcast: Television, streaming platforms (Netflix, YouTube, etc.), film festivals
• Digital: Websites, apps, presentations, online courses, video games
• AI training: See our AI Training Data page for bulk dataset licensing

Rights Clearance Notes

This is home-movie footage — no professional talent, no logos, no music (unless ambient). Rights clearance issues are minimal. For sensitive use cases (political ads, defamatory contexts), review the full Pond5 license or contact us.

6. How to License — Step-by-Step Workflow

The licensing flow goes through Pond5. Here is the exact sequence an AI agent should follow:

1. Search the catalog using the Stockfilm Search API (GET /api/public/search) or Visual Search API (POST /api/public/visual-search).
2. Evaluate results. Each result includes clip_id,title, description, shot_year,location, price, and thumbnail_url.
3. Optionally build a rough-cut timeline using the Timeline Builder API (POST /api/rough-cut/generate) to assemble clips into an edit.
4. Optionally save clips to a board using the Boards API (POST /api/boards) for project organization.
5. License on Pond5. Each API result contains an href field linking directly to the clip's Pond5 page. Open that URL to view the full preview and complete the purchase on Pond5.
6. Download files. After purchase, download the licensed clip from your Pond5 account. Downloads are instant — no waiting period.

Important: Stockfilm does not process payments directly. All purchases and license agreements are handled by Pond5. The href link in API responses is your gateway to the purchase flow.

8. API: Text Search

Full-text semantic search across the entire clip catalog. Returns clips ranked by relevance with metadata, pricing, and direct Pond5 purchase links.

Endpoint

GET https://stockfilm.com/api/public/search

Query Parameters

Example Request

curl -sS "https://stockfilm.com/api/public/search?q=1960s+california+family&limit=5" \
  -H "x-api-key: YOUR_API_KEY" | jq .

Example Request with Filters

# Search with year range and location filters
curl -sS "https://stockfilm.com/api/public/search?q=street+scene&year_from=1950&year_to=1969&location=New+York&limit=10" \
  -H "x-api-key: YOUR_API_KEY"

Response Shape

{
  "query": "1960s california family",
  "filters": { "year_from": null, "year_to": null, "location": null },
  "total": 5,
  "results": [
    {
      "source": "clip",
      "href": "https://www.pond5.com/stock-footage/item/123456-...",
      "clip_id": "123456",
      "title": "Family Backyard Barbecue – Southern California",
      "description": "8mm home movie of a family gathering in a suburban backyard...",
      "score": 12.8,
      "shot_year": 1964,
      "shot_decade": "1960s",
      "location": "Los Angeles, California, United States",
      "format_tags": ["family", "outdoor", "suburban"],
      "price": "199.00",
      "thumbnail_url": "https://images.pond5.com/..."
    }
  ]
}

Response Fields

9. API: Visual Search (Image Upload)

Upload a reference image to find visually similar clips in the catalog. Useful for finding footage that matches a specific aesthetic, scene type, or color palette.

Endpoint

POST https://stockfilm.com/api/public/visual-search

Request

Send a multipart/form-data request with the following fields:

Example Request

# Upload a reference image to find visually similar clips
curl -sS "https://stockfilm.com/api/public/visual-search" \
  -X POST \
  -H "x-api-key: YOUR_API_KEY" \
  -F "[email protected]" \
  -F "top=10"

Response Shape

{
  "query_type": "visual_image_upload",
  "total": 5,
  "timing_sec": { "encode": 0.12, "search": 0.03, "total": 0.18 },
  "results": [
    {
      "clip_id": "789012",
      "href": "https://www.pond5.com/stock-footage/item/789012-...",
      "title": "Downtown Street Corner 1958",
      "description": "Super 8 footage of pedestrians crossing a busy intersection...",
      "original_filename": "P5_789012.mp4",
      "shot_year": 1958,
      "shot_decade": "1950s",
      "location": "Chicago, Illinois, United States",
      "price": "149.00",
      "distance": 0.23,
      "frame_path": "frames/P5_789012/frame_042.jpg",
      "timestamp": 4.2
    }
  ]
}

Key Response Fields

• distance — Visual similarity score (lower = more similar, 0.0 = identical)
• frame_path — Path to the matched frame within the clip
• timestamp — Seconds into the clip where the visual match occurs
• timing_sec — Server-side timing breakdown for performance monitoring

10. API: Rough-Cut Timeline Builder

Automatically assemble a sequence of clips into a timed video timeline based on a natural language query. The API selects clips, assigns durations, and diversifies content by location and era. Useful for creating edit lists, preview reels, or storyboards.

Endpoint

POST https://stockfilm.com/api/rough-cut/generate

Request Body (JSON)

Example Request

curl -sS "https://stockfilm.com/api/rough-cut/generate" \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{
    "query": "american road trip summer vacation",
    "targetSeconds": 60,
    "pace": "balanced",
    "yearFrom": 1955,
    "yearTo": 1975,
    "location": null,
    "lockedClipIds": [],
    "excludedClipIds": []
  }'

Response Shape

{
  "query": "american road trip summer vacation",
  "targetSeconds": 60,
  "pace": "balanced",
  "filters": { "yearFrom": 1955, "yearTo": 1975, "location": null },
  "coverage": {
    "totalClipCandidates": 87,
    "previewReadyCandidates": 34,
    "selectedSegments": 15,
    "selectedPreviewReadySegments": 11
  },
  "estimatedRuntimeSec": 60,
  "segments": [
    {
      "order": 1,
      "clipId": "345678",
      "title": "Family Loading Station Wagon",
      "href": "https://www.pond5.com/stock-footage/item/345678-...",
      "thumbnailUrl": "https://images.pond5.com/...",
      "tinyVideoUrl": "/tiny-videos/345678.mp4",
      "tinyVideoAvailable": true,
      "shotYear": 1962,
      "location": "Detroit, Michigan, United States",
      "formatTags": ["family", "automotive", "suburban"],
      "durationSec": 4,
      "startOffsetSec": 0,
      "rationale": "period match: 1962 • location cue: Detroit, Michigan • visual tags: family, automotive"
    }
  ]
}

Key Concepts

• Segments: Ordered list of clips with assigned durations that sum to approximately targetSeconds
• Pace: Controls how many clips are used — "fast" pace uses more, shorter clips; "slow" uses fewer, longer clips
• Diversity: The algorithm penalizes repetition of same location or era to create a varied timeline
• Tiny previews: When tinyVideoAvailable is true, a low-res preview is available at tinyVideoUrl
• Rationale: Each segment includes a human-readable explanation of why it was selected

11. API: Project Boards (Curated Collections)

Create and manage curated collections of clips. Boards are useful for organizing selections before licensing, sharing clip lists with collaborators, or building themed collections.

Endpoints

Create a Board

# Create a new board
curl -sS "https://stockfilm.com/api/boards" \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{"name": "1960s California Project", "description": "Clips for documentary edit"}'

Add a Clip to a Board

# Add a clip to a board
curl -sS "https://stockfilm.com/api/boards/1960s-california-project-a1b2c3/items" \
  -X POST \
  -H "Content-Type: application/json" \
  --data '{
    "clipId": "123456",
    "title": "Family Backyard Barbecue",
    "pond5Url": "https://www.pond5.com/stock-footage/item/123456",
    "thumbnailUrl": "https://images.pond5.com/...",
    "note": "Use at 0:45 in the timeline"
  }'

Export as CSV

# Export board as CSV for licensing workflow
curl -sS "https://stockfilm.com/api/boards/1960s-california-project-a1b2c3/export"

Boards are identified by auto-generated slugs (e.g. 1960s-california-project-a1b2c3). The slug is returned in the creation response.

12. Other API Endpoints

13. Rate Limits

Rate limits are enforced per IP address. When exceeded, the API returns429 Too Many Requests with RateLimit-* headers.

Retry strategy: On 429, read the RateLimit-Resetheader and wait before retrying. Do not retry in a tight loop.

15. Agent-Native Licensing API (Crypto Payments)

In addition to the search and board APIs above, Stockfilm operates a dedicated agent-native API at api.stockfilm.com that supports autonomous clip licensing with cryptocurrency settlement. This API is designed for AI agents that need to search, verify rights, quote, pay, and receive licensed footage without human intervention.

Base URL

https://api.stockfilm.com

Supported Payment Rails

Canonical Licensing Workflow

1. Search — POST /v1/search/assets — Find clips by text query
2. Verify Rights — POST /v1/rights/verify — Confirm the asset is eligible for your intended use
3. Quote — POST /v1/quotes — Lock in a price and select a payment rail
4. Pay — POST /v1/payment-intents — Receive payment instructions (Solana address or Lightning invoice)
5. Execute License — POST /v1/licenses/execute — Activate the license after payment confirms
6. Download — POST /v1/assets/{asset_id}/download-token — Receive a time-limited download URL

Agent API Endpoints

Search via Agent API

# Search via the agent-native API
TIMESTAMP=$(date +%s)
BODY='{"query":"1960s california family","limit":5}'
SIGNATURE=$(echo -n "${TIMESTAMP}.POST./v1/search/assets.${BODY}" \
  | openssl dgst -sha256 -hmac "$API_KEY" -hex | awk '{print $NF}')

curl -sS "https://api.stockfilm.com/v1/search/assets" \
  -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d "$BODY"

16. HMAC Request Signing

All mutating requests (POST, PUT, PATCH,DELETE) to the agent API require HMAC-SHA256 signing. GET requests only require the API key.

Required Headers for Mutations

Signing Algorithm

# HMAC-SHA256 signing formula
# payload = "{timestamp}.{METHOD}.{path}.{body}"
# signature = hex(HMAC-SHA256(api_key, payload))

TIMESTAMP=$(date +%s)
METHOD="POST"
PATH="/v1/quotes"
BODY='{"asset_id":"...","usage_scope":"commercial","selected_rail":"solana_usdc"}'

PAYLOAD="${TIMESTAMP}.${METHOD}.${PATH}.${BODY}"
SIGNATURE=$(echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$API_KEY" -hex | awk '{print $NF}')

Security notes: The API key is used as the HMAC secret — no separate signing key is needed. Timestamps older than 5 minutes are rejected. The body is included in the signature to prevent tampering.

17. Crypto Payment Flow (Solana & Lightning)

Step 1: Verify Rights

# Verify rights eligibility before quoting
curl -sS "https://api.stockfilm.com/v1/rights/verify" \
  -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"asset_id": "0f5460d8-...", "intended_use": "commercial"}'

Returns "decision": "eligible" with the full rights policy, or"decision": "ineligible" with reasons.

Step 2: Create a Quote

# Create a quote for Solana USDC payment
curl -sS "https://api.stockfilm.com/v1/quotes" \
  -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "asset_id": "0f5460d8-bfb4-4b36-914d-14678fc4dccc",
    "usage_scope": "commercial",
    "selected_rail": "solana_usdc",
    "territory": "worldwide"
  }'

Response

{
  "quote_id": "faa22846-5dc1-41cc-a791-872c80b2b361",
  "asset_id": "0f5460d8-bfb4-4b36-914d-14678fc4dccc",
  "usage_scope": "commercial",
  "territory": "worldwide",
  "price_amount_cents": 1500,
  "price_currency": "USD",
  "tier_label": "commercial:sd",
  "selected_rail": "solana_usdc",
  "expires_at": "2026-03-19T05:53:26.540858Z",
  "quote_hash": "6f664a21b988...",
  "status": "open",
  "created_at": "2026-03-19T04:53:26.541337Z"
}

Quotes expire after 1 hour (configurable via ttl_seconds). Thequote_hash ensures idempotent re-creation — same inputs produce the same quote.

Step 3: Create a Payment Intent

# Create a Solana USDC payment intent from a quote
curl -sS "https://api.stockfilm.com/v1/payment-intents" \
  -X POST \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Timestamp: $TIMESTAMP" \
  -H "X-Signature: $SIGNATURE" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"quote_id": "faa22846-5dc1-41cc-a791-872c80b2b361"}'

Response

{
  "payment_intent_id": "d111cd33-f8d3-4bc7-a925-a68a436f36c9",
  "quote_id": "faa22846-5dc1-41cc-a791-872c80b2b361",
  "license_transaction_id": "b9d3bbe4-b444-4c58-ad47-e052c506e285",
  "rail": "solana_usdc",
  "amount_cents": 1500,
  "currency": "USD",
  "status": "pending",
  "rail_payment_id": "sol-d111cd33-f8d3-4bc7-a925-a68a436f36c9",
  "instructions": {
    "recipient_address": "FERR1XDCsvLRzU8U29baMY4XvZ8kwk52tUjqy3SaDRtQ",
    "amount_usdc_micro": 15000000,
    "token": "USDC",
    "currency": "USD",
    "amount_fiat_cents": 1500,
    "memo": "StockFilm payment d111cd33-...",
    "payment_reference": "sol-d111cd33-..."
  },
  "expires_at": "2026-03-19T05:23:32.102513Z",
  "created_at": "2026-03-19T04:53:32.101658Z"
}

Payment Instructions

The instructions object contains everything needed to execute the payment:

Step 4: Check Payment Status

Poll GET /v1/payment-intents/{payment_intent_id} to check status. The status field transitions through:

Step 5: Execute License & Download

Once payment status is succeeded, activate the license and retrieve the download token:

# Activate the license
POST https://api.stockfilm.com/v1/licenses/execute
{"payment_intent_id": "d111cd33-..."}

# Get time-limited download URL (valid ~5 minutes)
POST https://api.stockfilm.com/v1/assets/{asset_id}/download-token

18. Solana Pay URL Generation

Convert payment intent instructions into a Solana Pay–compatible URI that any Solana wallet (Phantom, Solflare, etc.) can scan or deeplink. Use the helper endpoint or construct the URL yourself.

Helper Endpoint

# Generate a Solana Pay URL from payment instructions
curl -sS "https://stockfilm.com/api/agent/solana-pay-url" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_address": "FERR1XDCsvLRzU8U29baMY4XvZ8kwk52tUjqy3SaDRtQ",
    "amount_usdc_micro": 15000000,
    "token": "USDC",
    "memo": "StockFilm payment d111cd33-..."
  }'

Response

{
  "solana_pay_url": "solana:FERR1X...?amount=15&spl-token=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&memo=...",
  "recipient": "FERR1XDCsvLRzU8U29baMY4XvZ8kwk52tUjqy3SaDRtQ",
  "amount_display": "15.00 USDC",
  "token": "USDC",
  "expires_note": "Use within 30 minutes of payment intent creation."
}

Manual Construction

If you prefer to construct the URL yourself, the Solana Pay URI format is:

# USDC payment
solana:<recipient_address>?amount=<usdc_amount>&spl-token=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v&memo=<memo>

# SOL payment
solana:<recipient_address>?amount=<sol_amount>&memo=<memo>

# USDC mint address (Solana mainnet):
# EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

19. Platform Status Endpoint

Check the health of the entire Stockfilm platform — both the web app and the agent licensing API — with a single request. No authentication required.

# Check platform status (no auth required)
curl -sS "https://stockfilm.com/api/agent/status"

Response

{
  "status": "operational",
  "timestamp": "2026-03-19T04:53:00.000Z",
  "services": [
    { "service": "stockfilm-web", "status": "ok" },
    {
      "service": "stockfilm-agent-api",
      "status": "ok",
      "latency_ms": 12,
      "version": "2026-03-04",
      "rails": ["lightning_btc", "solana_sol", "solana_usdc"]
    }
  ],
  "docs": {
    "agents": "https://stockfilm.com/for-ai-agents",
    "api": "https://api.stockfilm.com",
    "llms_txt": "https://stockfilm.com/llms.txt",
    "discovery": "https://stockfilm.com/.well-known/stockfilm-agent.json"
  }
}

The status field is one of: operational (all services healthy),degraded (agent API unavailable), or partial (some services impaired).

20. Agent Discovery & Machine-Readable Endpoints

Stockfilm provides standard machine-readable discovery endpoints for AI agents, LLM tools, and autonomous systems:

Recommended integration order: Start with /llms.txt for a quick overview, then fetch /.well-known/stockfilm-agent.json for structured discovery, and finally use /v1/capabilities for full feature enumeration.

Useful Pages on Stockfilm

• Search the archive — browse and search all clips interactively
• Curated collections — themed clip collections
• Footage landing pages — browse by topic
• Browse by decade — 1930s through 1980s
• Top 100 clips — most licensed clips by revenue
• Licensing guide — detailed licensing walkthrough for humans
• AI training data — bulk dataset licensing for ML
• FAQ — frequently asked questions
• Marketplaces — all platforms where Stockfilm is available

x402 Protocol — Pay-Per-Use Licensing

Stockfilm supports the x402 protocol (V2) for instant, pay-per-use clip licensing. Any x402-compatible agent can search for clips and license them with a single HTTP request — no API keys, no sign-up, no multi-step flow.

How It Works

1. Search for clips (free): GET https://api.stockfilm.com/x402/search?q=beach
2. Get clip details (free): GET https://api.stockfilm.com/x402/clip/{clip_id}
3. Check rights (free): GET https://api.stockfilm.com/x402/clip/{clip_id}/rights
4. License a clip ($10 USDC): GET https://api.stockfilm.com/x402/clip/{clip_id}/license

The license endpoint returns HTTP 402 with a PAYMENT-REQUIRED header containing base64-encoded payment instructions. Your x402 client signs a payment authorisation, retries the request with a PAYMENT-SIGNATURE header, and receives the license + download URL.

Pricing & Payment

• Price: $10 USD per clip (144p format). Contact us for HD/4K.
• Solana USDC: payTo FERR1XDCsvLRzU8U29baMY4XvZ8kwk52tUjqy3SaDRtQ
• Base USDC: payTo 0x4AeeD280b6006Aa354e09427AF4F49bD09f9447B
• License: Royalty-free, worldwide, perpetual

x402 Networks

• solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp — Solana mainnet USDC
• eip155:8453 — Base mainnet USDC

MCP Server — AI Agent Tool Discovery

Stockfilm exposes an MCP server that AI agents (Claude, GPT, Gemini, LangChain, etc.) can connect to and discover tools automatically.

Connect with Claude Code

claude mcp add --transport http stockfilm https://api.stockfilm.com/mcp

Connect with Claude Desktop

{
  "mcpServers": {
    "stockfilm": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://api.stockfilm.com/mcp"]
    }
  }
}

Available Tools

MCP Endpoint

• URL: https://api.stockfilm.com/mcp
• Transport: Streamable HTTP
• Auth: None required (paid tools use x402 at point of purchase)

21. Contact & Support

For API keys, enterprise licensing, custom integrations, or technical questions: