@framers/agentos 0.1.120 → 0.1.121

package/dist/core/video/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @file index.ts
+ * Barrel export for the video generation and analysis subsystem.
+ *
+ * Re-exports all public types, interfaces, and the fallback proxy so
+ * consumers can import from `@agentos/core/video` (or the relative path)
+ * without reaching into individual files.
+ *
+ * Also provides a provider factory registry (modelled on the image
+ * subsystem's pattern) so that built-in and third-party video providers
+ * can be registered and instantiated by provider ID.
+ */
+import type { IVideoGenerator } from './IVideoGenerator.js';
+export * from './types.js';
+export * from './IVideoGenerator.js';
+export * from './IVideoAnalyzer.js';
+export * from './FallbackVideoProxy.js';
+export * from './VideoAnalyzer.js';
+/** A factory function that creates an uninitialised video provider instance. */
+export type VideoProviderFactory = () => IVideoGenerator;
+/**
+ * Register a video provider factory for a given provider ID.
+ *
+ * Use this to add third-party or custom video providers at runtime.
+ * Built-in providers (runway, replicate, fal) are pre-registered.
+ *
+ * @param providerId - Unique identifier for the provider (lowercased for matching).
+ * @param factory - Factory function that creates a new uninitialised provider instance.
+ */
+export declare function registerVideoProviderFactory(providerId: string, factory: VideoProviderFactory): void;
+/**
+ * Create a video provider instance by provider ID.
+ *
+ * Looks up the factory in the registry and returns a new uninitialised
+ * provider. The caller must call `provider.initialize(config)` before use.
+ *
+ * @param providerId - Provider identifier (e.g. `"runway"`, `"replicate"`, `"fal"`).
+ * @returns A new uninitialised {@link IVideoGenerator} instance.
+ * @throws {Error} When no factory is registered for the given provider ID.
+ */
+export declare function createVideoProvider(providerId: string): IVideoGenerator;
+/**
+ * Check whether a video provider factory is registered for the given ID.
+ *
+ * @param providerId - Provider identifier to check.
+ * @returns `true` if a factory exists for this provider.
+ */
+export declare function hasVideoProviderFactory(providerId: string): boolean;
+/**
+ * List all registered video provider factory IDs, sorted alphabetically.
+ *
+ * @returns Sorted array of registered provider identifiers.
+ */
+export declare function listVideoProviderFactories(): string[];
+//# sourceMappingURL=index.d.ts.map

package/dist/core/video/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/video/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAK5D,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AAMnC,gFAAgF;AAChF,MAAM,MAAM,oBAAoB,GAAG,MAAM,eAAe,CAAC;AAczD;;;;;;;;GAQG;AACH,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,oBAAoB,GAC5B,IAAI,CAEN;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,eAAe,CAMvE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAEnE;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,EAAE,CAErD"}

package/dist/core/video/index.js

@@ -0,0 +1,78 @@
+/**
+ * @file index.ts
+ * Barrel export for the video generation and analysis subsystem.
+ *
+ * Re-exports all public types, interfaces, and the fallback proxy so
+ * consumers can import from `@agentos/core/video` (or the relative path)
+ * without reaching into individual files.
+ *
+ * Also provides a provider factory registry (modelled on the image
+ * subsystem's pattern) so that built-in and third-party video providers
+ * can be registered and instantiated by provider ID.
+ */
+import { FalVideoProvider } from './providers/FalVideoProvider.js';
+import { ReplicateVideoProvider } from './providers/ReplicateVideoProvider.js';
+import { RunwayVideoProvider } from './providers/RunwayVideoProvider.js';
+export * from './types.js';
+export * from './IVideoGenerator.js';
+export * from './IVideoAnalyzer.js';
+export * from './FallbackVideoProxy.js';
+export * from './VideoAnalyzer.js';
+/**
+ * Internal registry mapping provider IDs to provider constructors.
+ *
+ * Built-in providers (Runway, Replicate, Fal) are pre-registered here so the
+ * public `createVideoProvider()` API remains synchronous and ESM-safe.
+ */
+const videoProviderFactories = new Map([
+    ['runway', () => new RunwayVideoProvider()],
+    ['replicate', () => new ReplicateVideoProvider()],
+    ['fal', () => new FalVideoProvider()],
+]);
+/**
+ * Register a video provider factory for a given provider ID.
+ *
+ * Use this to add third-party or custom video providers at runtime.
+ * Built-in providers (runway, replicate, fal) are pre-registered.
+ *
+ * @param providerId - Unique identifier for the provider (lowercased for matching).
+ * @param factory - Factory function that creates a new uninitialised provider instance.
+ */
+export function registerVideoProviderFactory(providerId, factory) {
+    videoProviderFactories.set(providerId.toLowerCase(), factory);
+}
+/**
+ * Create a video provider instance by provider ID.
+ *
+ * Looks up the factory in the registry and returns a new uninitialised
+ * provider. The caller must call `provider.initialize(config)` before use.
+ *
+ * @param providerId - Provider identifier (e.g. `"runway"`, `"replicate"`, `"fal"`).
+ * @returns A new uninitialised {@link IVideoGenerator} instance.
+ * @throws {Error} When no factory is registered for the given provider ID.
+ */
+export function createVideoProvider(providerId) {
+    const factory = videoProviderFactories.get(providerId.toLowerCase());
+    if (!factory) {
+        throw new Error(`Video generation is not supported for provider "${providerId}".`);
+    }
+    return factory();
+}
+/**
+ * Check whether a video provider factory is registered for the given ID.
+ *
+ * @param providerId - Provider identifier to check.
+ * @returns `true` if a factory exists for this provider.
+ */
+export function hasVideoProviderFactory(providerId) {
+    return videoProviderFactories.has(providerId.toLowerCase());
+}
+/**
+ * List all registered video provider factory IDs, sorted alphabetically.
+ *
+ * @returns Sorted array of registered provider identifiers.
+ */
+export function listVideoProviderFactories() {
+    return Array.from(videoProviderFactories.keys()).sort();
+}
+//# sourceMappingURL=index.js.map

package/dist/core/video/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/video/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAC;AACnE,OAAO,EAAE,sBAAsB,EAAE,MAAM,uCAAuC,CAAC;AAC/E,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAC;AAEzE,cAAc,YAAY,CAAC;AAC3B,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,yBAAyB,CAAC;AACxC,cAAc,oBAAoB,CAAC;AASnC;;;;;GAKG;AACH,MAAM,sBAAsB,GAAG,IAAI,GAAG,CAA+B;IACnE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,mBAAmB,EAAE,CAAC;IAC3C,CAAC,WAAW,EAAE,GAAG,EAAE,CAAC,IAAI,sBAAsB,EAAE,CAAC;IACjD,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,IAAI,gBAAgB,EAAE,CAAC;CACtC,CAAC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,UAAU,4BAA4B,CAC1C,UAAkB,EAClB,OAA6B;IAE7B,sBAAsB,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,EAAE,OAAO,CAAC,CAAC;AAChE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CAAC,UAAkB;IACpD,MAAM,OAAO,GAAG,sBAAsB,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;IACrE,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,mDAAmD,UAAU,IAAI,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,OAAO,EAAE,CAAC;AACnB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,UAAkB;IACxD,OAAO,sBAAsB,CAAC,GAAG,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B;IACxC,OAAO,KAAK,CAAC,IAAI,CAAC,sBAAsB,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAC1D,CAAC"}

package/dist/core/video/providers/FalVideoProvider.d.ts

@@ -0,0 +1,195 @@
+/**
+ * @module core/video/providers/FalVideoProvider
+ *
+ * Video generation provider for the Fal.ai serverless GPU platform.
+ *
+ * Fal.ai hosts video generation models (Kling, HunyuanVideo, CogVideo, etc.)
+ * behind a queue-based API. This provider implements the three-step pattern
+ * established by {@link FalImageProvider}: submit to queue, poll for status,
+ * then fetch the completed result.
+ *
+ * ## Supported models
+ *
+ * | Model ID                         | Description                       |
+ * |----------------------------------|-----------------------------------|
+ * | `kling-video/v1`                 | Kling v1 — high quality video     |
+ * | `fal-ai/hunyuan-video`           | HunyuanVideo — Tencent's model    |
+ * | `fal-ai/cogvideox-5b`            | CogVideoX-5B — open model        |
+ *
+ * ## API flow (three-step queue)
+ *
+ * 1. **Submit** — `POST ${baseURL}/${model}` with prompt/params.
+ *    Returns `{ request_id }` immediately.
+ * 2. **Poll** — `GET ${baseURL}/${model}/requests/${request_id}/status`
+ *    until `status === 'COMPLETED'` or `'FAILED'`.
+ * 3. **Fetch** — `GET ${baseURL}/${model}/requests/${request_id}`
+ *    returns `{ video: { url } }`.
+ *
+ * ## Authentication
+ *
+ * Requires a `FAL_API_KEY`. Sent as `Authorization: Key ${apiKey}`.
+ *
+ * @see {@link IVideoGenerator} for the provider interface contract.
+ * @see {@link FalImageProvider} for the image counterpart.
+ */
+import type { IVideoGenerator } from '../IVideoGenerator.js';
+import type { VideoGenerateRequest, ImageToVideoRequest, VideoResult } from '../types.js';
+/**
+ * Configuration for the Fal.ai video generation provider.
+ *
+ * @example
+ * ```typescript
+ * const config: FalVideoProviderConfig = {
+ *   apiKey: process.env.FAL_API_KEY!,
+ *   defaultModelId: 'kling-video/v1',
+ * };
+ * ```
+ */
+export interface FalVideoProviderConfig {
+    /**
+     * Fal.ai API key. Sent as `Authorization: Key ${apiKey}`.
+     * Obtain from https://fal.ai/dashboard/keys
+     */
+    apiKey: string;
+    /**
+     * Base URL for the Fal.ai queue API. Override for testing or proxy setups.
+     * @default 'https://queue.fal.run'
+     */
+    baseURL?: string;
+    /**
+     * Default model to use when the request doesn't specify one.
+     * @default 'kling-video/v1'
+     */
+    defaultModelId?: string;
+    /**
+     * Milliseconds between status polls while waiting for generation.
+     * @default 2000
+     */
+    pollIntervalMs?: number;
+    /**
+     * Maximum milliseconds to wait for generation before timing out.
+     * @default 300000
+     */
+    timeoutMs?: number;
+}
+/**
+ * Video generation provider connecting to the Fal.ai serverless platform.
+ *
+ * Implements the three-step queue pattern: submit a generation task,
+ * poll the status endpoint until completion, then fetch the result.
+ * This mirrors the flow used by {@link FalImageProvider}.
+ *
+ * @implements {IVideoGenerator}
+ *
+ * @example
+ * ```typescript
+ * const provider = new FalVideoProvider();
+ * await provider.initialize({ apiKey: process.env.FAL_API_KEY! });
+ *
+ * const result = await provider.generateVideo({
+ *   modelId: 'kling-video/v1',
+ *   prompt: 'A time-lapse of flowers blooming in a meadow',
+ * });
+ * console.log(result.videos[0].url);
+ * ```
+ */
+export declare class FalVideoProvider implements IVideoGenerator {
+    /** @inheritdoc */
+    readonly providerId = "fal";
+    /** @inheritdoc */
+    isInitialized: boolean;
+    /** @inheritdoc */
+    defaultModelId?: string;
+    /** Internal resolved configuration. */
+    private _config;
+    /**
+     * Initialize the provider with API credentials and optional configuration.
+     *
+     * @param config - Configuration object. Must include `apiKey`.
+     * @throws {Error} If `apiKey` is missing or empty.
+     */
+    initialize(config: Record<string, unknown>): Promise<void>;
+    /**
+     * Generate a video from a text prompt using the Fal.ai queue API.
+     *
+     * Submits the task, polls until complete, then fetches the result.
+     *
+     * @param request - Video generation request with prompt and optional params.
+     * @returns The generated video result envelope.
+     *
+     * @throws {Error} If the provider is not initialized.
+     * @throws {Error} If the API returns an error or times out.
+     */
+    generateVideo(request: VideoGenerateRequest): Promise<VideoResult>;
+    /**
+     * Generate a video from a source image using the Fal.ai queue API.
+     *
+     * The source image Buffer is converted to a base64 data URL and passed
+     * as the `image_url` parameter.
+     *
+     * @param request - Generation parameters including the source image buffer.
+     * @returns The generated video result envelope.
+     *
+     * @throws {Error} If the provider is not initialized or the API fails.
+     */
+    imageToVideo(request: ImageToVideoRequest): Promise<VideoResult>;
+    /**
+     * Fal.ai supports both text-to-video and image-to-video generation.
+     *
+     * @param capability - The capability to check.
+     * @returns `true` for both `'text-to-video'` and `'image-to-video'`.
+     */
+    supports(capability: 'text-to-video' | 'image-to-video'): boolean;
+    /**
+     * Release any resources held by the provider. No-op for HTTP-only providers.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Submit a generation task to the Fal.ai queue.
+     *
+     * @param model - Full model path (e.g. 'kling-video/v1').
+     * @param body - Request body with prompt and generation params.
+     * @returns The request_id for status polling.
+     *
+     * @throws {Error} If the submission request fails.
+     * @internal
+     */
+    private _submitTask;
+    /**
+     * Poll the Fal.ai status endpoint until the task completes or times out.
+     *
+     * @param model - Full model path.
+     * @param requestId - The request ID from submission.
+     *
+     * @throws {Error} If the generation fails or times out.
+     * @internal
+     */
+    private _pollStatus;
+    /**
+     * Fetch the completed generation result from the Fal.ai result endpoint.
+     *
+     * Called after polling confirms the task is COMPLETED. The result endpoint
+     * is separate from the status endpoint because Fal.ai returns the full
+     * payload (including video URLs) only here.
+     *
+     * @param model - Full model path.
+     * @param requestId - The request ID from submission.
+     * @returns The generation result with video URL.
+     *
+     * @throws {Error} If the result fetch fails.
+     * @internal
+     */
+    private _fetchResult;
+    /**
+     * Build a {@link VideoResult} from a completed Fal.ai result.
+     *
+     * @param result - The Fal.ai result response.
+     * @param model - Model ID used for the generation.
+     * @returns Normalized video result envelope.
+     *
+     * @throws {Error} If the result has no video URL.
+     * @internal
+     */
+    private _buildResult;
+}
+//# sourceMappingURL=FalVideoProvider.d.ts.map

package/dist/core/video/providers/FalVideoProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FalVideoProvider.d.ts","sourceRoot":"","sources":["../../../../src/core/video/providers/FalVideoProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,KAAK,EACV,oBAAoB,EACpB,mBAAmB,EACnB,WAAW,EACZ,MAAM,aAAa,CAAC;AAMrB;;;;;;;;;;GAUG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA4DD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,gBAAiB,YAAW,eAAe;IACtD,kBAAkB;IAClB,SAAgB,UAAU,SAAS;IAEnC,kBAAkB;IACX,aAAa,UAAS;IAE7B,kBAAkB;IACX,cAAc,CAAC,EAAE,MAAM,CAAC;IAE/B,uCAAuC;IACvC,OAAO,CAAC,OAAO,CAA0H;IAMzI;;;;;OAKG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAkChE;;;;;;;;;;OAUG;IACG,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC;IAuBxE;;;;;;;;;;OAUG;IACG,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,WAAW,CAAC;IA+BtE;;;;;OAKG;IACH,QAAQ,CAAC,UAAU,EAAE,eAAe,GAAG,gBAAgB,GAAG,OAAO;IAIjE;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAQ/B;;;;;;;;;OASG;YACW,WAAW;IAyBzB;;;;;;;;OAQG;YACW,WAAW;IAoCzB;;;;;;;;;;;;;OAaG;YACW,YAAY;IAiB1B;;;;;;;;;OASG;IACH,OAAO,CAAC,YAAY;CAsBrB"}

package/dist/core/video/providers/FalVideoProvider.js

@@ -0,0 +1,322 @@
+/**
+ * @module core/video/providers/FalVideoProvider
+ *
+ * Video generation provider for the Fal.ai serverless GPU platform.
+ *
+ * Fal.ai hosts video generation models (Kling, HunyuanVideo, CogVideo, etc.)
+ * behind a queue-based API. This provider implements the three-step pattern
+ * established by {@link FalImageProvider}: submit to queue, poll for status,
+ * then fetch the completed result.
+ *
+ * ## Supported models
+ *
+ * | Model ID                         | Description                       |
+ * |----------------------------------|-----------------------------------|
+ * | `kling-video/v1`                 | Kling v1 — high quality video     |
+ * | `fal-ai/hunyuan-video`           | HunyuanVideo — Tencent's model    |
+ * | `fal-ai/cogvideox-5b`            | CogVideoX-5B — open model        |
+ *
+ * ## API flow (three-step queue)
+ *
+ * 1. **Submit** — `POST ${baseURL}/${model}` with prompt/params.
+ *    Returns `{ request_id }` immediately.
+ * 2. **Poll** — `GET ${baseURL}/${model}/requests/${request_id}/status`
+ *    until `status === 'COMPLETED'` or `'FAILED'`.
+ * 3. **Fetch** — `GET ${baseURL}/${model}/requests/${request_id}`
+ *    returns `{ video: { url } }`.
+ *
+ * ## Authentication
+ *
+ * Requires a `FAL_API_KEY`. Sent as `Authorization: Key ${apiKey}`.
+ *
+ * @see {@link IVideoGenerator} for the provider interface contract.
+ * @see {@link FalImageProvider} for the image counterpart.
+ */
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Sleep for the specified number of milliseconds.
+ * Used between poll requests to avoid rate-limiting.
+ * @param ms - Duration in milliseconds.
+ * @internal
+ */
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+// ---------------------------------------------------------------------------
+// Implementation
+// ---------------------------------------------------------------------------
+/**
+ * Video generation provider connecting to the Fal.ai serverless platform.
+ *
+ * Implements the three-step queue pattern: submit a generation task,
+ * poll the status endpoint until completion, then fetch the result.
+ * This mirrors the flow used by {@link FalImageProvider}.
+ *
+ * @implements {IVideoGenerator}
+ *
+ * @example
+ * ```typescript
+ * const provider = new FalVideoProvider();
+ * await provider.initialize({ apiKey: process.env.FAL_API_KEY! });
+ *
+ * const result = await provider.generateVideo({
+ *   modelId: 'kling-video/v1',
+ *   prompt: 'A time-lapse of flowers blooming in a meadow',
+ * });
+ * console.log(result.videos[0].url);
+ * ```
+ */
+export class FalVideoProvider {
+    constructor() {
+        /** @inheritdoc */
+        this.providerId = 'fal';
+        /** @inheritdoc */
+        this.isInitialized = false;
+    }
+    // -------------------------------------------------------------------------
+    // Lifecycle
+    // -------------------------------------------------------------------------
+    /**
+     * Initialize the provider with API credentials and optional configuration.
+     *
+     * @param config - Configuration object. Must include `apiKey`.
+     * @throws {Error} If `apiKey` is missing or empty.
+     */
+    async initialize(config) {
+        const apiKey = typeof config.apiKey === 'string' ? config.apiKey.trim() : '';
+        if (!apiKey) {
+            throw new Error('Fal.ai video provider requires apiKey (FAL_API_KEY).');
+        }
+        this._config = {
+            apiKey,
+            baseURL: typeof config.baseURL === 'string' && config.baseURL.trim()
+                ? config.baseURL.trim()
+                : 'https://queue.fal.run',
+            defaultModelId: typeof config.defaultModelId === 'string' && config.defaultModelId.trim()
+                ? config.defaultModelId.trim()
+                : 'kling-video/v1',
+            pollIntervalMs: typeof config.pollIntervalMs === 'number' && config.pollIntervalMs > 0
+                ? config.pollIntervalMs
+                : 2000,
+            timeoutMs: typeof config.timeoutMs === 'number' && config.timeoutMs > 0
+                ? config.timeoutMs
+                : 300000,
+        };
+        this.defaultModelId = this._config.defaultModelId;
+        this.isInitialized = true;
+    }
+    // -------------------------------------------------------------------------
+    // Generation
+    // -------------------------------------------------------------------------
+    /**
+     * Generate a video from a text prompt using the Fal.ai queue API.
+     *
+     * Submits the task, polls until complete, then fetches the result.
+     *
+     * @param request - Video generation request with prompt and optional params.
+     * @returns The generated video result envelope.
+     *
+     * @throws {Error} If the provider is not initialized.
+     * @throws {Error} If the API returns an error or times out.
+     */
+    async generateVideo(request) {
+        if (!this.isInitialized) {
+            throw new Error('Fal.ai video provider is not initialized. Call initialize() first.');
+        }
+        const model = request.modelId || this.defaultModelId || 'kling-video/v1';
+        const body = {
+            prompt: request.prompt,
+        };
+        if (request.durationSec !== undefined)
+            body.duration = request.durationSec;
+        if (request.aspectRatio)
+            body.aspect_ratio = request.aspectRatio;
+        if (request.seed !== undefined)
+            body.seed = request.seed;
+        // Three-step flow: submit → poll → fetch
+        const requestId = await this._submitTask(model, body);
+        await this._pollStatus(model, requestId);
+        const result = await this._fetchResult(model, requestId);
+        return this._buildResult(result, model);
+    }
+    /**
+     * Generate a video from a source image using the Fal.ai queue API.
+     *
+     * The source image Buffer is converted to a base64 data URL and passed
+     * as the `image_url` parameter.
+     *
+     * @param request - Generation parameters including the source image buffer.
+     * @returns The generated video result envelope.
+     *
+     * @throws {Error} If the provider is not initialized or the API fails.
+     */
+    async imageToVideo(request) {
+        if (!this.isInitialized) {
+            throw new Error('Fal.ai video provider is not initialized. Call initialize() first.');
+        }
+        const model = request.modelId || this.defaultModelId || 'kling-video/v1';
+        // Convert the image buffer to a base64 data URL for the Fal.ai API.
+        const imageBase64 = `data:image/png;base64,${request.image.toString('base64')}`;
+        const body = {
+            prompt: request.prompt,
+            image_url: imageBase64,
+        };
+        if (request.durationSec !== undefined)
+            body.duration = request.durationSec;
+        if (request.aspectRatio)
+            body.aspect_ratio = request.aspectRatio;
+        if (request.seed !== undefined)
+            body.seed = request.seed;
+        // Three-step flow: submit → poll → fetch
+        const requestId = await this._submitTask(model, body);
+        await this._pollStatus(model, requestId);
+        const result = await this._fetchResult(model, requestId);
+        return this._buildResult(result, model);
+    }
+    // -------------------------------------------------------------------------
+    // Capability query
+    // -------------------------------------------------------------------------
+    /**
+     * Fal.ai supports both text-to-video and image-to-video generation.
+     *
+     * @param capability - The capability to check.
+     * @returns `true` for both `'text-to-video'` and `'image-to-video'`.
+     */
+    supports(capability) {
+        return capability === 'text-to-video' || capability === 'image-to-video';
+    }
+    /**
+     * Release any resources held by the provider. No-op for HTTP-only providers.
+     */
+    async shutdown() {
+        this.isInitialized = false;
+    }
+    // -------------------------------------------------------------------------
+    // Private helpers
+    // -------------------------------------------------------------------------
+    /**
+     * Submit a generation task to the Fal.ai queue.
+     *
+     * @param model - Full model path (e.g. 'kling-video/v1').
+     * @param body - Request body with prompt and generation params.
+     * @returns The request_id for status polling.
+     *
+     * @throws {Error} If the submission request fails.
+     * @internal
+     */
+    async _submitTask(model, body) {
+        const url = `${this._config.baseURL}/${model}`;
+        const response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Key ${this._config.apiKey}`,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Fal.ai video generation submission failed (${response.status}): ${errorText}`);
+        }
+        const data = (await response.json());
+        if (!data.request_id) {
+            throw new Error('Fal.ai submission response missing request_id.');
+        }
+        return data.request_id;
+    }
+    /**
+     * Poll the Fal.ai status endpoint until the task completes or times out.
+     *
+     * @param model - Full model path.
+     * @param requestId - The request ID from submission.
+     *
+     * @throws {Error} If the generation fails or times out.
+     * @internal
+     */
+    async _pollStatus(model, requestId) {
+        const startedAt = Date.now();
+        while (Date.now() - startedAt < this._config.timeoutMs) {
+            const url = `${this._config.baseURL}/${model}/requests/${requestId}/status`;
+            const response = await fetch(url, {
+                headers: {
+                    Authorization: `Key ${this._config.apiKey}`,
+                },
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`Fal.ai status polling failed (${response.status}): ${errorText}`);
+            }
+            const data = (await response.json());
+            if (data.status === 'COMPLETED') {
+                return;
+            }
+            if (data.status === 'FAILED') {
+                throw new Error(`Fal.ai video generation failed for request ${requestId}.`);
+            }
+            // 'IN_QUEUE' or 'IN_PROGRESS' — wait before next poll
+            await sleep(this._config.pollIntervalMs);
+        }
+        throw new Error(`Fal.ai video generation timed out after ${this._config.timeoutMs}ms for request ${requestId}.`);
+    }
+    /**
+     * Fetch the completed generation result from the Fal.ai result endpoint.
+     *
+     * Called after polling confirms the task is COMPLETED. The result endpoint
+     * is separate from the status endpoint because Fal.ai returns the full
+     * payload (including video URLs) only here.
+     *
+     * @param model - Full model path.
+     * @param requestId - The request ID from submission.
+     * @returns The generation result with video URL.
+     *
+     * @throws {Error} If the result fetch fails.
+     * @internal
+     */
+    async _fetchResult(model, requestId) {
+        const url = `${this._config.baseURL}/${model}/requests/${requestId}`;
+        const response = await fetch(url, {
+            headers: {
+                Authorization: `Key ${this._config.apiKey}`,
+            },
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Fal.ai result fetch failed (${response.status}): ${errorText}`);
+        }
+        return (await response.json());
+    }
+    /**
+     * Build a {@link VideoResult} from a completed Fal.ai result.
+     *
+     * @param result - The Fal.ai result response.
+     * @param model - Model ID used for the generation.
+     * @returns Normalized video result envelope.
+     *
+     * @throws {Error} If the result has no video URL.
+     * @internal
+     */
+    _buildResult(result, model) {
+        if (!result.video?.url) {
+            throw new Error('Fal.ai generation completed but returned no video output.');
+        }
+        return {
+            created: Math.floor(Date.now() / 1000),
+            modelId: model,
+            providerId: this.providerId,
+            videos: [{
+                    url: result.video.url,
+                    mimeType: result.video.content_type ?? 'video/mp4',
+                    durationSec: result.video.duration,
+                    providerMetadata: {
+                        seed: result.seed,
+                    },
+                }],
+            usage: {
+                totalVideos: 1,
+            },
+        };
+    }
+}
+//# sourceMappingURL=FalVideoProvider.js.map

package/dist/core/video/providers/FalVideoProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FalVideoProvider.js","sourceRoot":"","sources":["../../../../src/core/video/providers/FalVideoProvider.ts"],"names":[],"mappings":"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"}