framethrower-ai

The official JavaScript/TypeScript client for the FrameThrower API — a film stills database of 5,489 films, indexed frame by frame on lighting, lens character, shot size, colour and mood.

Search in plain language, by reference image, or by colour. Every result comes back with its film, director, cinematographer, colour palette and a deep link.

npm install framethrower-ai

import FrameThrower from 'framethrower-ai'

const ft = new FrameThrower('ft_your_token')

const frames = await ft.search('neon-lit rainy street at night', { limit: 5 })

for (const f of frames) {
  console.log(f.film.title, f.film.year, '—', f.url)
}

What it costs

$2 of credits free on signup, no card, no plan. After that it is usage-based: $1 = 1,000 credits, and a search costs 2 — so $1 buys 500 searches. Credits never expire. There are no rate limits.

| | | |---|---| | Free on signup | $2 of credits (2,000), no card | | Rate | $1 = 1,000 credits | | A search | 2 credits | | An image search | 10 credits | | Autocomplete | free | | Rate limits | none |

Get a token

1. Sign up at framethrower.ai — free, no card
2. Go to Settings → API
3. Create token, copy it

Your free signup credits work through the API from the first call. No paid plan is required.

All methods

Costs are per call.

| Method | Credits | Description | |--------|---------|-------------| | ft.search(query, { limit?, mode? }) | 2 | Text search — mode: 'hybrid' (default) or 'description' | | ft.searchByColor(hex or hex[], limit?) | 2 | Colour palette search | | ft.searchByImage(url, limit?) | 10 | Image similarity search — runs a model on the image | | ft.browse({ shot_type?, director?, ... }) | 2 | Filter by craft attribute | | ft.similar(frameId, { mode?, limit? }) | 2 | Find similar frames | | ft.similarFrom(frameIds[], { mode?, limit? }) | 2 | Similar from several at once | | ft.frame(id) | 2 | Frame detail + the AI prompt for that frame | | ft.random(limit?) | 2 | Random sample | | ft.films({ q?, sort?, minFrames?, page? }) | 2 | Film catalogue with poster + frameCount | | ft.film(slug) | 2 | Film detail | | ft.filmFrames(slug, { page?, perPage? }) | 2 | A film's frames | | ft.filmFramesPage(slug, { page?, perPage? }) | 2 | Same, plus the film's total frame count | | ft.suggest(query) | 0 | Autocomplete films and people — free |

More ways in

// Colour
const warm = await ft.searchByColor(['#e8a87c', '#1b4332'])

// A reference image
const matches = await ft.searchByImage('https://example.com/photo.jpg')

// Craft attributes
const shots = await ft.browse({ shot_type: 'close-up', lens_character: 'anamorphic' })

// A frame's full detail, including the AI prompt describing it
const detail = await ft.frame(frames[0].id)
console.log(detail.prompt)

// More like this one
const more = await ft.similar(frames[0].id, { mode: 'visual' })

// The catalogue, best-covered films first
const films = await ft.films({ q: 'kubrick', sort: 'frames' })
console.log(films[0].title, films[0].frameCount)  // 2001: A Space Odyssey 68

From a frame to its film

Every frame carries its film's slug and frameCount, so any result is a jumping-off point:

const [frame] = await ft.search('rain on a window')
frame.film.slug        // 'blade-runner-1982'
frame.film.frameCount  // 57
const siblings = await ft.filmFrames(frame.film.slug)

Search modes

hybrid (the default) fuses the frame's image embedding with its scene-description embedding — use it unless you have a reason not to. description ranks on the written descriptions alone, which is better when the query is about story, action, or named objects.

Running out of credits

A call with an insufficient balance returns HTTP 402 with everything needed to recover, so an agent can explain itself rather than failing silently:

{
  "error": "Not enough credits: this call costs 2, your balance is 0.",
  "code": "insufficient_credits",
  "cost": 2,
  "balance": 0,
  "buy_credits": "https://framethrower.ai/settings?tab=billing"
}

Every metered response also carries X-Credits-Cost and X-Credits-Remaining, so you can track spend without a second call.

What you get back — and what you don't

Responses carry metadata, thumbnail URLs, extracted colour palettes and deep links back to FrameThrower. Never raw image bytes. This is a reference and discovery tool, not an image-delivery pipe: the frames are not ours to license, and rights remain with their owners. See intended use.

Also available

• MCP server — framethrower.ai/mcp. Four tools (search_frames, find_by_craft, find_similar, get_frame_details) over OAuth 2.1, for Claude, Cursor and any MCP client.
• REST API — 11 endpoints. The machine-readable spec is at framethrower.ai/api/v1; docs at framethrower.ai/developers.

About

FrameThrower is the reference app for the future creative: one of the largest film still libraries on the internet, callable from a REST API, an MCP server and an npm SDK. Built by senior filmmakers and ads creatives, for working film professionals.

MIT licensed.