‏API فریم‌تروور: جستجو تو کتابخونه‌ی فریم‌های سینمایی

FrameThrower یه کتابخونه‌ی رفرنس تصویری از فریم‌های فیلم‌هاست که فیلمسازها برای پیدا کردن حس و نور و ترکیب‌بندی ازش استفاده می‌کنن. حالا همین کتابخونه یه API هم داره که هم برای آدم‌ها و هم برای agentها و LLMها طراحی شده. خروجی‌ها همه JSON هستن و به جای خود عکس، متادیتا و لینک thumbnail و لینک مستقیم به فریم برمی‌گردونن.

چهار نوع جستجو داره: جستجوی متنی (مثلاً «خیابون بارونی با نور نئون»)، جستجو با تصویر، جستجو با رنگ (یه رنگ hex یا یه پالت تا شش رنگ) و browse by craft. این آخری از همه جالب‌تره، چون می‌شه فقط بر اساس اینکه نما چطوری گرفته شده فیلتر کرد: نوع نما، زاویه‌ی دوربین، کاراکتر لنز مثل anamorphic، ساعت روز، کارگردان و دهه. یه endpoint هم برای «فریم‌های شبیه این» هست که اگه چند فریم بهش بدی، میانگین‌شون رو حساب می‌کنه.

یه نکته‌ای که مستندات روش تأکید دارن اینه که نتیجه‌ی جستجو و جزئیات یه فریم شکل یکسانی ندارن. فیلد prompt (یه پرامپت آماده برای ساخت تصویر) فقط از /frames?id= میاد. پس الگوی معمول اینه که اول جستجو کنی و بعد برای چند فریمی که نگه می‌داری جزئیات بگیری:

const frames = await ft.search('neon rain at night')
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

هر فریم از قبل با مدل Depth-Anything V2 پردازش شده و فیلد depthUrl رو داره. depth map یعنی یه تصویر خاکستری که نزدیک‌ها روشن و دورها تاریکن. اندازه‌ش دقیقاً با فریم یکیه، پس مستقیم می‌ره تو یه depth ControlNet. این فایل هزینه نداره و توکن هم لازم نداره. اگه نقشه نباشه مقدارش null می‌شه و هیچ‌وقت عکس رنگی رو جاش نمی‌ده، چون به گفته‌ی مستندات اون یه نتیجه‌ی غلط ولی با اعتمادبه‌نفس می‌ساخت.

چند تا نکته‌ی عملی هم داره: سرور تصاویر هدر CORS نمی‌فرسته، پس تو مرورگر باید فایل رو از سمت سرور خودت بخونی. CDN هم user-agent پیش‌فرض urllib پایتون رو بلاک می‌کنه، ولی requests و httpx مشکلی ندارن. یه SDK جاوااسکریپتی به اسم framethrower-ai با تایپ‌های TypeScript، یه spec از نوع OpenAPI و یه سرور MCP هم برای وصل کردن agentها هست.

قیمت‌گذاری بر اساس اعتباره: حساب جدید ۲ دلار اعتبار رایگان می‌گیره، بیشتر درخواست‌ها ۲ اعتبار و جستجو با تصویر ۱۰ اعتبار هزینه داره. هر دلار هزار اعتباره، پس با یه دلار ۵۰۰ تا جستجو می‌شه کرد. سازنده‌ها می‌گن عمداً rate limit نذاشتن و اعتبار هم منقضی نمی‌شه.

نکات کلیدی:

• چهار نوع جستجو: متن، تصویر، رنگ (تا ۶ رنگ hex) و فیلتر بر اساس ویژگی‌های فیلم‌برداری
• فیلد prompt فقط تو جزئیات فریم (/frames?id=) هست، نه تو نتیجه‌ی جستجو
• depth map با Depth-Anything V2، هم‌اندازه با فریم، رایگان و بدون نیاز به توکن
• ۲ دلار اعتبار اولیه؛ هر جستجو ۲ اعتبار، جستجو با تصویر ۱۰ اعتبار، بدون rate limit
• SDK جاوااسکریپت framethrower-ai، spec از نوع OpenAPI و سرور MCP برای agentها