Search

Search by text

Describe a mood, scene or visual concept in natural language.

Cost: 2 credits. $1 = 1,000 credits. Returns 402 when the balance is short.

post/search

Request

  • Base URL: https://framethrower.ai/api/v1
  • URL: https://framethrower.ai/api/v1/search
  • Auth: HTTP bearer

Request body

querystring required

Natural-language query

limitinteger
mode'hybrid' | 'description'

hybrid fuses the image and scene-description embeddings via reciprocal rank fusion — use it unless you have a reason not to. description ranks on the written descriptions only, better when the query is about story, action or named objects.

colorstring

Bias the search toward frames dominated by this colour, without abandoning the query. Fused with the text ranking rather than replacing it — "ocean" with #1f7a8c returns teal seas, not teal anything. For colour alone, use /search/color.

enhanceboolean

Rewrite the query into the descriptive register the frames were embedded from before searching — "man on fire" becomes a full sentence. Benchmarked recall@10: 0.72 raw, 0.88 enhanced. This is what the website does by default. Adds ~1s on a cache miss and falls back to the raw query on error. When it fires, the rewritten text comes back as meta.enhancedQuery — send that as the query for later pages so every page ranks in the same neighbourhood.

offsetinteger

Skip this many results before returning. Use with limit to page: offset 0 then 50 then 100. Capped at 500 — ranking past that is noise, and the candidate pool is built to offset+limit.

shot_type'medium' | 'closeup' | 'wide' | 'fullbody' | 'establishing'

Shot size. Aliased, so close-up and closeup both land.

camera_angle'eye_level' | 'high_angle' | 'low_angle' | 'top_down' | 'overhead' | 'worms_eye' | 'dutch_angle' | 'pov' | 'birds_eye'

Camera angle.

time_of_day'night' | 'day' | 'interior_indeterminate' | 'golden_hour' | 'dusk' | 'blue_hour' | 'dawn' | 'overcast'

Time of day / light.

setting'interior' | 'exterior' | 'both'

Interior or exterior.

visual_style'live_action' | 'cg_stylized' | 'anime' | 'cg_photorealistic' | 'cartoon_2d' | 'stop_motion' | 'mixed_media' | 'rotoscope' | 'noir' | 'watercolor' | 'minimalist' | 'documentary' | 'expressionist' | 'painterly' | 'surreal'

Medium and treatment.

lens'anamorphic' | 'spherical' | 'vintage_soft'

Lens character.

lighting'sun' | 'window' | 'moonlight' | 'practical' | 'neon' | 'fluorescent' | 'firelight' | 'candlelight' | 'streetlamp' | 'screen_glow' | 'headlight' | 'lightning'

What is lighting the frame — a different question from the time of day.

depth_of_field'shallow' | 'deep' | 'rack_focus' | 'medium'

Focus depth.

directorstring
genrestring
film_titlestring
era'ancient' | 'medieval' | 'renaissance' | '1800s' | '1900s_1910s' | '1920s' | '1930s' | '1940s' | '1950s' | '1960s' | '1970s' | '1980s' | '1990s' | '2000s' | '2010s' | 'contemporary' | 'near_future' | 'far_future' | 'fantasy'

The era depicted on screen, not the release year.

year_mininteger
year_maxinteger

Example request

{
  "query": "neon-lit rainy street at night",
  "color": "#1f7a8c"
}

Response

Matching frames

metaobject

Changes