feat(api): video format (firecrawl#3516)

Author: mogery

apps/api/src/__tests__/snips/v2/audio-routing.test.ts

@@ -84,6 +84,30 @@ describe("Audio format engine routing (buildFallbackList)", () => {
     expect(engines).not.toContain("fetch");
   });
 
+  it("routes video format to chrome-cdp before tlsclient", async () => {
+    const fallback = await buildFallbackList(buildStubMeta(["video"]));
+    const engines = fallback.map(f => f.engine);
+
+    expect(engines).toEqual([
+      "fire-engine;chrome-cdp",
+      "fire-engine(retry);chrome-cdp",
+      "fire-engine;tlsclient",
+    ]);
+  });
+
+  it("excludes index and non-browser engines when video format is requested", async () => {
+    const fallback = await buildFallbackList(buildStubMeta(["video"]));
+    const engines = fallback.map(f => f.engine);
+
+    expect(engines).toContain("fire-engine;chrome-cdp");
+    expect(engines).toContain("fire-engine(retry);chrome-cdp");
+    expect(engines).not.toContain("index");
+    expect(engines).not.toContain("index;documents");
+    expect(engines).not.toContain("fire-engine;chrome-cdp;stealth");
+    expect(engines).not.toContain("fire-engine(retry);chrome-cdp;stealth");
+    expect(engines).not.toContain("fetch");
+  });
+
   it("still allows chrome-cdp for non-audio requests", async () => {
     const fallback = await buildFallbackList(buildStubMeta([]));
     const engines = fallback.map(f => f.engine);

apps/api/src/__tests__/snips/v2/scrape-lockdown.test.ts

@@ -99,33 +99,34 @@ describeIf(TEST_PRODUCTION)("V2 Scrape Lockdown Mode", () => {
   );
 
   test(
-    "should serve cache and skip audio fetch even when audio format is requested",
+    "should serve cache and skip media fetch even when audio and video formats are requested",
     async () => {
       const id = crypto.randomUUID();
-      const url = "https://firecrawl.dev/?testAudioGate=" + id;
+      const url = "https://firecrawl.dev/?testMediaGate=" + id;
 
       const seed = await scrape({ url }, identity);
       expect(seed).toBeDefined();
       expect(seed.metadata.cacheState).toBe("miss");
 
       await new Promise(resolve => setTimeout(resolve, 20000));
 
-      // Without the lockdown audio gate this would either throw
-      // AudioUnsupportedUrlError (firecrawl.dev is not an audio source) or
+      // Without the lockdown media gate this would either throw an unsupported
+      // media URL error (firecrawl.dev is not an avgrab source) or
       // POST to AVGRAB_SERVICE_URL with the target URL. Success here implies
       // the gate short-circuited before any outbound call.
       const data = await scrape(
         {
           url,
           lockdown: true,
-          formats: ["markdown", "audio"],
+          formats: ["markdown", "audio", "video"],
         },
         identity,
       );
 
       expect(data).toBeDefined();
       expect(data.metadata.cacheState).toBe("hit");
       expect(data.audio).toBeUndefined();
+      expect(data.video).toBeUndefined();
     },
     scrapeTimeout * 2 + 20000,
   );

apps/api/src/__tests__/snips/v2/scrape.test.ts

@@ -2065,6 +2065,42 @@ describe("Attribute formats", () => {
     );
   });
 
+  describeIf(!TEST_SELF_HOST)("Video format", () => {
+    it.concurrent(
+      "should return video field with signed GCS URL for a supported video URL",
+      async () => {
+        const data = await scrape(
+          {
+            url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+            formats: ["video"],
+          },
+          identity,
+        );
+
+        expect(data.video).toBeDefined();
+        expect(typeof data.video).toBe("string");
+        expect(data.video).toMatch(/^https:\/\//);
+      },
+      scrapeTimeout * 2,
+    );
+
+    it.concurrent(
+      "should reject unsupported URL with video format",
+      async () => {
+        const result = await scrapeWithFailure(
+          {
+            url: "https://example.com",
+            formats: ["video"],
+          },
+          identity,
+        );
+
+        expect(result.error).toMatch(/video/i);
+      },
+      scrapeTimeout,
+    );
+  });
+
   describe("UUID validation", () => {
     it.concurrent(
       "should reject invalid UUID 'None' for scrape status",

apps/api/src/__tests__/snips/v2/types-validation.test.ts

@@ -60,6 +60,24 @@ describe("V2 Types Validation", () => {
       expect(result.formats).toEqual([{ type: "markdown" }, { type: "html" }]);
     });
 
+    it("should accept video format as string and object", () => {
+      const stringInput: ScrapeRequestInput = {
+        url: "https://example.com",
+        formats: ["video"],
+      };
+      const objectInput: ScrapeRequestInput = {
+        url: "https://example.com",
+        formats: [{ type: "video" }],
+      };
+
+      expect(scrapeRequestSchema.parse(stringInput).formats).toEqual([
+        { type: "video" },
+      ]);
+      expect(scrapeRequestSchema.parse(objectInput).formats).toEqual([
+        { type: "video" },
+      ]);
+    });
+
     it("should accept valid scrape request with json format options", () => {
       const input: ScrapeRequestInput = {
         url: "https://example.com",

apps/api/src/controllers/v2/types.ts

@@ -438,7 +438,8 @@ export type FormatObject =
   | HighlightsFormatWithOptions
   | QueryFormatWithOptions
   | { type: "branding" }
-  | { type: "audio" };
+  | { type: "audio" }
+  | { type: "video" };
 
 const pdfModeSchema = z.enum(["fast", "auto", "ocr"]);
 
@@ -550,6 +551,7 @@ const baseScrapeOptions = z.strictObject({
           highlightsFormatWithOptions,
           queryFormatWithOptions,
           z.strictObject({ type: z.literal("audio") }),
+          z.strictObject({ type: z.literal("video") }),
         ])
         .array()
         .optional()
@@ -1097,6 +1099,7 @@ export type Document = {
   images?: string[];
   screenshot?: string;
   audio?: string;
+  video?: string;
   extract?: any;
   json?: any;
   summary?: string;

apps/api/src/lib/error-serde.ts

@@ -32,6 +32,7 @@ import {
   ScrapeRetryLimitError,
   BrandingNotSupportedError,
   AudioUnsupportedUrlError,
+  VideoUnsupportedUrlError,
   XTwitterConfigurationError,
 } from "../scraper/scrapeURL/error";
 
@@ -65,6 +66,7 @@ const errorMap: Record<ErrorCodes, any> = {
   SCRAPE_SITEMAP_ERROR: SitemapError,
   CRAWL_DENIAL: CrawlDenialError,
   SCRAPE_AUDIO_UNSUPPORTED_URL: AudioUnsupportedUrlError,
+  SCRAPE_VIDEO_UNSUPPORTED_URL: VideoUnsupportedUrlError,
   SCRAPE_X_TWITTER_CONFIGURATION_ERROR: XTwitterConfigurationError,
   MAP_FAILED: MapFailedError,
 

apps/api/src/lib/error.ts

@@ -26,6 +26,7 @@ export type ErrorCodes =
   | "SCRAPE_BRANDING_NOT_SUPPORTED"
   | "AGENT_INDEX_ONLY"
   | "SCRAPE_AUDIO_UNSUPPORTED_URL"
+  | "SCRAPE_VIDEO_UNSUPPORTED_URL"
   | "SCRAPE_X_TWITTER_CONFIGURATION_ERROR"
   | "PARSE_UNSUPPORTED_OPTIONS"
   | "CRAWL_DENIAL"

apps/api/src/lib/scrape-billing.ts

@@ -90,6 +90,10 @@ export async function calculateCreditsToBeBilled(
     creditsToBeBilled += 4;
   }
 
+  if (hasFormatOfType(options.formats, "video")) {
+    creditsToBeBilled += 4;
+  }
+
   if (document.metadata?.postprocessorsUsed?.includes("x-twitter")) {
     creditsToBeBilled += xTwitterCostBonus;
   }

apps/api/src/scraper/scrapeURL/engines/fire-engine/index.ts

@@ -265,6 +265,7 @@ export async function scrapeURLWithFireEngineChromeCDP(
     });
     const hasBranding = hasFormatOfType(meta.options.formats, "branding");
     const hasAudio = hasFormatOfType(meta.options.formats, "audio");
+    const hasVideo = hasFormatOfType(meta.options.formats, "video");
     const shouldRunYoutubePostprocessor = youtubePostprocessor.shouldRun(
       meta,
       new URL(meta.rewrittenUrl ?? meta.url),
@@ -321,7 +322,7 @@ export async function scrapeURLWithFireEngineChromeCDP(
             },
           ]
         : []),
-      ...(hasAudio || shouldRunYoutubePostprocessor
+      ...(hasAudio || hasVideo || shouldRunYoutubePostprocessor
         ? ([
             {
               type: "getCookies",
@@ -464,7 +465,9 @@ export async function scrapeURLWithFireEngineChromeCDP(
       proxyUsed: response.usedMobileProxy ? "stealth" : "basic",
       youtubeTranscriptContent: response.youtubeTranscriptContent,
       timezone: response.timezone,
-      ...(hasAudio || shouldRunYoutubePostprocessor ? { audioCookies } : {}),
+      ...(hasAudio || hasVideo || shouldRunYoutubePostprocessor
+        ? { audioCookies }
+        : {}),
     };
   });
 }

apps/api/src/scraper/scrapeURL/engines/index.ts

@@ -90,6 +90,7 @@ const featureFlags = [
   "pdf",
   "document",
   "audio",
+  "video",
   "atsv",
   "location",
   "mobile",
@@ -114,6 +115,7 @@ const featureFlagOptions: {
   pdf: { priority: 100 },
   document: { priority: 100 },
   audio: { priority: 100 },
+  video: { priority: 100 },
   atsv: { priority: 90 }, // NOTE: should atsv force to tlsclient? adjust priority if not
   useFastMode: { priority: 90 },
   location: { priority: 10 },
@@ -224,6 +226,7 @@ const engineOptions: {
       pdf: false,
       document: false,
       audio: false,
+      video: false,
       atsv: false,
       mobile: true,
       location: true,
@@ -244,6 +247,7 @@ const engineOptions: {
       pdf: false,
       document: false,
       audio: true,
+      video: true,
       atsv: false,
       location: true,
       mobile: true,
@@ -264,6 +268,7 @@ const engineOptions: {
       pdf: false,
       document: false,
       audio: true,
+      video: true,
       atsv: false,
       location: true,
       mobile: true,
@@ -284,6 +289,7 @@ const engineOptions: {
       pdf: true,
       document: true,
       audio: false,
+      video: false,
       atsv: false,
       location: true,
       mobile: true,
@@ -304,6 +310,7 @@ const engineOptions: {
       pdf: false,
       document: false,
       audio: true,
+      video: true,
       atsv: false,
       location: true,
       mobile: true,
@@ -324,6 +331,7 @@ const engineOptions: {
       pdf: false,
       document: false,
       audio: true,
+      video: true,
       atsv: false,
       location: true,
       mobile: true,
@@ -344,6 +352,7 @@ const engineOptions: {
       pdf: false,
       document: false,
       audio: false,
+      video: false,
       atsv: false,
       location: false,
       mobile: false,
@@ -364,6 +373,7 @@ const engineOptions: {
       pdf: false,
       document: false,
       audio: true,
+      video: true,
       atsv: true,
       location: true,
       mobile: false,
@@ -384,6 +394,7 @@ const engineOptions: {
       pdf: false,
       document: false,
       audio: true,
+      video: true,
       atsv: true,
       location: true,
       mobile: false,
@@ -404,6 +415,7 @@ const engineOptions: {
       pdf: false,
       document: false,
       audio: false,
+      video: false,
       atsv: false,
       location: false,
       mobile: false,
@@ -424,6 +436,7 @@ const engineOptions: {
       pdf: true,
       document: false,
       audio: false,
+      video: false,
       atsv: false,
       location: false,
       mobile: false,
@@ -444,6 +457,7 @@ const engineOptions: {
       pdf: false,
       document: true,
       audio: false,
+      video: false,
       atsv: false,
       location: false,
       mobile: false,
@@ -464,6 +478,7 @@ const engineOptions: {
       pdf: false,
       document: false,
       audio: false,
+      video: false,
       atsv: false,
       location: false,
       mobile: false,
@@ -484,6 +499,7 @@ const engineOptions: {
       pdf: false,
       document: false,
       audio: false,
+      video: false,
       atsv: false,
       location: false,
       mobile: false,