/** * 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' import type { MediaPromptModality } from '@tanstack/ai' import type { FalImageFieldName } from './image/generated/image-field-overrides' import type { FAL_MESH_FIELD_MAP, FalMeshFieldName, } from './model3d/generated/mesh-field-overrides' 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 keyof EndpointTypeMap ? EndpointTypeMap[TModel]['input'] : Record /** * Utility type to extract the output type for a specific fal model. * * @example * type FluxOutput = FalModelOutput<'fal-ai/flux/dev'> * // { images: Array; seed: number; ... } */ export type FalModelOutput = 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 keyof EndpointTypeMap ? 'image_size' extends keyof EndpointTypeMap[TModel]['input'] ? NonNullable['image_size'], object>> : 'aspect_ratio' extends keyof EndpointTypeMap[TModel]['input'] ? 'resolution' extends keyof EndpointTypeMap[TModel]['input'] ? `${Extract['aspect_ratio']>, string>}_${Extract['resolution']>, string>}` : Extract['aspect_ratio']>, string> : undefined : string export type FalModelImageSizeInput = TModel extends keyof EndpointTypeMap ? 'aspect_ratio' extends keyof EndpointTypeMap[TModel]['input'] ? 'resolution' extends keyof EndpointTypeMap[TModel]['input'] ? { aspect_ratio: FalModelInput['aspect_ratio'] resolution: FalModelInput['resolution'] } : { aspect_ratio: NonNullable['aspect_ratio']> } : 'image_size' extends keyof EndpointTypeMap[TModel]['input'] ? { image_size: FalModelImageSize } : never : { image_size: string } /** * Input fields the prompt-part mappers can populate: image conditioning via * the generated `FalImageFieldName` set, video conditioning via * `video_url` / `video_urls` / `reference_video_urls`, audio via `audio_url`. */ type FalMediaInputFieldName = | FalImageFieldName | 'video_url' | 'video_urls' | 'reference_video_urls' | 'audio_url' /** * Demote an endpoint input's media-conditioning fields from required to * optional. Image-to-video endpoints declare e.g. `image_url` as a required * input, but with a multimodal `prompt` the start frame usually arrives as a * prompt part — requiring it in `modelOptions` too would force redundancy. * The fields stay passable via `modelOptions` as the documented escape hatch * (and override-wise the mapped prompt-part fields win on conflict). */ type WithOptionalMediaInputFields = Omit< TInput, Extract > & Partial>> /** * 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 = WithOptionalMediaInputFields, 'prompt'>> /** * Extract the video size type supported by a specific fal model. * Video models typically use aspect_ratio and/or resolution fields. * * - aspect_ratio + resolution → "16:9_720p" * - aspect_ratio only → "16:9" * - resolution only → "720p" * - neither → undefined (the model takes no size param) * - unknown models → string */ export type FalModelVideoSize = TModel extends keyof EndpointTypeMap ? 'aspect_ratio' extends keyof EndpointTypeMap[TModel]['input'] ? 'resolution' extends keyof EndpointTypeMap[TModel]['input'] ? `${Extract['aspect_ratio']>, string>}_${Extract['resolution']>, string>}` : Extract['aspect_ratio']>, string> : 'resolution' extends keyof EndpointTypeMap[TModel]['input'] ? Extract['resolution']>, string> : undefined : string export type FalModelVideoSizeInput = TModel extends keyof EndpointTypeMap ? 'aspect_ratio' extends keyof EndpointTypeMap[TModel]['input'] ? 'resolution' extends keyof EndpointTypeMap[TModel]['input'] ? { aspect_ratio: FalModelInput['aspect_ratio'] resolution: FalModelInput['resolution'] } : { aspect_ratio: NonNullable['aspect_ratio']> } : 'resolution' extends keyof EndpointTypeMap[TModel]['input'] ? { resolution: NonNullable['resolution']> } : never : { aspect_ratio?: string; resolution?: string } /** * Extract the `duration` field type from a fal video model's input. * Falls back to `string | number | undefined` for models not in the SDK's * `EndpointTypeMap`. * * Shapes seen in the wild: * - `'5' | '10'` (Kling, Pika): discrete numeric strings * - `'5s' | '9s'` (Luma): keyword strings with unit * - `'4s' | '6s' | '8s'` (Veo3 via FAL): keyword strings * - `'2' | … | '15'` (WAN-25): discrete-range numeric strings * - undefined (Minimax, Hunyuan): no duration field; passing one is a type error */ export type FalModelVideoDuration = TModel extends keyof EndpointTypeMap ? 'duration' extends keyof EndpointTypeMap[TModel]['input'] ? Extract< NonNullable< EndpointTypeMap[TModel]['input'] extends { duration?: infer D } ? D : never >, string | number > : undefined : string | number | undefined /** * Prompt input modalities for a fal image endpoint, derived from the SDK's * endpoint input type: an endpoint accepts image prompt parts exactly when * its input declares one of the known image-conditioning fields * (`image_url`, `image_urls`, `mask_url`, …). Endpoints unknown to the * installed SDK are unconstrained. */ export type FalImagePromptModalitiesFor = TModel extends keyof EndpointTypeMap ? ReadonlyArray< Extract, FalImageFieldName> extends never ? never : 'image' > : ReadonlyArray /** * Prompt input modalities for a fal video endpoint. Image conditioning is * detected via the same field set as image endpoints; video conditioning via * `video_url` / `video_urls` / `reference_video_urls`; audio conditioning * via `audio_url`. Endpoints unknown to the installed SDK are unconstrained. */ export type FalVideoPromptModalitiesFor = TModel extends keyof EndpointTypeMap ? ReadonlyArray< | (Extract, FalImageFieldName> extends never ? never : 'image') | (Extract< keyof FalModelInput, 'video_url' | 'video_urls' | 'reference_video_urls' > extends never ? never : 'video') | (Extract, 'audio_url'> extends never ? never : 'audio') > : ReadonlyArray /** * Provider options for video generation, excluding fields TanStack AI handles. * Use this for the `modelOptions` parameter in video generation. * * Media-conditioning fields (start/end frame, reference images, source * video/audio) are optional here even when the endpoint requires them — * they're usually supplied as prompt parts instead. */ export type FalVideoProviderOptions = TModel extends keyof EndpointTypeMap ? WithOptionalMediaInputFields< Omit, 'prompt' | 'duration'> > : Record /** * Provider options for TTS, excluding fields TanStack AI handles. * Use this for the `modelOptions` parameter in speech generation. */ export type FalSpeechProviderOptions = Omit< FalModelInput, 'prompt' | 'text' > /** * Provider options for transcription, excluding fields TanStack AI handles. * Use this for the `modelOptions` parameter in transcription. */ export type FalTranscriptionProviderOptions = Omit< FalModelInput, 'audio_url' > /** * Provider options for audio generation, excluding fields TanStack AI handles. * Use this for the `modelOptions` parameter in audio generation. */ export type FalAudioProviderOptions = Omit< FalModelInput, 'prompt' > /** * The fal 3D endpoints that `fal3dModel()` knows. Each id is a key of the * installed SDK's `EndpointTypeMap`, and each endpoint returns a mesh file. * * @experimental 3D model generation is experimental and may change. */ export type Fal3dKnownModel = | 'fal-ai/hunyuan3d/v2' | 'fal-ai/hunyuan3d/v2/turbo' | 'fal-ai/hunyuan3d/v2/mini' | 'fal-ai/hunyuan3d/v2/mini/turbo' | 'fal-ai/hunyuan3d/v2/multi-view' | 'fal-ai/hunyuan3d/v2/multi-view/turbo' | 'fal-ai/hunyuan3d-v3/image-to-3d' | 'fal-ai/hunyuan3d-v3/text-to-3d' | 'fal-ai/hunyuan-3d/v3.1/pro/image-to-3d' | 'fal-ai/hunyuan-3d/v3.1/pro/text-to-3d' | 'fal-ai/hunyuan-3d/v3.1/rapid/image-to-3d' | 'fal-ai/hunyuan-3d/v3.1/rapid/text-to-3d' | 'fal-ai/hyper3d/rodin' | 'fal-ai/hyper3d/rodin/v2' | 'fal-ai/meshy/v6/image-to-3d' | 'fal-ai/meshy/v6/text-to-3d' | 'fal-ai/meshy/v6-preview/text-to-3d' | 'meshy/v7.1/image-to-3d' | 'meshy/v7.1/multi-image-to-3d' | 'meshy/v7.1/text-to-3d' | 'meshy/v7/retexture' | 'fal-ai/trellis' | 'fal-ai/trellis/multi' | 'fal-ai/trellis-2' | 'fal-ai/trellis-2/retexture' | 'tripo3d/tripo/v2.5/image-to-3d' | 'tripo3d/tripo/v2.5/multiview-to-3d' | 'tripo3d/tripo/remesh' | 'fal-ai/sam-3/3d-objects' | 'fal-ai/sam-3/3d-body' /** * A fal 3D endpoint id. The known ids autocomplete. Any other string also * works, without typed options, so a new fal endpoint is usable at once. * * @experimental 3D model generation is experimental and may change. */ export type Fal3dModel = Fal3dKnownModel | (string & {}) /** * Input fields that take the text of a 3D prompt: `prompt`, or * `text_style_prompt` for Meshy retexture. */ export type Fal3dTextFieldName = 'prompt' | 'text_style_prompt' /** * Input fields that take the image parts of a 3D prompt: the fields of the * generated image field map, and `image_style_url` for Meshy retexture. */ export type Fal3dImageFieldName = FalImageFieldName | 'image_style_url' /** Input fields that the 3D adapter fills from the prompt. */ type Fal3dPromptFieldName = | Fal3dTextFieldName | Fal3dImageFieldName | FalMeshFieldName /** * Provider options for 3D model generation: the endpoint input without the * fields that the adapter fills from the prompt (the text field, the image * fields, and the mesh field). Endpoints that the installed SDK does not know * take any options. * * @example * type Options = Fal3dModelProviderOptions<'fal-ai/hunyuan3d-v3/image-to-3d'> * // { face_count?: number; generate_type?: 'Normal' | 'LowPoly' | 'Geometry'; ... } * * @experimental 3D model generation is experimental and may change. */ export type Fal3dModelProviderOptions = TModel extends keyof EndpointTypeMap ? Omit, Fal3dPromptFieldName> : Record /** * Prompt input modalities for a fal 3D endpoint. An endpoint takes image * parts when its input has one of the {@link Fal3dImageFieldName} fields. It * takes a `model3d` part when the generated mesh field map lists it. * Endpoints that the installed SDK does not know are unconstrained. * * @experimental 3D model generation is experimental and may change. */ export type Fal3dPromptModalitiesFor = TModel extends keyof EndpointTypeMap ? ReadonlyArray< | (Extract< keyof FalModelInput, Fal3dImageFieldName > extends never ? never : 'image') | (TModel extends keyof typeof FAL_MESH_FIELD_MAP ? 'model3d' : never) > : ReadonlyArray