@tanstack/ai-fal 0.0.1 → 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tanner Linsley
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/esm/adapters/image.d.ts

@@ -0,0 +1,36 @@
+import { BaseImageAdapter } from '@tanstack/ai/adapters';
+import { FalClientConfig } from '../utils.js';
+import { ImageGenerationOptions, ImageGenerationResult } from '@tanstack/ai';
+import { FalImageProviderOptions, FalModel, FalModelImageSize } from '../model-meta.js';
+/**
+ * fal.ai image generation adapter with full type inference.
+ *
+ * Uses fal.ai's comprehensive type system to provide autocomplete
+ *
+ * and type safety for all 600+ supported models.
+ *
+ * @example
+ * ```typescript
+ * const adapter = falImage('fal-ai/flux/dev')
+ * const result = await adapter.generateImages({
+ *   model: 'fal-ai/flux/dev',
+ *   prompt: 'a cat',
+ *   modelOptions: {
+ *     num_inference_steps: 28, // Type-safe! Autocomplete works
+ *     guidance_scale: 3.5,
+ *   },
+ * })
+ * ```
+ */
+export declare class FalImageAdapter<TModel extends FalModel> extends BaseImageAdapter<TModel, FalImageProviderOptions<TModel>, Record<TModel, FalImageProviderOptions<TModel>>, Record<TModel, FalModelImageSize<TModel>>> {
+    readonly kind: "image";
+    readonly name: "fal";
+    constructor(model: TModel, config?: FalClientConfig);
+    generateImages(options: ImageGenerationOptions<FalImageProviderOptions<TModel>, FalModelImageSize<TModel>>): Promise<ImageGenerationResult>;
+    private buildInput;
+    protected generateId(): string;
+    private transformResponse;
+    private parseImage;
+}
+export declare function createFalImage<TModel extends FalModel>(model: TModel, config?: FalClientConfig): FalImageAdapter<TModel>;
+export declare function falImage<TModel extends FalModel>(model: TModel, config?: FalClientConfig): FalImageAdapter<TModel>;

package/dist/esm/adapters/image.js

@@ -0,0 +1,71 @@
+import { fal } from "@fal-ai/client";
+import { BaseImageAdapter } from "@tanstack/ai/adapters";
+import { configureFalClient, generateId } from "../utils/client.js";
+import { mapSizeToFalFormat } from "../image/image-provider-options.js";
+class FalImageAdapter extends BaseImageAdapter {
+  constructor(model, config) {
+    super({}, model);
+    this.kind = "image";
+    this.name = "fal";
+    configureFalClient(config);
+  }
+  async generateImages(options) {
+    const input = this.buildInput(options);
+    const result = await fal.subscribe(this.model, { input });
+    return this.transformResponse(result);
+  }
+  buildInput(options) {
+    const sizeParams = mapSizeToFalFormat(options.size);
+    const input = {
+      ...options.modelOptions,
+      ...sizeParams,
+      prompt: options.prompt,
+      num_images: options.numberOfImages
+    };
+    return input;
+  }
+  generateId() {
+    return generateId(this.name);
+  }
+  transformResponse(response) {
+    const images = [];
+    const data = response.data;
+    if ("images" in data && Array.isArray(data.images)) {
+      for (const img of data.images) {
+        images.push(this.parseImage(img));
+      }
+    } else if ("image" in data && data.image && typeof data.image === "object") {
+      images.push(this.parseImage(data.image));
+    }
+    return {
+      id: response.requestId || this.generateId(),
+      model: this.model,
+      images
+    };
+  }
+  parseImage(img) {
+    const url = img.url;
+    if (url.startsWith("data:")) {
+      const base64Match = url.match(/^data:image\/[^;]+;base64,(.+)$/);
+      if (base64Match) {
+        return {
+          b64Json: base64Match[1],
+          url
+        };
+      }
+    }
+    return { url };
+  }
+}
+function createFalImage(model, config) {
+  return new FalImageAdapter(model, config);
+}
+function falImage(model, config) {
+  return createFalImage(model, config);
+}
+export {
+  FalImageAdapter,
+  createFalImage,
+  falImage
+};
+//# sourceMappingURL=image.js.map

package/dist/esm/adapters/image.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image.js","sources":["../../../src/adapters/image.ts"],"sourcesContent":["import { fal } from '@fal-ai/client'\nimport { BaseImageAdapter } from '@tanstack/ai/adapters'\nimport { configureFalClient, generateId as utilGenerateId } from '../utils'\nimport { mapSizeToFalFormat } from '../image/image-provider-options'\nimport type { OutputType, Result } from '@fal-ai/client'\nimport type { FalClientConfig } from '../utils'\nimport type {\n  GeneratedImage,\n  ImageGenerationOptions,\n  ImageGenerationResult,\n} from '@tanstack/ai'\nimport type {\n  FalImageProviderOptions,\n  FalModel,\n  FalModelImageSize,\n  FalModelInput,\n} from '../model-meta'\n\n/**\n * fal.ai image generation adapter with full type inference.\n *\n * Uses fal.ai's comprehensive type system to provide autocomplete\n *\n * and type safety for all 600+ supported models.\n *\n * @example\n * ```typescript\n * const adapter = falImage('fal-ai/flux/dev')\n * const result = await adapter.generateImages({\n *   model: 'fal-ai/flux/dev',\n *   prompt: 'a cat',\n *   modelOptions: {\n *     num_inference_steps: 28, // Type-safe! Autocomplete works\n *     guidance_scale: 3.5,\n *   },\n * })\n * ```\n */\nexport class FalImageAdapter<TModel extends FalModel> extends BaseImageAdapter<\n  TModel,\n  FalImageProviderOptions<TModel>,\n  Record<TModel, FalImageProviderOptions<TModel>>,\n  Record<TModel, FalModelImageSize<TModel>>\n> {\n  readonly kind = 'image' as const\n  readonly name = 'fal' as const\n\n  constructor(model: TModel, config?: FalClientConfig) {\n    super({}, model)\n    configureFalClient(config)\n  }\n\n  async generateImages(\n    options: ImageGenerationOptions<\n      FalImageProviderOptions<TModel>,\n      FalModelImageSize<TModel>\n    >,\n  ): Promise<ImageGenerationResult> {\n    const input = this.buildInput(options)\n    const result = await fal.subscribe(this.model, { input })\n    return this.transformResponse(result)\n  }\n\n  private buildInput(\n    options: ImageGenerationOptions<FalImageProviderOptions<TModel>, string>,\n  ): FalModelInput<TModel> {\n    const sizeParams = mapSizeToFalFormat(options.size)\n    const input = {\n      ...options.modelOptions,\n      ...sizeParams,\n      prompt: options.prompt,\n      num_images: options.numberOfImages,\n    } as FalModelInput<TModel>\n    return input\n  }\n\n  protected override generateId(): string {\n    return utilGenerateId(this.name)\n  }\n\n  private transformResponse(\n    response: Result<OutputType<TModel>>,\n  ): ImageGenerationResult {\n    const images: Array<GeneratedImage> = []\n    const data = response.data\n\n    // Handle array of images (most models return { images: [...] })\n    if ('images' in data && Array.isArray(data.images)) {\n      for (const img of data.images) {\n        images.push(this.parseImage(img))\n      }\n    }\n    // Handle single image response (some models return { image: {...} })\n    else if ('image' in data && data.image && typeof data.image === 'object') {\n      images.push(this.parseImage(data.image))\n    }\n\n    return {\n      id: response.requestId || this.generateId(),\n      model: this.model,\n      images,\n    }\n  }\n\n  private parseImage(img: { url: string }): GeneratedImage {\n    const url = img.url\n    // Check if it's a base64 data URL\n    if (url.startsWith('data:')) {\n      const base64Match = url.match(/^data:image\\/[^;]+;base64,(.+)$/)\n      if (base64Match) {\n        return {\n          b64Json: base64Match[1],\n          url,\n        }\n      }\n    }\n    return { url }\n  }\n}\n\nexport function createFalImage<TModel extends FalModel>(\n  model: TModel,\n  config?: FalClientConfig,\n): FalImageAdapter<TModel> {\n  return new FalImageAdapter(model, config)\n}\n\nexport function falImage<TModel extends FalModel>(\n  model: TModel,\n  config?: FalClientConfig,\n): FalImageAdapter<TModel> {\n  return createFalImage(model, config)\n}\n"],"names":["utilGenerateId"],"mappings":";;;;AAsCO,MAAM,wBAAiD,iBAK5D;AAAA,EAIA,YAAY,OAAe,QAA0B;AACnD,UAAM,CAAA,GAAI,KAAK;AAJjB,SAAS,OAAO;AAChB,SAAS,OAAO;AAId,uBAAmB,MAAM;AAAA,EAC3B;AAAA,EAEA,MAAM,eACJ,SAIgC;AAChC,UAAM,QAAQ,KAAK,WAAW,OAAO;AACrC,UAAM,SAAS,MAAM,IAAI,UAAU,KAAK,OAAO,EAAE,OAAO;AACxD,WAAO,KAAK,kBAAkB,MAAM;AAAA,EACtC;AAAA,EAEQ,WACN,SACuB;AACvB,UAAM,aAAa,mBAAmB,QAAQ,IAAI;AAClD,UAAM,QAAQ;AAAA,MACZ,GAAG,QAAQ;AAAA,MACX,GAAG;AAAA,MACH,QAAQ,QAAQ;AAAA,MAChB,YAAY,QAAQ;AAAA,IAAA;AAEtB,WAAO;AAAA,EACT;AAAA,EAEmB,aAAqB;AACtC,WAAOA,WAAe,KAAK,IAAI;AAAA,EACjC;AAAA,EAEQ,kBACN,UACuB;AACvB,UAAM,SAAgC,CAAA;AACtC,UAAM,OAAO,SAAS;AAGtB,QAAI,YAAY,QAAQ,MAAM,QAAQ,KAAK,MAAM,GAAG;AAClD,iBAAW,OAAO,KAAK,QAAQ;AAC7B,eAAO,KAAK,KAAK,WAAW,GAAG,CAAC;AAAA,MAClC;AAAA,IACF,WAES,WAAW,QAAQ,KAAK,SAAS,OAAO,KAAK,UAAU,UAAU;AACxE,aAAO,KAAK,KAAK,WAAW,KAAK,KAAK,CAAC;AAAA,IACzC;AAEA,WAAO;AAAA,MACL,IAAI,SAAS,aAAa,KAAK,WAAA;AAAA,MAC/B,OAAO,KAAK;AAAA,MACZ;AAAA,IAAA;AAAA,EAEJ;AAAA,EAEQ,WAAW,KAAsC;AACvD,UAAM,MAAM,IAAI;AAEhB,QAAI,IAAI,WAAW,OAAO,GAAG;AAC3B,YAAM,cAAc,IAAI,MAAM,iCAAiC;AAC/D,UAAI,aAAa;AACf,eAAO;AAAA,UACL,SAAS,YAAY,CAAC;AAAA,UACtB;AAAA,QAAA;AAAA,MAEJ;AAAA,IACF;AACA,WAAO,EAAE,IAAA;AAAA,EACX;AACF;AAEO,SAAS,eACd,OACA,QACyB;AACzB,SAAO,IAAI,gBAAgB,OAAO,MAAM;AAC1C;AAEO,SAAS,SACd,OACA,QACyB;AACzB,SAAO,eAAe,OAAO,MAAM;AACrC;"}

package/dist/esm/adapters/video.d.ts

@@ -0,0 +1,34 @@
+import { BaseVideoAdapter } from '@tanstack/ai/adapters';
+import { VideoGenerationOptions, VideoJobResult, VideoStatusResult, VideoUrlResult } from '@tanstack/ai';
+import { FalModel, FalModelVideoSize, FalVideoProviderOptions } from '../model-meta.js';
+import { FalClientConfig } from '../utils.js';
+/**
+ * fal.ai video generation adapter.
+ * Supports MiniMax, Luma, Kling, Hunyuan, and other fal.ai video models.
+ *
+ * Uses fal.ai's comprehensive type system to provide autocomplete
+ * and type safety for all supported video models.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export declare class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<TModel, FalVideoProviderOptions<TModel>, Record<TModel, FalVideoProviderOptions<TModel>>, Record<TModel, FalModelVideoSize<TModel>>> {
+    readonly kind: "video";
+    readonly name: "fal";
+    constructor(model: TModel, config?: FalClientConfig);
+    createVideoJob(options: VideoGenerationOptions<FalVideoProviderOptions<TModel>, FalModelVideoSize<TModel>>): Promise<VideoJobResult>;
+    getVideoStatus(jobId: string): Promise<VideoStatusResult>;
+    getVideoUrl(jobId: string): Promise<VideoUrlResult>;
+    protected generateId(): string;
+}
+/**
+ * Create a fal.ai video adapter with an explicit API key.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export declare function createFalVideo<TModel extends FalModel>(model: TModel, config?: FalClientConfig): FalVideoAdapter<TModel>;
+/**
+ * Create a fal.ai video adapter using config.apiKey or the FAL_KEY environment variable.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export declare function falVideo<TModel extends FalModel>(model: TModel, config?: FalClientConfig): FalVideoAdapter<TModel>;

package/dist/esm/adapters/video.js

@@ -0,0 +1,81 @@
+import { fal } from "@fal-ai/client";
+import { BaseVideoAdapter } from "@tanstack/ai/adapters";
+import { configureFalClient, generateId } from "../utils/client.js";
+import { mapVideoSizeToFalFormat } from "../video/video-provider-options.js";
+function mapFalStatusToVideoStatus(falStatus) {
+  switch (falStatus) {
+    case "IN_QUEUE":
+      return "pending";
+    case "IN_PROGRESS":
+      return "processing";
+    case "COMPLETED":
+      return "completed";
+    default:
+      return "processing";
+  }
+}
+class FalVideoAdapter extends BaseVideoAdapter {
+  constructor(model, config) {
+    super({}, model);
+    this.kind = "video";
+    this.name = "fal";
+    configureFalClient(config);
+  }
+  async createVideoJob(options) {
+    const { prompt, size, duration, modelOptions } = options;
+    const sizeParams = mapVideoSizeToFalFormat(size);
+    const input = {
+      ...modelOptions,
+      ...sizeParams,
+      prompt,
+      ...duration ? { duration } : {}
+    };
+    const { request_id } = await fal.queue.submit(this.model, {
+      input
+    });
+    return {
+      jobId: request_id,
+      model: this.model
+    };
+  }
+  async getVideoStatus(jobId) {
+    const statusResponse = await fal.queue.status(this.model, {
+      requestId: jobId,
+      logs: true
+    });
+    return {
+      jobId,
+      status: mapFalStatusToVideoStatus(statusResponse.status),
+      progress: statusResponse.queue_position != null ? Math.max(0, 100 - statusResponse.queue_position * 10) : void 0
+    };
+  }
+  async getVideoUrl(jobId) {
+    const result = await fal.queue.result(this.model, {
+      requestId: jobId
+    });
+    const data = result.data;
+    const url = data.video?.url || data.video_url;
+    if (!url) {
+      throw new Error("Video URL not found in response");
+    }
+    return {
+      jobId,
+      url
+    };
+  }
+  generateId() {
+    return generateId(this.name);
+  }
+}
+function createFalVideo(model, config) {
+  return new FalVideoAdapter(model, config);
+}
+function falVideo(model, config) {
+  return createFalVideo(model, config);
+}
+export {
+  FalVideoAdapter,
+  createFalVideo,
+  falVideo
+};
+//# sourceMappingURL=video.js.map

package/dist/esm/adapters/video.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"video.js","sources":["../../../src/adapters/video.ts"],"sourcesContent":["import { fal } from '@fal-ai/client'\nimport { BaseVideoAdapter } from '@tanstack/ai/adapters'\nimport { configureFalClient, generateId as utilGenerateId } from '../utils'\nimport { mapVideoSizeToFalFormat } from '../video/video-provider-options'\nimport type {\n  VideoGenerationOptions,\n  VideoJobResult,\n  VideoStatusResult,\n  VideoUrlResult,\n} from '@tanstack/ai'\nimport type {\n  FalModel,\n  FalModelInput,\n  FalModelVideoSize,\n  FalVideoProviderOptions,\n} from '../model-meta'\nimport type { FalClientConfig } from '../utils'\n\ntype FalQueueStatus = 'IN_QUEUE' | 'IN_PROGRESS' | 'COMPLETED'\n\ninterface FalStatusResponse {\n  status: FalQueueStatus\n  queue_position?: number\n  logs?: Array<{ message: string }>\n}\n\ninterface FalVideoResultData {\n  video?: { url: string }\n  video_url?: string\n}\n\n/**\n * Maps fal.ai queue status to TanStack AI video status.\n */\nfunction mapFalStatusToVideoStatus(\n  falStatus: FalQueueStatus,\n): VideoStatusResult['status'] {\n  switch (falStatus) {\n    case 'IN_QUEUE':\n      return 'pending'\n    case 'IN_PROGRESS':\n      return 'processing'\n    case 'COMPLETED':\n      return 'completed'\n    default:\n      return 'processing'\n  }\n}\n\n/**\n * fal.ai video generation adapter.\n * Supports MiniMax, Luma, Kling, Hunyuan, and other fal.ai video models.\n *\n * Uses fal.ai's comprehensive type system to provide autocomplete\n * and type safety for all supported video models.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<\n  TModel,\n  FalVideoProviderOptions<TModel>,\n  Record<TModel, FalVideoProviderOptions<TModel>>,\n  Record<TModel, FalModelVideoSize<TModel>>\n> {\n  readonly kind = 'video' as const\n  readonly name = 'fal' as const\n\n  constructor(model: TModel, config?: FalClientConfig) {\n    super({}, model)\n    configureFalClient(config)\n  }\n\n  async createVideoJob(\n    options: VideoGenerationOptions<\n      FalVideoProviderOptions<TModel>,\n      FalModelVideoSize<TModel>\n    >,\n  ): Promise<VideoJobResult> {\n    const { prompt, size, duration, modelOptions } = options\n    const sizeParams = mapVideoSizeToFalFormat(size)\n\n    const input = {\n      ...modelOptions,\n      ...sizeParams,\n      prompt,\n      ...(duration ? { duration } : {}),\n    } as FalModelInput<TModel>\n\n    // Submit to queue and get request ID\n    const { request_id } = await fal.queue.submit(this.model, {\n      input,\n    })\n\n    return {\n      jobId: request_id,\n      model: this.model,\n    }\n  }\n\n  async getVideoStatus(jobId: string): Promise<VideoStatusResult> {\n    const statusResponse = (await fal.queue.status(this.model, {\n      requestId: jobId,\n      logs: true,\n    })) as FalStatusResponse\n\n    return {\n      jobId,\n      status: mapFalStatusToVideoStatus(statusResponse.status),\n      progress:\n        statusResponse.queue_position != null\n          ? Math.max(0, 100 - statusResponse.queue_position * 10)\n          : undefined,\n    }\n  }\n\n  async getVideoUrl(jobId: string): Promise<VideoUrlResult> {\n    const result = await fal.queue.result(this.model, {\n      requestId: jobId,\n    })\n\n    const data = result.data as FalVideoResultData\n\n    // Different models return video URL in different formats\n    const url = data.video?.url || data.video_url\n    if (!url) {\n      throw new Error('Video URL not found in response')\n    }\n\n    return {\n      jobId,\n      url,\n    }\n  }\n\n  protected override generateId(): string {\n    return utilGenerateId(this.name)\n  }\n}\n\n/**\n * Create a fal.ai video adapter with an explicit API key.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport function createFalVideo<TModel extends FalModel>(\n  model: TModel,\n  config?: FalClientConfig,\n): FalVideoAdapter<TModel> {\n  return new FalVideoAdapter(model, config)\n}\n\n/**\n * Create a fal.ai video adapter using config.apiKey or the FAL_KEY environment variable.\n *\n * @experimental Video generation is an experimental feature and may change.\n */\nexport function falVideo<TModel extends FalModel>(\n  model: TModel,\n  config?: FalClientConfig,\n): FalVideoAdapter<TModel> {\n  return createFalVideo(model, config)\n}\n"],"names":["utilGenerateId"],"mappings":";;;;AAkCA,SAAS,0BACP,WAC6B;AAC7B,UAAQ,WAAA;AAAA,IACN,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT,KAAK;AACH,aAAO;AAAA,IACT;AACE,aAAO;AAAA,EAAA;AAEb;AAWO,MAAM,wBAAiD,iBAK5D;AAAA,EAIA,YAAY,OAAe,QAA0B;AACnD,UAAM,CAAA,GAAI,KAAK;AAJjB,SAAS,OAAO;AAChB,SAAS,OAAO;AAId,uBAAmB,MAAM;AAAA,EAC3B;AAAA,EAEA,MAAM,eACJ,SAIyB;AACzB,UAAM,EAAE,QAAQ,MAAM,UAAU,iBAAiB;AACjD,UAAM,aAAa,wBAAwB,IAAI;AAE/C,UAAM,QAAQ;AAAA,MACZ,GAAG;AAAA,MACH,GAAG;AAAA,MACH;AAAA,MACA,GAAI,WAAW,EAAE,aAAa,CAAA;AAAA,IAAC;AAIjC,UAAM,EAAE,eAAe,MAAM,IAAI,MAAM,OAAO,KAAK,OAAO;AAAA,MACxD;AAAA,IAAA,CACD;AAED,WAAO;AAAA,MACL,OAAO;AAAA,MACP,OAAO,KAAK;AAAA,IAAA;AAAA,EAEhB;AAAA,EAEA,MAAM,eAAe,OAA2C;AAC9D,UAAM,iBAAkB,MAAM,IAAI,MAAM,OAAO,KAAK,OAAO;AAAA,MACzD,WAAW;AAAA,MACX,MAAM;AAAA,IAAA,CACP;AAED,WAAO;AAAA,MACL;AAAA,MACA,QAAQ,0BAA0B,eAAe,MAAM;AAAA,MACvD,UACE,eAAe,kBAAkB,OAC7B,KAAK,IAAI,GAAG,MAAM,eAAe,iBAAiB,EAAE,IACpD;AAAA,IAAA;AAAA,EAEV;AAAA,EAEA,MAAM,YAAY,OAAwC;AACxD,UAAM,SAAS,MAAM,IAAI,MAAM,OAAO,KAAK,OAAO;AAAA,MAChD,WAAW;AAAA,IAAA,CACZ;AAED,UAAM,OAAO,OAAO;AAGpB,UAAM,MAAM,KAAK,OAAO,OAAO,KAAK;AACpC,QAAI,CAAC,KAAK;AACR,YAAM,IAAI,MAAM,iCAAiC;AAAA,IACnD;AAEA,WAAO;AAAA,MACL;AAAA,MACA;AAAA,IAAA;AAAA,EAEJ;AAAA,EAEmB,aAAqB;AACtC,WAAOA,WAAe,KAAK,IAAI;AAAA,EACjC;AACF;AAOO,SAAS,eACd,OACA,QACyB;AACzB,SAAO,IAAI,gBAAgB,OAAO,MAAM;AAC1C;AAOO,SAAS,SACd,OACA,QACyB;AACzB,SAAO,eAAe,OAAO,MAAM;AACrC;"}

package/dist/esm/image/image-provider-options.d.ts

@@ -0,0 +1,2 @@
+import { FalModelImageSize, FalModelImageSizeInput } from '../model-meta.js';
+export declare function mapSizeToFalFormat<TModel extends string>(size: FalModelImageSize<TModel> | undefined): FalModelImageSizeInput<TModel> | undefined;

package/dist/esm/image/image-provider-options.js

@@ -0,0 +1,15 @@
+function mapSizeToFalFormat(size) {
+  if (!size) return void 0;
+  const match = size.match(/^(\d+:\d+)(?:_(.+))?$/);
+  return {
+    image_size: size,
+    aspect_ratio: match?.[1],
+    ...match?.[2] && {
+      resolution: match?.[2]
+    }
+  };
+}
+export {
+  mapSizeToFalFormat
+};
+//# sourceMappingURL=image-provider-options.js.map

package/dist/esm/image/image-provider-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"image-provider-options.js","sources":["../../../src/image/image-provider-options.ts"],"sourcesContent":["import type { FalModelImageSize, FalModelImageSizeInput } from '../model-meta'\n\nexport function mapSizeToFalFormat<TModel extends string>(\n  size: FalModelImageSize<TModel> | undefined,\n): FalModelImageSizeInput<TModel> | undefined {\n  if (!size) return undefined\n\n  // \"16:9_4K\" → { aspect_ratio, resolution }\n  // \"16:9\"    → { aspect_ratio }\n  // no match  → { image_size }\n  const match = size.match(/^(\\d+:\\d+)(?:_(.+))?$/)\n\n  return {\n    image_size: size,\n    aspect_ratio: match?.[1],\n    ...(match?.[2] && {\n      resolution: match?.[2],\n    }),\n  }\n}\n"],"names":[],"mappings":"AAEO,SAAS,mBACd,MAC4C;AAC5C,MAAI,CAAC,KAAM,QAAO;AAKlB,QAAM,QAAQ,KAAK,MAAM,uBAAuB;AAEhD,SAAO;AAAA,IACL,YAAY;AAAA,IACZ,cAAc,QAAQ,CAAC;AAAA,IACvB,GAAI,QAAQ,CAAC,KAAK;AAAA,MAChB,YAAY,QAAQ,CAAC;AAAA,IAAA;AAAA,EACvB;AAEJ;"}

package/dist/esm/index.d.ts

@@ -0,0 +1,4 @@
+export { FalImageAdapter, falImage } from './adapters/image.js';
+export { FalVideoAdapter, falVideo } from './adapters/video.js';
+export { type FalImageProviderOptions, type FalVideoProviderOptions, type FalModel, type FalModelInput, type FalModelOutput, type FalModelImageSize, type FalModelVideoSize, } from './model-meta.js';
+export { getFalApiKeyFromEnv, configureFalClient, generateId, type FalClientConfig, } from './utils.js';

package/dist/esm/index.js

@@ -0,0 +1,13 @@
+import { FalImageAdapter, falImage } from "./adapters/image.js";
+import { FalVideoAdapter, falVideo } from "./adapters/video.js";
+import { configureFalClient, generateId, getFalApiKeyFromEnv } from "./utils/client.js";
+export {
+  FalImageAdapter,
+  FalVideoAdapter,
+  configureFalClient,
+  falImage,
+  falVideo,
+  generateId,
+  getFalApiKeyFromEnv
+};
+//# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";;;"}

package/dist/esm/model-meta.d.ts

@@ -0,0 +1,76 @@
+import { EndpointTypeMap } from '@fal-ai/client/endpoints';
+export type { EndpointTypeMap } from '@fal-ai/client/endpoints';
+/**
+ * All known fal.ai model IDs with autocomplete support.
+ * Also accepts any string for custom/new models.
+ */
+export type FalModel = keyof EndpointTypeMap | (string & {});
+/**
+ * Utility type to extract the input type for a specific fal model.
+ *
+ * @example
+ * type FluxInput = FalModelInput<'fal-ai/flux/dev'>
+ * // { prompt: string; num_inference_steps?: number; ... }
+ */
+export type FalModelInput<TModel extends string> = TModel extends keyof EndpointTypeMap ? EndpointTypeMap[TModel]['input'] : Record<string, any>;
+/**
+ * Utility type to extract the output type for a specific fal model.
+ *
+ * @example
+ * type FluxOutput = FalModelOutput<'fal-ai/flux/dev'>
+ * // { images: Array<Image>; seed: number; ... }
+ */
+export type FalModelOutput<TModel extends string> = TModel extends keyof EndpointTypeMap ? EndpointTypeMap[TModel]['output'] : unknown;
+/**
+ * Extract the image_size type supported by a specific fal model.
+ * Returns never if the model doesn't support image_size.
+ *
+ * @example
+ * type FluxSize = FalModelImageSize<'fal-ai/flux/dev'>
+ * // "square_hd" | "square" | "portrait_4_3" | "portrait_16_9" | ...
+ */
+export type FalModelImageSize<TModel extends string> = TModel extends keyof EndpointTypeMap ? 'image_size' extends keyof EndpointTypeMap[TModel]['input'] ? NonNullable<Exclude<FalModelInput<TModel>['image_size'], object>> : 'aspect_ratio' extends keyof EndpointTypeMap[TModel]['input'] ? 'resolution' extends keyof EndpointTypeMap[TModel]['input'] ? `${NonNullable<FalModelInput<TModel>['aspect_ratio']>}_${NonNullable<FalModelInput<TModel>['resolution']>}` : NonNullable<FalModelInput<TModel>['aspect_ratio']> : never : string;
+export type FalModelImageSizeInput<TModel extends string> = TModel extends keyof EndpointTypeMap ? 'aspect_ratio' extends keyof EndpointTypeMap[TModel]['input'] ? 'resolution' extends keyof EndpointTypeMap[TModel]['input'] ? {
+    aspect_ratio: FalModelInput<TModel>['aspect_ratio'];
+    resolution: FalModelInput<TModel>['resolution'];
+} : {
+    aspect_ratio: NonNullable<FalModelInput<TModel>['aspect_ratio']>;
+} : {
+    image_size: FalModelImageSize<TModel>;
+} : {
+    image_size: string;
+};
+/**
+ * Provider options for image generation, excluding fields TanStack AI handles.
+ * Use this for the `modelOptions` parameter in image generation.
+ *
+ * @example
+ * type FluxOptions = FalImageProviderOptions<'fal-ai/flux/dev'>
+ * // { num_inference_steps?: number; guidance_scale?: number; seed?: number; ... }
+ */
+export type FalImageProviderOptions<TModel extends string> = Omit<FalModelInput<TModel>, 'prompt'>;
+/**
+ * Extract the video size type supported by a specific fal model.
+ * Video models typically use aspect_ratio and/or resolution fields.
+ *
+ * Follows the same pattern as FalModelImageSize:
+ * - aspect_ratio + resolution → "16:9_720p"
+ * - aspect_ratio only → "16:9"
+ * - unknown models → string
+ */
+export type FalModelVideoSize<TModel extends string> = TModel extends keyof EndpointTypeMap ? 'aspect_ratio' extends keyof EndpointTypeMap[TModel]['input'] ? 'resolution' extends keyof EndpointTypeMap[TModel]['input'] ? `${NonNullable<FalModelInput<TModel>['aspect_ratio']>}_${NonNullable<FalModelInput<TModel>['resolution']>}` : NonNullable<FalModelInput<TModel>['aspect_ratio']> : never : string;
+export type FalModelVideoSizeInput<TModel extends string> = TModel extends keyof EndpointTypeMap ? 'aspect_ratio' extends keyof EndpointTypeMap[TModel]['input'] ? 'resolution' extends keyof EndpointTypeMap[TModel]['input'] ? {
+    aspect_ratio: FalModelInput<TModel>['aspect_ratio'];
+    resolution: FalModelInput<TModel>['resolution'];
+} : {
+    aspect_ratio: NonNullable<FalModelInput<TModel>['aspect_ratio']>;
+} : {
+    aspect_ratio: string;
+} : {
+    aspect_ratio: string;
+};
+/**
+ * Provider options for video generation, excluding fields TanStack AI handles.
+ * Use this for the `modelOptions` parameter in video generation.
+ */
+export type FalVideoProviderOptions<TModel extends string> = TModel extends keyof EndpointTypeMap ? Omit<FalModelInput<TModel>, 'prompt'> : Record<string, any>;

package/dist/esm/utils/client.d.ts

@@ -0,0 +1,7 @@
+export interface FalClientConfig {
+    apiKey: string;
+    proxyUrl?: string;
+}
+export declare function getFalApiKeyFromEnv(): string;
+export declare function configureFalClient(config?: FalClientConfig): void;
+export declare function generateId(prefix: string): string;

package/dist/esm/utils/client.js

@@ -0,0 +1,47 @@
+import { fal } from "@fal-ai/client";
+function getEnvironment() {
+  if (typeof globalThis !== "undefined") {
+    const win = globalThis.window;
+    if (win?.env) {
+      return win.env;
+    }
+  }
+  if (typeof process !== "undefined") {
+    return process.env;
+  }
+  return void 0;
+}
+function getFalApiKeyFromEnv() {
+  const env = getEnvironment();
+  const key = env?.FAL_KEY;
+  if (!key) {
+    throw new Error(
+      "FAL_KEY is required. Please set it in your environment variables or use the factory function with an explicit API key."
+    );
+  }
+  return key;
+}
+function configureFalClient(config) {
+  if (config?.proxyUrl) {
+    fal.config({
+      proxyUrl: config.proxyUrl
+    });
+  } else {
+    const apiKey = config?.apiKey ?? getFalApiKeyFromEnv();
+    if (!apiKey) {
+      throw new Error("API key is required");
+    }
+    fal.config({
+      credentials: apiKey
+    });
+  }
+}
+function generateId(prefix) {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`;
+}
+export {
+  configureFalClient,
+  generateId,
+  getFalApiKeyFromEnv
+};
+//# sourceMappingURL=client.js.map

package/dist/esm/utils/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sources":["../../../src/utils/client.ts"],"sourcesContent":["import { fal } from '@fal-ai/client'\n\nexport interface FalClientConfig {\n  apiKey: string\n  proxyUrl?: string\n}\n\ninterface EnvObject {\n  FAL_KEY?: string\n}\n\ninterface WindowWithEnv {\n  env?: EnvObject\n}\n\nfunction getEnvironment(): EnvObject | undefined {\n  if (typeof globalThis !== 'undefined') {\n    const win = (globalThis as { window?: WindowWithEnv }).window\n    if (win?.env) {\n      return win.env\n    }\n  }\n  if (typeof process !== 'undefined') {\n    return process.env as EnvObject\n  }\n  return undefined\n}\n\nexport function getFalApiKeyFromEnv(): string {\n  const env = getEnvironment()\n  const key = env?.FAL_KEY\n\n  if (!key) {\n    throw new Error(\n      'FAL_KEY is required. Please set it in your environment variables or use the factory function with an explicit API key.',\n    )\n  }\n\n  return key\n}\n\nexport function configureFalClient(config?: FalClientConfig): void {\n  if (config?.proxyUrl) {\n    fal.config({\n      proxyUrl: config.proxyUrl,\n    })\n  } else {\n    const apiKey = config?.apiKey ?? getFalApiKeyFromEnv()\n    if (!apiKey) {\n      throw new Error('API key is required')\n    }\n    fal.config({\n      credentials: apiKey,\n    })\n  }\n}\n\nexport function generateId(prefix: string): string {\n  return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`\n}\n"],"names":[],"mappings":";AAeA,SAAS,iBAAwC;AAC/C,MAAI,OAAO,eAAe,aAAa;AACrC,UAAM,MAAO,WAA0C;AACvD,QAAI,KAAK,KAAK;AACZ,aAAO,IAAI;AAAA,IACb;AAAA,EACF;AACA,MAAI,OAAO,YAAY,aAAa;AAClC,WAAO,QAAQ;AAAA,EACjB;AACA,SAAO;AACT;AAEO,SAAS,sBAA8B;AAC5C,QAAM,MAAM,eAAA;AACZ,QAAM,MAAM,KAAK;AAEjB,MAAI,CAAC,KAAK;AACR,UAAM,IAAI;AAAA,MACR;AAAA,IAAA;AAAA,EAEJ;AAEA,SAAO;AACT;AAEO,SAAS,mBAAmB,QAAgC;AACjE,MAAI,QAAQ,UAAU;AACpB,QAAI,OAAO;AAAA,MACT,UAAU,OAAO;AAAA,IAAA,CAClB;AAAA,EACH,OAAO;AACL,UAAM,SAAS,QAAQ,UAAU,oBAAA;AACjC,QAAI,CAAC,QAAQ;AACX,YAAM,IAAI,MAAM,qBAAqB;AAAA,IACvC;AACA,QAAI,OAAO;AAAA,MACT,aAAa;AAAA,IAAA,CACd;AAAA,EACH;AACF;AAEO,SAAS,WAAW,QAAwB;AACjD,SAAO,GAAG,MAAM,IAAI,KAAK,KAAK,IAAI,KAAK,OAAA,EAAS,SAAS,EAAE,EAAE,UAAU,CAAC,CAAC;AAC3E;"}

package/dist/esm/utils/index.d.ts

@@ -0,0 +1 @@
+export { getFalApiKeyFromEnv, configureFalClient, generateId, type FalClientConfig, } from './client.js';

package/dist/esm/video/video-provider-options.d.ts

@@ -0,0 +1,2 @@
+import { FalModelVideoSize, FalModelVideoSizeInput } from '../model-meta.js';
+export declare function mapVideoSizeToFalFormat<TModel extends string>(size: FalModelVideoSize<TModel> | undefined): FalModelVideoSizeInput<TModel> | undefined;

package/dist/esm/video/video-provider-options.js

@@ -0,0 +1,14 @@
+function mapVideoSizeToFalFormat(size) {
+  if (!size) return void 0;
+  const match = size.match(/^(\d+:\d+)(?:_(.+))?$/);
+  return {
+    aspect_ratio: match?.[1],
+    ...match?.[2] && {
+      resolution: match[2]
+    }
+  };
+}
+export {
+  mapVideoSizeToFalFormat
+};
+//# sourceMappingURL=video-provider-options.js.map

package/dist/esm/video/video-provider-options.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"video-provider-options.js","sources":["../../../src/video/video-provider-options.ts"],"sourcesContent":["import type {\n  FalModelInput,\n  FalModelVideoSize,\n  FalModelVideoSizeInput,\n} from '../model-meta'\n\nexport function mapVideoSizeToFalFormat<TModel extends string>(\n  size: FalModelVideoSize<TModel> | undefined,\n): FalModelVideoSizeInput<TModel> | undefined {\n  if (!size) return undefined\n\n  // \"16:9_720p\" → { aspect_ratio, resolution }\n  // \"16:9\"      → { aspect_ratio }\n  const match = size.match(/^(\\d+:\\d+)(?:_(.+))?$/)\n\n  return {\n    aspect_ratio: match?.[1] as NonNullable<\n      FalModelInput<TModel>['aspect_ratio']\n    >,\n    ...(match?.[2] && {\n      resolution: match[2] as NonNullable<FalModelInput<TModel>['resolution']>,\n    }),\n  } as FalModelVideoSizeInput<TModel>\n}\n"],"names":[],"mappings":"AAMO,SAAS,wBACd,MAC4C;AAC5C,MAAI,CAAC,KAAM,QAAO;AAIlB,QAAM,QAAQ,KAAK,MAAM,uBAAuB;AAEhD,SAAO;AAAA,IACL,cAAc,QAAQ,CAAC;AAAA,IAGvB,GAAI,QAAQ,CAAC,KAAK;AAAA,MAChB,YAAY,MAAM,CAAC;AAAA,IAAA;AAAA,EACrB;AAEJ;"}

package/package.json

@@ -1,10 +1,54 @@
 {
   "name": "@tanstack/ai-fal",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @tanstack/ai-fal",
+  "version": "0.6.1",
+  "description": "fal.ai adapter for TanStack AI",
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TanStack/ai.git",
+    "directory": "packages/typescript/ai-fal"
+  },
+  "type": "module",
+  "module": "./dist/esm/index.js",
+  "types": "./dist/esm/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/esm/index.d.ts",
+      "import": "./dist/esm/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "ai",
+    "fal",
+    "tanstack",
+    "adapter",
+    "image-generation",
+    "video-generation"
+  ],
+  "dependencies": {
+    "@fal-ai/client": "^1.9.1"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "4.0.14",
+    "vite": "^7.2.7",
+    "@tanstack/ai": "0.6.1"
+  },
+  "peerDependencies": {
+    "@tanstack/ai": "0.6.1"
+  },
+  "scripts": {
+    "build": "vite build",
+    "clean": "premove ./build ./dist",
+    "lint:fix": "eslint ./src --fix",
+    "test:build": "publint --strict",
+    "test:eslint": "eslint ./src",
+    "test:lib": "vitest run",
+    "test:lib:dev": "pnpm test:lib --watch",
+    "test:types": "tsc"
+  }
+}

package/src/adapters/image.ts

@@ -0,0 +1,133 @@
+import { fal } from '@fal-ai/client'
+import { BaseImageAdapter } from '@tanstack/ai/adapters'
+import { configureFalClient, generateId as utilGenerateId } from '../utils'
+import { mapSizeToFalFormat } from '../image/image-provider-options'
+import type { OutputType, Result } from '@fal-ai/client'
+import type { FalClientConfig } from '../utils'
+import type {
+  GeneratedImage,
+  ImageGenerationOptions,
+  ImageGenerationResult,
+} from '@tanstack/ai'
+import type {
+  FalImageProviderOptions,
+  FalModel,
+  FalModelImageSize,
+  FalModelInput,
+} from '../model-meta'
+
+/**
+ * fal.ai image generation adapter with full type inference.
+ *
+ * Uses fal.ai's comprehensive type system to provide autocomplete
+ *
+ * and type safety for all 600+ supported models.
+ *
+ * @example
+ * ```typescript
+ * const adapter = falImage('fal-ai/flux/dev')
+ * const result = await adapter.generateImages({
+ *   model: 'fal-ai/flux/dev',
+ *   prompt: 'a cat',
+ *   modelOptions: {
+ *     num_inference_steps: 28, // Type-safe! Autocomplete works
+ *     guidance_scale: 3.5,
+ *   },
+ * })
+ * ```
+ */
+export class FalImageAdapter<TModel extends FalModel> extends BaseImageAdapter<
+  TModel,
+  FalImageProviderOptions<TModel>,
+  Record<TModel, FalImageProviderOptions<TModel>>,
+  Record<TModel, FalModelImageSize<TModel>>
+> {
+  readonly kind = 'image' as const
+  readonly name = 'fal' as const
+
+  constructor(model: TModel, config?: FalClientConfig) {
+    super({}, model)
+    configureFalClient(config)
+  }
+
+  async generateImages(
+    options: ImageGenerationOptions<
+      FalImageProviderOptions<TModel>,
+      FalModelImageSize<TModel>
+    >,
+  ): Promise<ImageGenerationResult> {
+    const input = this.buildInput(options)
+    const result = await fal.subscribe(this.model, { input })
+    return this.transformResponse(result)
+  }
+
+  private buildInput(
+    options: ImageGenerationOptions<FalImageProviderOptions<TModel>, string>,
+  ): FalModelInput<TModel> {
+    const sizeParams = mapSizeToFalFormat(options.size)
+    const input = {
+      ...options.modelOptions,
+      ...sizeParams,
+      prompt: options.prompt,
+      num_images: options.numberOfImages,
+    } as FalModelInput<TModel>
+    return input
+  }
+
+  protected override generateId(): string {
+    return utilGenerateId(this.name)
+  }
+
+  private transformResponse(
+    response: Result<OutputType<TModel>>,
+  ): ImageGenerationResult {
+    const images: Array<GeneratedImage> = []
+    const data = response.data
+
+    // Handle array of images (most models return { images: [...] })
+    if ('images' in data && Array.isArray(data.images)) {
+      for (const img of data.images) {
+        images.push(this.parseImage(img))
+      }
+    }
+    // Handle single image response (some models return { image: {...} })
+    else if ('image' in data && data.image && typeof data.image === 'object') {
+      images.push(this.parseImage(data.image))
+    }
+
+    return {
+      id: response.requestId || this.generateId(),
+      model: this.model,
+      images,
+    }
+  }
+
+  private parseImage(img: { url: string }): GeneratedImage {
+    const url = img.url
+    // Check if it's a base64 data URL
+    if (url.startsWith('data:')) {
+      const base64Match = url.match(/^data:image\/[^;]+;base64,(.+)$/)
+      if (base64Match) {
+        return {
+          b64Json: base64Match[1],
+          url,
+        }
+      }
+    }
+    return { url }
+  }
+}
+
+export function createFalImage<TModel extends FalModel>(
+  model: TModel,
+  config?: FalClientConfig,
+): FalImageAdapter<TModel> {
+  return new FalImageAdapter(model, config)
+}
+
+export function falImage<TModel extends FalModel>(
+  model: TModel,
+  config?: FalClientConfig,
+): FalImageAdapter<TModel> {
+  return createFalImage(model, config)
+}

package/src/adapters/video.ts

@@ -0,0 +1,162 @@
+import { fal } from '@fal-ai/client'
+import { BaseVideoAdapter } from '@tanstack/ai/adapters'
+import { configureFalClient, generateId as utilGenerateId } from '../utils'
+import { mapVideoSizeToFalFormat } from '../video/video-provider-options'
+import type {
+  VideoGenerationOptions,
+  VideoJobResult,
+  VideoStatusResult,
+  VideoUrlResult,
+} from '@tanstack/ai'
+import type {
+  FalModel,
+  FalModelInput,
+  FalModelVideoSize,
+  FalVideoProviderOptions,
+} from '../model-meta'
+import type { FalClientConfig } from '../utils'
+
+type FalQueueStatus = 'IN_QUEUE' | 'IN_PROGRESS' | 'COMPLETED'
+
+interface FalStatusResponse {
+  status: FalQueueStatus
+  queue_position?: number
+  logs?: Array<{ message: string }>
+}
+
+interface FalVideoResultData {
+  video?: { url: string }
+  video_url?: string
+}
+
+/**
+ * Maps fal.ai queue status to TanStack AI video status.
+ */
+function mapFalStatusToVideoStatus(
+  falStatus: FalQueueStatus,
+): VideoStatusResult['status'] {
+  switch (falStatus) {
+    case 'IN_QUEUE':
+      return 'pending'
+    case 'IN_PROGRESS':
+      return 'processing'
+    case 'COMPLETED':
+      return 'completed'
+    default:
+      return 'processing'
+  }
+}
+
+/**
+ * fal.ai video generation adapter.
+ * Supports MiniMax, Luma, Kling, Hunyuan, and other fal.ai video models.
+ *
+ * Uses fal.ai's comprehensive type system to provide autocomplete
+ * and type safety for all supported video models.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
+  TModel,
+  FalVideoProviderOptions<TModel>,
+  Record<TModel, FalVideoProviderOptions<TModel>>,
+  Record<TModel, FalModelVideoSize<TModel>>
+> {
+  readonly kind = 'video' as const
+  readonly name = 'fal' as const
+
+  constructor(model: TModel, config?: FalClientConfig) {
+    super({}, model)
+    configureFalClient(config)
+  }
+
+  async createVideoJob(
+    options: VideoGenerationOptions<
+      FalVideoProviderOptions<TModel>,
+      FalModelVideoSize<TModel>
+    >,
+  ): Promise<VideoJobResult> {
+    const { prompt, size, duration, modelOptions } = options
+    const sizeParams = mapVideoSizeToFalFormat(size)
+
+    const input = {
+      ...modelOptions,
+      ...sizeParams,
+      prompt,
+      ...(duration ? { duration } : {}),
+    } as FalModelInput<TModel>
+
+    // Submit to queue and get request ID
+    const { request_id } = await fal.queue.submit(this.model, {
+      input,
+    })
+
+    return {
+      jobId: request_id,
+      model: this.model,
+    }
+  }
+
+  async getVideoStatus(jobId: string): Promise<VideoStatusResult> {
+    const statusResponse = (await fal.queue.status(this.model, {
+      requestId: jobId,
+      logs: true,
+    })) as FalStatusResponse
+
+    return {
+      jobId,
+      status: mapFalStatusToVideoStatus(statusResponse.status),
+      progress:
+        statusResponse.queue_position != null
+          ? Math.max(0, 100 - statusResponse.queue_position * 10)
+          : undefined,
+    }
+  }
+
+  async getVideoUrl(jobId: string): Promise<VideoUrlResult> {
+    const result = await fal.queue.result(this.model, {
+      requestId: jobId,
+    })
+
+    const data = result.data as FalVideoResultData
+
+    // Different models return video URL in different formats
+    const url = data.video?.url || data.video_url
+    if (!url) {
+      throw new Error('Video URL not found in response')
+    }
+
+    return {
+      jobId,
+      url,
+    }
+  }
+
+  protected override generateId(): string {
+    return utilGenerateId(this.name)
+  }
+}
+
+/**
+ * Create a fal.ai video adapter with an explicit API key.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export function createFalVideo<TModel extends FalModel>(
+  model: TModel,
+  config?: FalClientConfig,
+): FalVideoAdapter<TModel> {
+  return new FalVideoAdapter(model, config)
+}
+
+/**
+ * Create a fal.ai video adapter using config.apiKey or the FAL_KEY environment variable.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export function falVideo<TModel extends FalModel>(
+  model: TModel,
+  config?: FalClientConfig,
+): FalVideoAdapter<TModel> {
+  return createFalVideo(model, config)
+}

package/src/image/image-provider-options.ts

@@ -0,0 +1,20 @@
+import type { FalModelImageSize, FalModelImageSizeInput } from '../model-meta'
+
+export function mapSizeToFalFormat<TModel extends string>(
+  size: FalModelImageSize<TModel> | undefined,
+): FalModelImageSizeInput<TModel> | undefined {
+  if (!size) return undefined
+
+  // "16:9_4K" → { aspect_ratio, resolution }
+  // "16:9"    → { aspect_ratio }
+  // no match  → { image_size }
+  const match = size.match(/^(\d+:\d+)(?:_(.+))?$/)
+
+  return {
+    image_size: size,
+    aspect_ratio: match?.[1],
+    ...(match?.[2] && {
+      resolution: match?.[2],
+    }),
+  }
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+// ============================================================================
+// Image Adapter
+// ============================================================================
+
+export { FalImageAdapter, falImage } from './adapters/image'
+
+// ============================================================================
+// Video Adapter (Experimental)
+// ============================================================================
+
+export { FalVideoAdapter, falVideo } from './adapters/video'
+
+// ============================================================================
+// Model Types (from fal.ai's type system)
+// ============================================================================
+
+export {
+  type FalImageProviderOptions,
+  type FalVideoProviderOptions,
+  type FalModel,
+  type FalModelInput,
+  type FalModelOutput,
+  type FalModelImageSize,
+  type FalModelVideoSize,
+} from './model-meta'
+// ============================================================================
+// Utils
+// ============================================================================
+
+export {
+  getFalApiKeyFromEnv,
+  configureFalClient,
+  generateId,
+  type FalClientConfig,
+} from './utils'

package/src/model-meta.ts

@@ -0,0 +1,121 @@
+/**
+ * Re-export fal.ai's comprehensive type system for full model support.
+ * The fal.ai SDK provides types for 600+ models through EndpointTypeMap.
+ * These types give you full autocomplete and type safety for any model.
+ */
+import type { EndpointTypeMap } from '@fal-ai/client/endpoints'
+
+export type { EndpointTypeMap } from '@fal-ai/client/endpoints'
+
+/**
+ * All known fal.ai model IDs with autocomplete support.
+ * Also accepts any string for custom/new models.
+ */
+export type FalModel = keyof EndpointTypeMap | (string & {})
+
+/**
+ * Utility type to extract the input type for a specific fal model.
+ *
+ * @example
+ * type FluxInput = FalModelInput<'fal-ai/flux/dev'>
+ * // { prompt: string; num_inference_steps?: number; ... }
+ */
+export type FalModelInput<TModel extends string> =
+  TModel extends keyof EndpointTypeMap
+    ? EndpointTypeMap[TModel]['input']
+    : Record<string, any>
+
+/**
+ * Utility type to extract the output type for a specific fal model.
+ *
+ * @example
+ * type FluxOutput = FalModelOutput<'fal-ai/flux/dev'>
+ * // { images: Array<Image>; seed: number; ... }
+ */
+export type FalModelOutput<TModel extends string> =
+  TModel extends keyof EndpointTypeMap
+    ? EndpointTypeMap[TModel]['output']
+    : unknown
+
+/**
+ * Extract the image_size type supported by a specific fal model.
+ * Returns never if the model doesn't support image_size.
+ *
+ * @example
+ * type FluxSize = FalModelImageSize<'fal-ai/flux/dev'>
+ * // "square_hd" | "square" | "portrait_4_3" | "portrait_16_9" | ...
+ */
+export type FalModelImageSize<TModel extends string> =
+  TModel extends keyof EndpointTypeMap
+    ? 'image_size' extends keyof EndpointTypeMap[TModel]['input']
+      ? NonNullable<Exclude<FalModelInput<TModel>['image_size'], object>>
+      : 'aspect_ratio' extends keyof EndpointTypeMap[TModel]['input']
+        ? 'resolution' extends keyof EndpointTypeMap[TModel]['input']
+          ? `${NonNullable<FalModelInput<TModel>['aspect_ratio']>}_${NonNullable<FalModelInput<TModel>['resolution']>}`
+          : NonNullable<FalModelInput<TModel>['aspect_ratio']>
+        : never
+    : string
+
+export type FalModelImageSizeInput<TModel extends string> =
+  TModel extends keyof EndpointTypeMap
+    ? 'aspect_ratio' extends keyof EndpointTypeMap[TModel]['input']
+      ? 'resolution' extends keyof EndpointTypeMap[TModel]['input']
+        ? {
+            aspect_ratio: FalModelInput<TModel>['aspect_ratio']
+            resolution: FalModelInput<TModel>['resolution']
+          }
+        : { aspect_ratio: NonNullable<FalModelInput<TModel>['aspect_ratio']> }
+      : { image_size: FalModelImageSize<TModel> }
+    : { image_size: string }
+
+/**
+ * Provider options for image generation, excluding fields TanStack AI handles.
+ * Use this for the `modelOptions` parameter in image generation.
+ *
+ * @example
+ * type FluxOptions = FalImageProviderOptions<'fal-ai/flux/dev'>
+ * // { num_inference_steps?: number; guidance_scale?: number; seed?: number; ... }
+ */
+export type FalImageProviderOptions<TModel extends string> = Omit<
+  FalModelInput<TModel>,
+  'prompt'
+>
+
+/**
+ * Extract the video size type supported by a specific fal model.
+ * Video models typically use aspect_ratio and/or resolution fields.
+ *
+ * Follows the same pattern as FalModelImageSize:
+ * - aspect_ratio + resolution → "16:9_720p"
+ * - aspect_ratio only → "16:9"
+ * - unknown models → string
+ */
+export type FalModelVideoSize<TModel extends string> =
+  TModel extends keyof EndpointTypeMap
+    ? 'aspect_ratio' extends keyof EndpointTypeMap[TModel]['input']
+      ? 'resolution' extends keyof EndpointTypeMap[TModel]['input']
+        ? `${NonNullable<FalModelInput<TModel>['aspect_ratio']>}_${NonNullable<FalModelInput<TModel>['resolution']>}`
+        : NonNullable<FalModelInput<TModel>['aspect_ratio']>
+      : never
+    : string
+
+export type FalModelVideoSizeInput<TModel extends string> =
+  TModel extends keyof EndpointTypeMap
+    ? 'aspect_ratio' extends keyof EndpointTypeMap[TModel]['input']
+      ? 'resolution' extends keyof EndpointTypeMap[TModel]['input']
+        ? {
+            aspect_ratio: FalModelInput<TModel>['aspect_ratio']
+            resolution: FalModelInput<TModel>['resolution']
+          }
+        : { aspect_ratio: NonNullable<FalModelInput<TModel>['aspect_ratio']> }
+      : { aspect_ratio: string }
+    : { aspect_ratio: string }
+
+/**
+ * Provider options for video generation, excluding fields TanStack AI handles.
+ * Use this for the `modelOptions` parameter in video generation.
+ */
+export type FalVideoProviderOptions<TModel extends string> =
+  TModel extends keyof EndpointTypeMap
+    ? Omit<FalModelInput<TModel>, 'prompt'>
+    : Record<string, any>

package/src/utils/client.ts

@@ -0,0 +1,60 @@
+import { fal } from '@fal-ai/client'
+
+export interface FalClientConfig {
+  apiKey: string
+  proxyUrl?: string
+}
+
+interface EnvObject {
+  FAL_KEY?: string
+}
+
+interface WindowWithEnv {
+  env?: EnvObject
+}
+
+function getEnvironment(): EnvObject | undefined {
+  if (typeof globalThis !== 'undefined') {
+    const win = (globalThis as { window?: WindowWithEnv }).window
+    if (win?.env) {
+      return win.env
+    }
+  }
+  if (typeof process !== 'undefined') {
+    return process.env as EnvObject
+  }
+  return undefined
+}
+
+export function getFalApiKeyFromEnv(): string {
+  const env = getEnvironment()
+  const key = env?.FAL_KEY
+
+  if (!key) {
+    throw new Error(
+      'FAL_KEY is required. Please set it in your environment variables or use the factory function with an explicit API key.',
+    )
+  }
+
+  return key
+}
+
+export function configureFalClient(config?: FalClientConfig): void {
+  if (config?.proxyUrl) {
+    fal.config({
+      proxyUrl: config.proxyUrl,
+    })
+  } else {
+    const apiKey = config?.apiKey ?? getFalApiKeyFromEnv()
+    if (!apiKey) {
+      throw new Error('API key is required')
+    }
+    fal.config({
+      credentials: apiKey,
+    })
+  }
+}
+
+export function generateId(prefix: string): string {
+  return `${prefix}-${Date.now()}-${Math.random().toString(36).substring(7)}`
+}

package/src/utils/index.ts

@@ -0,0 +1,6 @@
+export {
+  getFalApiKeyFromEnv,
+  configureFalClient,
+  generateId,
+  type FalClientConfig,
+} from './client'

package/src/video/video-provider-options.ts

@@ -0,0 +1,24 @@
+import type {
+  FalModelInput,
+  FalModelVideoSize,
+  FalModelVideoSizeInput,
+} from '../model-meta'
+
+export function mapVideoSizeToFalFormat<TModel extends string>(
+  size: FalModelVideoSize<TModel> | undefined,
+): FalModelVideoSizeInput<TModel> | undefined {
+  if (!size) return undefined
+
+  // "16:9_720p" → { aspect_ratio, resolution }
+  // "16:9"      → { aspect_ratio }
+  const match = size.match(/^(\d+:\d+)(?:_(.+))?$/)
+
+  return {
+    aspect_ratio: match?.[1] as NonNullable<
+      FalModelInput<TModel>['aspect_ratio']
+    >,
+    ...(match?.[2] && {
+      resolution: match[2] as NonNullable<FalModelInput<TModel>['resolution']>,
+    }),
+  } as FalModelVideoSizeInput<TModel>
+}

package/README.md

@@ -1,45 +0,0 @@
-# @tanstack/ai-fal
-
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@tanstack/ai-fal`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**