StockFinder AI Documentation

1. Step-by-Step User Guide (How to Use)

Follow this complete step-by-step walkthrough to turn any raw script into an organized Pexels b-roll asset pack.

2. Prerequisites & API Keys Setup

Because StockFinder AI is 100% local and open-source, there are no monthly subscription fees or proprietary cloud servers. You simply connect your own free and pay-as-you-go API credentials:

All sensitive API keys are encrypted directly on your machine using your operating system's hardware-backed key vault:

• Windows: Microsoft Data Protection API (DPAPI) via Electron safeStorage.
• macOS: Apple Keychain Services via Electron safeStorage.
• Linux: Secret Service API / Libsecret.

3. Project Overview & What It Does

StockFinder AI is a free, open-source (MIT licensed) desktop application built for YouTube creators, documentary editors, short-form video producers, and marketing teams.

When making video content, video creators often spend 2 to 4 hours per project manually browsing stock footage websites like Pexels, guessing search keywords scene by scene, downloading clips one by one into an unorganized Downloads folder, and manually keeping track of photographer credits.

StockFinder AI completely automates this stock research phase:

• Script Decomposition: An LLM agent reads your entire narration script and splits it into structured visual beats (scenes).
• Visual Translation: Metaphors and abstract lines are translated into concrete, searchable real-world visual descriptions.
• Autonomous Media Search: The agent calls the official Pexels API to locate high-resolution 4K/HD video clips and photos matching your chosen aspect ratio and mood.
• High-Speed Multi-Threaded Downloader: Streams selected media directly into a cleanly structured project folder on your machine.
• Automatic Attribution: Generates a full credits manifest and YouTube description block complying with the Pexels License.

4. How the AI Agent Loop Works

StockFinder AI uses a secure tool-calling agent loop rather than simple keyword replacement. The backend agent interacts with Pexels and the file system through a strict four-tool contract:

// 1. Search Pexels Photos for a specific beat
search_pexels_photos({ beatId, query, orientation, size, color, page, perPage })

// 2. Search Pexels Videos for a specific beat
search_pexels_videos({ beatId, query, orientation, size, page, perPage })

// 3. Select candidates with reasoning & log rejections
select_assets_for_download({
  selections: [{ beatId, assetType: 'video', pexelsId: 123456, reason: 'Matches moody lighting' }],
  rejections: [{ beatId, assetType: 'photo', pexelsId: 789012, reason: 'Wrong framing' }]
})

// 4. Trigger download queue with optional approval lock
download_selected_assets({ assets: [{ assetType: 'video', pexelsId: 123456 }] })

Rate-Limit & Cache Protection: To ensure you never exhaust your Pexels API quota, all search queries are hashed and cached locally for 1 hour. If a network blip occurs, exponential backoff retries the request automatically.

5. Human-in-the-Loop Review Controls

AI search is fast, but video creators have distinct visual taste. StockFinder AI gives you granular control over what gets saved to your disk:

• Review Lock: When requireApprovalBeforeDownload is enabled in settings, the runner pauses after asset selection and emits an awaiting_user_approval event.
• Per-Asset Decisions: Accept or reject individual clips per scene beat.
• Resume Continuity: If you close the app or pause a run, StockFinder AI preserves your session state and continues where you left off.
• Rerun Failed Jobs: Retry individual failed beats or whole projects with a single click without re-entering your script.

6. Project Folder & Manifest Structure

Each project is saved in its own organized directory within your configured download folder:

MyDownloadFolder/
└── the-future-of-artificial-intelligence/
    ├── manifest.json         # Full project settings, visual beats, and media metadata
    ├── agent-log.jsonl       # Structured JSON log of all agent thoughts, tool calls, and timings
    ├── videos/               # High-resolution MP4/WebM video files
    │   ├── beat_1_1234567_futuristic_city.mp4
    │   └── beat_2_8901234_robot_hands.mp4
    ├── photos/               # High-resolution JPG/PNG/WebP image files
    │   └── beat_3_5678901_microchip.jpg
    └── thumbnails/           # Low-resolution previews for quick UI inspection

7. Importing Assets into Video Editors

Because assets are grouped into standard MP4 and JPG files with sanitized file names, importing your new b-roll pack takes seconds:

8. Pexels Attribution & License Compliance

All media downloaded from Pexels is free to use for commercial and non-commercial purposes under the Pexels License. Attribution is not strictly legally required by Pexels, but it is heavily encouraged and appreciated by photographers and creators.

StockFinder AI generates a clean attribution block in one click:

Stock footage provided by Pexels:
- Futuristic City by Jane Doe (https://www.pexels.com/@janedoe)
- Robotic Arm by John Smith (https://www.pexels.com/@johnsmith)
- Data Server Room by Media Producer (https://www.pexels.com/@producer)

Curated with StockFinder AI (https://stockfinderai.birol.tech)

9. Performance & Safety Configuration

Customize StockFinder AI to match your hardware and editorial guidelines in the Settings tab:

• Max Concurrent Downloads: Adjust between 1 and 5 parallel download streams based on your network bandwidth.
• Request Timeout: Sets maximum timeout duration (default: 30 seconds) before aborting hanging API connections.
• Avoid Faces and People: Injects negative prompts into stock searches to favor objects, nature, architecture, and technology over human closeups.
• Skip Explicit Queries: Automatically sanitizes adult, violent, or sensitive terms from stock search queries.

10. Architecture & Developer Reference

StockFinder AI is built on a modern, secure Electron stack:

• Electron 39: Multi-process desktop container with strict context isolation.
• React 19 & Vite: High-performance renderer bundle with instant hot reloading during development.
• Tailwind CSS 4: Industrial risograph dark theme with custom glassmorphic components.
• Zustand: Fast, lightweight reactive state management.
• Node.js IPC: Sandboxed main process handling filesystem, cryptography, and network requests safely.

To run or build StockFinder AI from source code:

# 1. Clone repository
git clone https://github.com/birol-dev/Pexels.git
cd Pexels

# 2. Install dependencies
npm install

# 3. Start in development mode (hot reload)
npm run dev

# 4. Build native desktop installer
npm run build:win   # Windows installer (.exe)
npm run build:mac   # macOS app bundle (.dmg)
npm run build:linux # Linux AppImage & .deb

11. Troubleshooting & FAQ

"Invalid Pexels API Key" Error

Ensure your Pexels key does not contain leading or trailing spaces. Verify that your account at pexels.com/api has an approved active application.

"LLM Rate Limit (429)" Error

If you hit rate limits with your LLM provider, switch the model in Settings (e.g. from gpt-4o to gpt-4o-mini, or from gemini-1.5-pro to gemini-2.5-flash) or increase your project timeout limit.

Missing Video Previews in Media Library

StockFinder AI uses a custom media:// protocol to safely stream local video files without CORS errors. If a video fails to play, check that your system has standard H.264/WebM codecs installed.

Can I run StockFinder AI without internet?

The desktop application itself runs locally, but an active internet connection is required during the agent run to query the LLM API and stream media assets from Pexels servers.