FrameThrower API

https://framethrower.ai/api/v1

{
  "data": [ ... ] or { ... },   // the result(s)
  "meta": {                      // context about the request
    "total": 20,
    "query": "...",
    "mode": "hybrid",
    ...
  }
}

{
  "id": "ac75d913-...",
  "imageUrl": "https://frames.shotspot.pro/core/ac75d913....jpg",
  "thumbUrl": "https://frames.shotspot.pro/thumb/ac75d913....jpg.webp",
  "depthUrl": "https://frames.shotspot.pro/depth/ac75d913....jpg.webp"
}

# Search, then feed the geometry straight into a generation
curl -s https://framethrower.ai/api/v1/search \
  -H "Authorization: Bearer $FT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"low-angle staircase, hard shadows","limit":4}' \
| jq -r '.data[].depthUrl'

curl -s -o depth.webp \
  "https://frames.shotspot.pro/depth/ac75d913....jpg.webp"   # no token

Authorization: Bearer ft_your_token_here
Content-Type: application/json

{
  "name": "framethrower_search",
  "description": "Search FrameThrower's film frame library by concept, mood, lighting, color, or composition. Returns thumbnails + metadata + deep links. Use for finding visual references.",
  "parameters": {
    "type": "object",
    "properties": {
      "query": { "type": "string", "description": "Natural language search (e.g. 'overhead dinner table warm candlelight')" },
      "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }
    },
    "required": ["query"]
  }
}

npm install framethrower-ai

import FrameThrower from 'framethrower-ai'

const ft = new FrameThrower('ft_YOUR_TOKEN')

// Search by text, colour, or image
const frames = await ft.search('neon rain at night')
const warm   = await ft.searchByColor(['#e8a87c', '#1b4332'])
const like   = await ft.searchByImage('https://example.com/photo.jpg')

// Browse by craft, then follow a frame into its film
const shots = await ft.browse({ shot_type: 'close-up', lens_character: 'anamorphic' })
const detail = await ft.frame(frames[0].id)   // detail.prompt is a composed image prompt
const more   = await ft.similar(frames[0].id, { mode: 'visual' })

const films = await ft.films({ q: 'kubrick', sort: 'frames' })
const film  = await ft.film(films[0].slug)

{
  "query": "neon-lit rainy street at night",
  "limit": 20,
  "mode": "hybrid"
}

{ "imageUrl": "https://example.com/reference.jpg", "limit": 20 }

// Single color
{ "color": "#e94560" }

// Palette (blended)
{ "colors": ["#e94560", "#1a1a2e", "#16213e"], "limit": 20 }

{
  "shot_type": "close-up",          // or "wide", "medium", "extreme-close-up"
  "lens_character": "anamorphic",   // or "spherical", "vintage_soft"
  "setting": "exterior",            // or "interior"
  "time_of_day": "night",           // or "day", "golden_hour", "blue_hour"
  "camera_angle": "low_angle",      // or "high_angle", "eye_level", "overhead"
  "visual_style": "noir",           // or "naturalistic", "stylized"
  "director": "Denis Villeneuve",
  "genre": "Science Fiction",
  "era": "2010s",
  "year_min": 2010,
  "year_max": 2025,
  "limit": 20
}

// Single frame
{ "frameId": "abc123", "mode": "semantic", "limit": 20 }

// Multiple frames (averaged — finds the centroid)
{ "frameIds": ["abc", "def", "ghi"], "mode": "visual", "limit": 20 }

// Response shape
{
  "data": {
    "id": "abc123",
    "imageUrl": "https://frames.shotspot.pro/core/...",
    "thumbUrl": "https://frames.shotspot.pro/thumb/...",
    "deepLink": "https://framethrower.ai/#frame/abc123",
    "prompt": "A lone figure walks through dense orange haze toward a distant structure. Set in exterior, day. Diffused amber backlight with atmospheric haze. Desaturated warm tones dominated by deep orange and ochre. Naturalistic style with a melancholy, atmospheric, isolation mood.",
    "film": {
      "title": "Blade Runner 2049", "year": 2017,
      "director": "Denis Villeneuve", "dp": "Roger Deakins",
      "genres": ["Science Fiction", "Drama"],
      "tmdbId": 335984, "imdbId": "tt1856101"
    },
    "metadata": {
      "sceneDescription": "A lone figure walks through orange haze...",
      "shotType": "wide", "cameraAngle": "eye_level",
      "lensCharacter": "anamorphic",
      "lightingKey": "low_key",
      "lightingDescription": "Diffused amber backlight with atmospheric haze",
      "moods": ["melancholy", "atmospheric", "isolation"],
      "colorPalette": ["#c45a28", "#1a1a2e", "#e8a87c"],
      "era": "2010s", "setting": "exterior", "timeOfDay": "day"
    }
  }
}

// Response
{
  "data": {
    "films": [
      { "type": "film", "title": "2001: A Space Odyssey", "year": 1968,
        "director": "Stanley Kubrick", "posterUrl": "...", "imdbId": "..." }
    ],
    "people": [
      { "type": "person", "name": "Stanley Kubrick", "slug": "stanley-kubrick",
        "portraitUrl": "...", "filmCount": 12 }
    ]
  }
}

GET /api/v1/films/blade-runner-2049-2017

# Search
curl -s -X POST https://framethrower.ai/api/v1/search \
  -H "Authorization: Bearer ft_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "overhead shot dinner table warm light"}' \
  | jq '.data[:3] | .[] | {title: .film.title, url: .deepLink}'

# Browse by craft
curl -s -X POST https://framethrower.ai/api/v1/browse \
  -H "Authorization: Bearer ft_YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"shot_type": "close-up", "lens_character": "anamorphic", "limit": 5}' \
  | jq '.data | length'

# Autocomplete
curl -s "https://framethrower.ai/api/v1/suggest?q=nolan" \
  -H "Authorization: Bearer ft_YOUR_TOKEN" \
  | jq '.data.films[].title'

import requests

TOKEN = "ft_YOUR_TOKEN"
H = {"Authorization": f"Bearer {TOKEN}"}

# 1. Find candidate references.
hits = requests.post(f"https://framethrower.ai/api/v1/search", headers=H,
    json={"query": "low-angle staircase, hard shadows", "limit": 5}).json()["data"]

frame = hits[0]

# 2. The composed prompt lives on frame detail, not on search results.
detail = requests.get(f"https://framethrower.ai/api/v1/frames",
    headers=H, params={"id": frame["id"]}).json()["data"]

prompt = detail["prompt"]          # scene + people + lighting + colour + mood
scene  = frame["metadata"]["sceneDescription"]   # just the description, no extra call

# 3. The depth map is a plain public file — no token, and do not send one.
depth = frame["depthUrl"]
if depth:
    r = requests.get(depth, timeout=30)     # NOT urllib: our CDN 403s its user-agent
    if r.ok:
        open("depth.webp", "wb").write(r.content)
    else:
        depth = None                        # rare miss — fall back to computing it

# 4. Hand both to whatever you generate with.
print(prompt)
print("depth map:", "depth.webp" if depth else "compute locally")

import requests

TOKEN = "ft_YOUR_TOKEN"
H = {"Authorization": f"Bearer {TOKEN}"}

# Search by concept
r = requests.post(f"https://framethrower.ai/api/v1/search", headers=H,
    json={"query": "anamorphic close-up blue hour", "limit": 5})
for f in r.json()["data"]:
    print(f'{f["film"]["title"]} — {f["deepLink"]}')

# Find by color
r = requests.post(f"https://framethrower.ai/api/v1/search/color", headers=H,
    json={"colors": ["#c45a28", "#1a1a2e"]})
print(f'{len(r.json()["data"])} frames match that palette')

# Browse craft
r = requests.post(f"https://framethrower.ai/api/v1/browse", headers=H,
    json={"director": "Wong Kar-wai", "time_of_day": "night"})
for f in r.json()["data"]:
    print(f'{f["film"]["title"]} — {f["metadata"]["lensCharacter"]}')

const TOKEN = "ft_YOUR_TOKEN";
const api = (path, body) =>
  fetch(`https://framethrower.ai/api/v1${path}`, {
    method: body ? "POST" : "GET",
    headers: { "Authorization": `Bearer ${TOKEN}`, "Content-Type": "application/json" },
    body: body ? JSON.stringify(body) : undefined,
  }).then(r => r.json());

// Script → visual references workflow
async function findRefsForScene(sceneDescription) {
  // 1. Search by scene text
  const { data: results } = await api("/search", {
    query: sceneDescription, limit: 10
  });

  // 2. Pick the best match, find more like it
  if (results.length > 0) {
    const { data: similar } = await api("/similar", {
      frameId: results[0].id, mode: "visual", limit: 5
    });
    return [...results.slice(0, 5), ...similar];
  }
  return results;
}

// Use it
const refs = await findRefsForScene(
  "candlelit dinner party in a grand ballroom, wide shot, warm"
);
refs.forEach(f => console.log(f.film.title, f.thumbUrl));