canonical: https://jentic.com/apis/framethrower.ai/framethrower # FrameThrower API The FrameThrower API searches a film stills library indexed frame by frame on lighting, lens character, shot size, camera angle, colour palette, and mood, so an application can find cinematography references in plain language, by a reference image, or by colour. You search by text, image, or colour, browse by craft attribute, find frames similar to one you like, and read frame and film detail. Responses carry metadata, thumbnail URLs, colour palettes, and deep links rather than raw image bytes, since the frames are reference material whose rights stay with their owners. ## For AI agents Search a film stills library by text, reference image, or colour, browse by craft attribute, and find similar frames in FrameThrower. Authenticates with a bearer personal access token. ## Scope Does not deliver or license raw image files, edit images, or process video. Use for searching and discovering film stills by visual attributes only. ## Capabilities - Search the film stills library in plain language by craft attributes - Search by a reference image to find visually matching frames - Search by colour to find frames with a target palette - Browse frames filtered by a craft attribute such as shot size or camera angle - Find frames visually similar to a chosen frame - Read frame detail and film detail with thumbnails, palettes, and deep links ## Use cases ### Agent-Driven Shot Reference An AI agent connected through Jentic finds cinematography references for a creative brief by searching the library in plain language, then returning frames with their metadata, colour palettes, and deep links, so a director of photography builds a lookbook without scrubbing films by hand. Because FrameThrower indexes craft attributes, the agent can narrow a search to a specific shot size or lens character. Example prompt: Search for moody low-key close-ups on long lenses and return the top frames with their colour palettes and deep links ### Reference-Image and Colour Search A visual workflow finds matching frames from a picture or a colour target by searching by reference image or by colour, so an art department can match a mood board to real shots. FrameThrower also finds frames similar to one you already like, so the workflow can pivot from a single good match to a set of related references. Example prompt: Search by this reference image, then expand the result with frames visually similar to the best match ### Film Catalogue Browsing A discovery workflow browses the film catalogue and reads each film's frames, so an editor can explore a title's visual language shot by shot. Autocomplete suggestions help the workflow resolve a film or attribute before it searches, so a vague query lands on the right title. Example prompt: List the films in the catalogue and return the frames for a chosen title ## Key endpoints | Method | Path | Description | | --- | --- | --- | | POST | `/search` | Search film stills by text | | POST | `/search/image` | Search by a reference image | | POST | `/search/color` | Search by colour | | POST | `/similar` | Find similar frames | | POST | `/browse` | Filter frames by a craft attribute | | GET | `/frames` | Get frame detail | | GET | `/films` | List the film catalogue | | GET | `/films/{slug}` | Get film detail | ## Key resources - **Search** — Text, reference-image, and colour search plus craft-attribute browse and similarity - **Frames** — Frame detail with metadata, thumbnails, colour palettes, and deep links - **Films** — Film catalogue and per-film frame listings - **Discovery** — Autocomplete suggestions and random frame sampling ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 61 / 100 - **Maturity:** AI-Aware - **Dimensions:** - Foundational Compliance: 74 / 100 - Developer Experience & Jentic Compatibility: 63 / 100 - AI-Readiness & Agent Experience: 42 / 100 - Agent Usability: 94 / 100 - Security: 60 / 100 - AI Discoverability: 68 / 100 - **View full report:** https://jentic.com/apis/framethrower.ai/framethrower/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring the FrameThrower API by hand means handling its ft_ bearer token and building three different search request shapes for text, image, and colour. Through Jentic you install once, import FrameThrower from the API Directory, store the token once, and your agent calls it. - **Permission scoping:** FrameThrower is a read-only search API, so you choose which operations your agent may call: you can allow searching and browsing frames and leave nothing destructive on the table, because there is nothing destructive to grant. Rules bound which operations run, so the agent searches within the surface you allow. - **Credential handling:** Your FrameThrower token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'find film stills by description' or 'search frames by colour', and Jentic returns the matching FrameThrower operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Shutterstock API** — Stock media library with search across images, footage, and music - **Pexels API** — Free stock photo and video library with keyword search - **Cloudinary Upload API** — Image and video upload, transformation, and delivery ## FAQ ### Is there a FrameThrower MCP server? You don't need an MCP server to give your agent the FrameThrower API. Jentic connects it directly from the API Directory: import it, store your token once, and your agent can search film stills by text, image, or colour straight away, with no extra server to run and no tool definitions sitting in the agent's context. ### Can I limit what my agent is allowed to do with the FrameThrower API? Yes. FrameThrower is a read-only search API, so you can write a rule that allows only the search and browse operations the agent needs and nothing else. Every call the agent makes is logged, so you can see exactly which searches it ran. ### What authentication does the FrameThrower API use? The FrameThrower API authenticates with a bearer personal access token, prefixed ft_, per its OpenAPI spec. Through Jentic the token is stored encrypted by your own instance and added to each request at call time, so it never appears in the agent's prompt or logs. ### Can I search frames by colour with the FrameThrower API? Yes. One operation searches by colour to find frames built around a target palette, alongside text search and reference-image search. Each result carries the frame's colour palette and a deep link, so an agent can rank matches and point back to the source. ### What are the rate limits for the FrameThrower API? The OpenAPI spec does not state request rate limits for the FrameThrower API. For current limits and fair-use guidance, check the provider documentation at https://framethrower.ai. ### How do I search for a shot through Jentic? Import the FrameThrower API from the Jentic API Directory, then have your agent issue a request such as 'find moody night exteriors on wide lenses'. Jentic matches the intent to the text-search operation and returns its input schema so the agent builds the correct request, with your stored token injected at call time. To run it on your own infrastructure, install Jentic One from its GitHub repo.