fal.toolkit package

Subpackages

Submodules

fal.toolkit.exceptions module

exception fal.toolkit.exceptions.FalTookitException

Bases: Exception

Base exception for all toolkit exceptions

exception fal.toolkit.exceptions.FileUploadException

Bases: FalTookitException

Raised when file upload fails

exception fal.toolkit.exceptions.KVStoreException

Bases: FalTookitException

Raised when KV store operation fails

fal.toolkit.kv module

class fal.toolkit.kv.KVStore(db_name)

Bases: object

A key-value store client for interacting with the FAL KV service.

Parameters:

db_name (str) – The name of the database/namespace to use for this KV store.

property auth_headers: Dict[str, str]
get(key)

Retrieve a value from the key-value store.

Parameters:

key (str) – The key to retrieve the value for.

Return type:

Optional[str]

Returns:

The value associated with the key, or None if the key doesn’t exist.

set(key, value)

Store a value in the key-value store.

Parameters:

  • key (str) – The key to store the value under.

  • value (str) – The value to store.

Return type:

None

fal.toolkit.optimize module

fal.toolkit.optimize.optimize(module, *, optimization_config=None)

Optimize the given torch module with dynamic compilation and quantization techniques. Only applicable under fal’s cloud environment.

Warning: This function is experimental and may not work as expected.

Return type:

torch.nn.Module

fal.toolkit.types module

class fal.toolkit.types.DataUri

Bases: DownloadFileMixin, str

class fal.toolkit.types.DownloadFileMixin

Bases: object

as_temp_file()
Return type:

Generator[Path, None, None]

class fal.toolkit.types.DownloadImageMixin

Bases: object

to_pil()
class fal.toolkit.types.HttpsUrl

Bases: DownloadFileMixin, str

class fal.toolkit.types.ImageDataUri

Bases: DownloadImageMixin, DataUri

class fal.toolkit.types.ImageHttpsUrl

Bases: DownloadImageMixin, HttpsUrl

Module contents

class fal.toolkit.Audio(**data)

Bases: File

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'ui': {'field': 'audio'}}}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

fal.toolkit.AudioField(default=PydanticUndefined, *, default_factory=PydanticUndefined, alias=PydanticUndefined, alias_priority=PydanticUndefined, validation_alias=PydanticUndefined, serialization_alias=PydanticUndefined, title=PydanticUndefined, field_title_generator=PydanticUndefined, description=PydanticUndefined, examples=PydanticUndefined, exclude=PydanticUndefined, discriminator=PydanticUndefined, deprecated=PydanticUndefined, json_schema_extra=PydanticUndefined, frozen=PydanticUndefined, validate_default=PydanticUndefined, repr=PydanticUndefined, init=PydanticUndefined, init_var=PydanticUndefined, kw_only=PydanticUndefined, pattern=PydanticUndefined, strict=PydanticUndefined, coerce_numbers_to_str=PydanticUndefined, gt=PydanticUndefined, ge=PydanticUndefined, lt=PydanticUndefined, le=PydanticUndefined, multiple_of=PydanticUndefined, allow_inf_nan=PydanticUndefined, max_digits=PydanticUndefined, decimal_places=PydanticUndefined, min_length=PydanticUndefined, max_length=PydanticUndefined, union_mode=PydanticUndefined, fail_fast=PydanticUndefined, **extra)

Usage docs: https://docs.pydantic.dev/2.10/concepts/fields

Create a field for objects that can be configured.

Used to provide extra information about a field, either for the model schema or complex validation. Some arguments apply only to number fields (int, float, Decimal) and some apply only to str.

Note

  • Any _Unset objects will be replaced by the corresponding value defined in the _DefaultValues dictionary. If a key for the _Unset object is not found in the _DefaultValues dictionary, it will default to None

Parameters:

  • default (Any) – Default value if the field is not set.

  • default_factory (Callable[[], Any] | Callable[[dict[str, Any]], Any] | None) – A callable to generate the default value. The callable can either take 0 arguments (in which case it is called as is) or a single argument containing the already validated data.

  • alias (str | None) – The name to use for the attribute when validating or serializing by alias. This is often used for things like converting between snake and camel case.

  • alias_priority (int | None) – Priority of the alias. This affects whether an alias generator is used.

  • validation_alias (str | AliasPath | AliasChoices | None) – Like alias, but only affects validation, not serialization.

  • serialization_alias (str | None) – Like alias, but only affects serialization, not validation.

  • title (str | None) – Human-readable title.

  • field_title_generator (Callable[[str, FieldInfo], str] | None) – A callable that takes a field name and returns title for it.

  • description (str | None) – Human-readable description.

  • examples (list[Any] | None) – Example values for this field.

  • exclude (bool | None) – Whether to exclude the field from the model serialization.

  • discriminator (str | types.Discriminator | None) – Field name or Discriminator for discriminating the type in a tagged union.

  • deprecated (Deprecated | str | bool | None) – A deprecation message, an instance of warnings.deprecated or the typing_extensions.deprecated backport, or a boolean. If True, a default deprecation message will be emitted when accessing the field.

  • json_schema_extra (JsonDict | Callable[[JsonDict], None] | None) – A dict or callable to provide extra JSON schema properties.

  • frozen (bool | None) – Whether the field is frozen. If true, attempts to change the value on an instance will raise an error.

  • validate_default (bool | None) – If True, apply validation to the default value every time you create an instance. Otherwise, for performance reasons, the default value of the field is trusted and not validated.

  • repr (bool) – A boolean indicating whether to include the field in the __repr__ output.

  • init (bool | None) – Whether the field should be included in the constructor of the dataclass. (Only applies to dataclasses.)

  • init_var (bool | None) – Whether the field should _only_ be included in the constructor of the dataclass. (Only applies to dataclasses.)

  • kw_only (bool | None) – Whether the field should be a keyword-only argument in the constructor of the dataclass. (Only applies to dataclasses.)

  • coerce_numbers_to_str (bool | None) – Whether to enable coercion of any Number type to str (not applicable in strict mode).

  • strict (bool | None) – If True, strict validation is applied to the field. See [Strict Mode](../concepts/strict_mode.md) for details.

  • gt (annotated_types.SupportsGt | None) – Greater than. If set, value must be greater than this. Only applicable to numbers.

  • ge (annotated_types.SupportsGe | None) – Greater than or equal. If set, value must be greater than or equal to this. Only applicable to numbers.

  • lt (annotated_types.SupportsLt | None) – Less than. If set, value must be less than this. Only applicable to numbers.

  • le (annotated_types.SupportsLe | None) – Less than or equal. If set, value must be less than or equal to this. Only applicable to numbers.

  • multiple_of (float | None) – Value must be a multiple of this. Only applicable to numbers.

  • min_length (int | None) – Minimum length for iterables.

  • max_length (int | None) – Maximum length for iterables.

  • pattern (str | typing.Pattern[str] | None) – Pattern for strings (a regular expression).

  • allow_inf_nan (bool | None) – Allow inf, -inf, nan. Only applicable to numbers.

  • max_digits (int | None) – Maximum number of allow digits for strings.

  • decimal_places (int | None) – Maximum number of decimal places allowed for numbers.

  • union_mode (Literal[‘smart’, ‘left_to_right’]) – The strategy to apply when validating a union. Can be smart (the default), or left_to_right. See [Union Mode](../concepts/unions.md#union-modes) for details.

  • fail_fast (bool | None) – If True, validation will stop on the first error. If False, all validation errors will be collected. This option can be applied only to iterable types (list, tuple, set, and frozenset).

  • extra (Unpack[_EmptyKwargs]) –

    (Deprecated) Extra fields that will be included in the JSON schema.

    !!! warning Deprecated

    The extra kwargs is deprecated. Use json_schema_extra instead.

Return type:

Any

Returns:

A new [FieldInfo][pydantic.fields.FieldInfo]. The return annotation is Any so Field can be used on

type-annotated fields without causing a type error.

class fal.toolkit.CompressedFile(**data)

Bases: File

extract_dir: Optional[str]
glob(pattern)
model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class fal.toolkit.File(**data)

Bases: BaseModel

as_bytes()
Return type:

bytes

content_type: Optional[str]
file_data: Optional[bytes]
file_name: Optional[str]
file_size: Optional[int]
classmethod from_bytes(data, content_type=None, file_name=None, repository='fal_v3', fallback_repository=['cdn', 'fal'], request=None, save_kwargs=None, fallback_save_kwargs=None)
Return type:

File

classmethod from_path(path, content_type=None, repository='fal_v3', multipart=None, fallback_repository=['cdn', 'fal'], request=None, save_kwargs=None, fallback_save_kwargs=None)
Return type:

File

model_config: ClassVar[ConfigDict] = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

save(path, overwrite=False)
Return type:

Path

url: str
fal.toolkit.FileField(default=PydanticUndefined, *, default_factory=PydanticUndefined, alias=PydanticUndefined, alias_priority=PydanticUndefined, validation_alias=PydanticUndefined, serialization_alias=PydanticUndefined, title=PydanticUndefined, field_title_generator=PydanticUndefined, description=PydanticUndefined, examples=PydanticUndefined, exclude=PydanticUndefined, discriminator=PydanticUndefined, deprecated=PydanticUndefined, json_schema_extra=PydanticUndefined, frozen=PydanticUndefined, validate_default=PydanticUndefined, repr=PydanticUndefined, init=PydanticUndefined, init_var=PydanticUndefined, kw_only=PydanticUndefined, pattern=PydanticUndefined, strict=PydanticUndefined, coerce_numbers_to_str=PydanticUndefined, gt=PydanticUndefined, ge=PydanticUndefined, lt=PydanticUndefined, le=PydanticUndefined, multiple_of=PydanticUndefined, allow_inf_nan=PydanticUndefined, max_digits=PydanticUndefined, decimal_places=PydanticUndefined, min_length=PydanticUndefined, max_length=PydanticUndefined, union_mode=PydanticUndefined, fail_fast=PydanticUndefined, **extra)

Usage docs: https://docs.pydantic.dev/2.10/concepts/fields

Create a field for objects that can be configured.

Used to provide extra information about a field, either for the model schema or complex validation. Some arguments apply only to number fields (int, float, Decimal) and some apply only to str.

Note

  • Any _Unset objects will be replaced by the corresponding value defined in the _DefaultValues dictionary. If a key for the _Unset object is not found in the _DefaultValues dictionary, it will default to None

Parameters:

  • default (Any) – Default value if the field is not set.

  • default_factory (Callable[[], Any] | Callable[[dict[str, Any]], Any] | None) – A callable to generate the default value. The callable can either take 0 arguments (in which case it is called as is) or a single argument containing the already validated data.

  • alias (str | None) – The name to use for the attribute when validating or serializing by alias. This is often used for things like converting between snake and camel case.

  • alias_priority (int | None) – Priority of the alias. This affects whether an alias generator is used.

  • validation_alias (str | AliasPath | AliasChoices | None) – Like alias, but only affects validation, not serialization.

  • serialization_alias (str | None) – Like alias, but only affects serialization, not validation.

  • title (str | None) – Human-readable title.

  • field_title_generator (Callable[[str, FieldInfo], str] | None) – A callable that takes a field name and returns title for it.

  • description (str | None) – Human-readable description.

  • examples (list[Any] | None) – Example values for this field.

  • exclude (bool | None) – Whether to exclude the field from the model serialization.

  • discriminator (str | types.Discriminator | None) – Field name or Discriminator for discriminating the type in a tagged union.

  • deprecated (Deprecated | str | bool | None) – A deprecation message, an instance of warnings.deprecated or the typing_extensions.deprecated backport, or a boolean. If True, a default deprecation message will be emitted when accessing the field.

  • json_schema_extra (JsonDict | Callable[[JsonDict], None] | None) – A dict or callable to provide extra JSON schema properties.

  • frozen (bool | None) – Whether the field is frozen. If true, attempts to change the value on an instance will raise an error.

  • validate_default (bool | None) – If True, apply validation to the default value every time you create an instance. Otherwise, for performance reasons, the default value of the field is trusted and not validated.

  • repr (bool) – A boolean indicating whether to include the field in the __repr__ output.

  • init (bool | None) – Whether the field should be included in the constructor of the dataclass. (Only applies to dataclasses.)

  • init_var (bool | None) – Whether the field should _only_ be included in the constructor of the dataclass. (Only applies to dataclasses.)

  • kw_only (bool | None) – Whether the field should be a keyword-only argument in the constructor of the dataclass. (Only applies to dataclasses.)

  • coerce_numbers_to_str (bool | None) – Whether to enable coercion of any Number type to str (not applicable in strict mode).

  • strict (bool | None) – If True, strict validation is applied to the field. See [Strict Mode](../concepts/strict_mode.md) for details.

  • gt (annotated_types.SupportsGt | None) – Greater than. If set, value must be greater than this. Only applicable to numbers.

  • ge (annotated_types.SupportsGe | None) – Greater than or equal. If set, value must be greater than or equal to this. Only applicable to numbers.

  • lt (annotated_types.SupportsLt | None) – Less than. If set, value must be less than this. Only applicable to numbers.

  • le (annotated_types.SupportsLe | None) – Less than or equal. If set, value must be less than or equal to this. Only applicable to numbers.

  • multiple_of (float | None) – Value must be a multiple of this. Only applicable to numbers.

  • min_length (int | None) – Minimum length for iterables.

  • max_length (int | None) – Maximum length for iterables.

  • pattern (str | typing.Pattern[str] | None) – Pattern for strings (a regular expression).

  • allow_inf_nan (bool | None) – Allow inf, -inf, nan. Only applicable to numbers.

  • max_digits (int | None) – Maximum number of allow digits for strings.

  • decimal_places (int | None) – Maximum number of decimal places allowed for numbers.

  • union_mode (Literal[‘smart’, ‘left_to_right’]) – The strategy to apply when validating a union. Can be smart (the default), or left_to_right. See [Union Mode](../concepts/unions.md#union-modes) for details.

  • fail_fast (bool | None) – If True, validation will stop on the first error. If False, all validation errors will be collected. This option can be applied only to iterable types (list, tuple, set, and frozenset).

  • extra (Unpack[_EmptyKwargs]) –

    (Deprecated) Extra fields that will be included in the JSON schema.

    !!! warning Deprecated

    The extra kwargs is deprecated. Use json_schema_extra instead.

Return type:

Any

Returns:

A new [FieldInfo][pydantic.fields.FieldInfo]. The return annotation is Any so Field can be used on

type-annotated fields without causing a type error.

class fal.toolkit.Image(**data)

Bases: File

Represents an image file.

classmethod from_bytes(data, format, size=None, file_name=None, repository='fal_v3', fallback_repository=['cdn', 'fal'], request=None)
Return type:

Image

classmethod from_pil(pil_image, format=None, file_name=None, repository='fal_v3', fallback_repository=['cdn', 'fal'], request=None)
Return type:

Image

height: Optional[int]
model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'ui': {'field': 'image'}}}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

to_pil(mode='RGB')
Return type:

Image

width: Optional[int]
fal.toolkit.ImageField(default=PydanticUndefined, *, default_factory=PydanticUndefined, alias=PydanticUndefined, alias_priority=PydanticUndefined, validation_alias=PydanticUndefined, serialization_alias=PydanticUndefined, title=PydanticUndefined, field_title_generator=PydanticUndefined, description=PydanticUndefined, examples=PydanticUndefined, exclude=PydanticUndefined, discriminator=PydanticUndefined, deprecated=PydanticUndefined, json_schema_extra=PydanticUndefined, frozen=PydanticUndefined, validate_default=PydanticUndefined, repr=PydanticUndefined, init=PydanticUndefined, init_var=PydanticUndefined, kw_only=PydanticUndefined, pattern=PydanticUndefined, strict=PydanticUndefined, coerce_numbers_to_str=PydanticUndefined, gt=PydanticUndefined, ge=PydanticUndefined, lt=PydanticUndefined, le=PydanticUndefined, multiple_of=PydanticUndefined, allow_inf_nan=PydanticUndefined, max_digits=PydanticUndefined, decimal_places=PydanticUndefined, min_length=PydanticUndefined, max_length=PydanticUndefined, union_mode=PydanticUndefined, fail_fast=PydanticUndefined, **extra)

Usage docs: https://docs.pydantic.dev/2.10/concepts/fields

Create a field for objects that can be configured.

Used to provide extra information about a field, either for the model schema or complex validation. Some arguments apply only to number fields (int, float, Decimal) and some apply only to str.

Note

  • Any _Unset objects will be replaced by the corresponding value defined in the _DefaultValues dictionary. If a key for the _Unset object is not found in the _DefaultValues dictionary, it will default to None

Parameters:

  • default (Any) – Default value if the field is not set.

  • default_factory (Callable[[], Any] | Callable[[dict[str, Any]], Any] | None) – A callable to generate the default value. The callable can either take 0 arguments (in which case it is called as is) or a single argument containing the already validated data.

  • alias (str | None) – The name to use for the attribute when validating or serializing by alias. This is often used for things like converting between snake and camel case.

  • alias_priority (int | None) – Priority of the alias. This affects whether an alias generator is used.

  • validation_alias (str | AliasPath | AliasChoices | None) – Like alias, but only affects validation, not serialization.

  • serialization_alias (str | None) – Like alias, but only affects serialization, not validation.

  • title (str | None) – Human-readable title.

  • field_title_generator (Callable[[str, FieldInfo], str] | None) – A callable that takes a field name and returns title for it.

  • description (str | None) – Human-readable description.

  • examples (list[Any] | None) – Example values for this field.

  • exclude (bool | None) – Whether to exclude the field from the model serialization.

  • discriminator (str | types.Discriminator | None) – Field name or Discriminator for discriminating the type in a tagged union.

  • deprecated (Deprecated | str | bool | None) – A deprecation message, an instance of warnings.deprecated or the typing_extensions.deprecated backport, or a boolean. If True, a default deprecation message will be emitted when accessing the field.

  • json_schema_extra (JsonDict | Callable[[JsonDict], None] | None) – A dict or callable to provide extra JSON schema properties.

  • frozen (bool | None) – Whether the field is frozen. If true, attempts to change the value on an instance will raise an error.

  • validate_default (bool | None) – If True, apply validation to the default value every time you create an instance. Otherwise, for performance reasons, the default value of the field is trusted and not validated.

  • repr (bool) – A boolean indicating whether to include the field in the __repr__ output.

  • init (bool | None) – Whether the field should be included in the constructor of the dataclass. (Only applies to dataclasses.)

  • init_var (bool | None) – Whether the field should _only_ be included in the constructor of the dataclass. (Only applies to dataclasses.)

  • kw_only (bool | None) – Whether the field should be a keyword-only argument in the constructor of the dataclass. (Only applies to dataclasses.)

  • coerce_numbers_to_str (bool | None) – Whether to enable coercion of any Number type to str (not applicable in strict mode).

  • strict (bool | None) – If True, strict validation is applied to the field. See [Strict Mode](../concepts/strict_mode.md) for details.

  • gt (annotated_types.SupportsGt | None) – Greater than. If set, value must be greater than this. Only applicable to numbers.

  • ge (annotated_types.SupportsGe | None) – Greater than or equal. If set, value must be greater than or equal to this. Only applicable to numbers.

  • lt (annotated_types.SupportsLt | None) – Less than. If set, value must be less than this. Only applicable to numbers.

  • le (annotated_types.SupportsLe | None) – Less than or equal. If set, value must be less than or equal to this. Only applicable to numbers.

  • multiple_of (float | None) – Value must be a multiple of this. Only applicable to numbers.

  • min_length (int | None) – Minimum length for iterables.

  • max_length (int | None) – Maximum length for iterables.

  • pattern (str | typing.Pattern[str] | None) – Pattern for strings (a regular expression).

  • allow_inf_nan (bool | None) – Allow inf, -inf, nan. Only applicable to numbers.

  • max_digits (int | None) – Maximum number of allow digits for strings.

  • decimal_places (int | None) – Maximum number of decimal places allowed for numbers.

  • union_mode (Literal[‘smart’, ‘left_to_right’]) – The strategy to apply when validating a union. Can be smart (the default), or left_to_right. See [Union Mode](../concepts/unions.md#union-modes) for details.

  • fail_fast (bool | None) – If True, validation will stop on the first error. If False, all validation errors will be collected. This option can be applied only to iterable types (list, tuple, set, and frozenset).

  • extra (Unpack[_EmptyKwargs]) –

    (Deprecated) Extra fields that will be included in the JSON schema.

    !!! warning Deprecated

    The extra kwargs is deprecated. Use json_schema_extra instead.

Return type:

Any

Returns:

A new [FieldInfo][pydantic.fields.FieldInfo]. The return annotation is Any so Field can be used on

type-annotated fields without causing a type error.

class fal.toolkit.Video(**data)

Bases: File

model_config: ClassVar[ConfigDict] = {'json_schema_extra': {'ui': {'field': 'video'}}}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

fal.toolkit.VideoField(default=PydanticUndefined, *, default_factory=PydanticUndefined, alias=PydanticUndefined, alias_priority=PydanticUndefined, validation_alias=PydanticUndefined, serialization_alias=PydanticUndefined, title=PydanticUndefined, field_title_generator=PydanticUndefined, description=PydanticUndefined, examples=PydanticUndefined, exclude=PydanticUndefined, discriminator=PydanticUndefined, deprecated=PydanticUndefined, json_schema_extra=PydanticUndefined, frozen=PydanticUndefined, validate_default=PydanticUndefined, repr=PydanticUndefined, init=PydanticUndefined, init_var=PydanticUndefined, kw_only=PydanticUndefined, pattern=PydanticUndefined, strict=PydanticUndefined, coerce_numbers_to_str=PydanticUndefined, gt=PydanticUndefined, ge=PydanticUndefined, lt=PydanticUndefined, le=PydanticUndefined, multiple_of=PydanticUndefined, allow_inf_nan=PydanticUndefined, max_digits=PydanticUndefined, decimal_places=PydanticUndefined, min_length=PydanticUndefined, max_length=PydanticUndefined, union_mode=PydanticUndefined, fail_fast=PydanticUndefined, **extra)

Usage docs: https://docs.pydantic.dev/2.10/concepts/fields

Create a field for objects that can be configured.

Used to provide extra information about a field, either for the model schema or complex validation. Some arguments apply only to number fields (int, float, Decimal) and some apply only to str.

Note

  • Any _Unset objects will be replaced by the corresponding value defined in the _DefaultValues dictionary. If a key for the _Unset object is not found in the _DefaultValues dictionary, it will default to None

Parameters:

  • default (Any) – Default value if the field is not set.

  • default_factory (Callable[[], Any] | Callable[[dict[str, Any]], Any] | None) – A callable to generate the default value. The callable can either take 0 arguments (in which case it is called as is) or a single argument containing the already validated data.

  • alias (str | None) – The name to use for the attribute when validating or serializing by alias. This is often used for things like converting between snake and camel case.

  • alias_priority (int | None) – Priority of the alias. This affects whether an alias generator is used.

  • validation_alias (str | AliasPath | AliasChoices | None) – Like alias, but only affects validation, not serialization.

  • serialization_alias (str | None) – Like alias, but only affects serialization, not validation.

  • title (str | None) – Human-readable title.

  • field_title_generator (Callable[[str, FieldInfo], str] | None) – A callable that takes a field name and returns title for it.

  • description (str | None) – Human-readable description.

  • examples (list[Any] | None) – Example values for this field.

  • exclude (bool | None) – Whether to exclude the field from the model serialization.

  • discriminator (str | types.Discriminator | None) – Field name or Discriminator for discriminating the type in a tagged union.

  • deprecated (Deprecated | str | bool | None) – A deprecation message, an instance of warnings.deprecated or the typing_extensions.deprecated backport, or a boolean. If True, a default deprecation message will be emitted when accessing the field.

  • json_schema_extra (JsonDict | Callable[[JsonDict], None] | None) – A dict or callable to provide extra JSON schema properties.

  • frozen (bool | None) – Whether the field is frozen. If true, attempts to change the value on an instance will raise an error.

  • validate_default (bool | None) – If True, apply validation to the default value every time you create an instance. Otherwise, for performance reasons, the default value of the field is trusted and not validated.

  • repr (bool) – A boolean indicating whether to include the field in the __repr__ output.

  • init (bool | None) – Whether the field should be included in the constructor of the dataclass. (Only applies to dataclasses.)

  • init_var (bool | None) – Whether the field should _only_ be included in the constructor of the dataclass. (Only applies to dataclasses.)

  • kw_only (bool | None) – Whether the field should be a keyword-only argument in the constructor of the dataclass. (Only applies to dataclasses.)

  • coerce_numbers_to_str (bool | None) – Whether to enable coercion of any Number type to str (not applicable in strict mode).

  • strict (bool | None) – If True, strict validation is applied to the field. See [Strict Mode](../concepts/strict_mode.md) for details.

  • gt (annotated_types.SupportsGt | None) – Greater than. If set, value must be greater than this. Only applicable to numbers.

  • ge (annotated_types.SupportsGe | None) – Greater than or equal. If set, value must be greater than or equal to this. Only applicable to numbers.

  • lt (annotated_types.SupportsLt | None) – Less than. If set, value must be less than this. Only applicable to numbers.

  • le (annotated_types.SupportsLe | None) – Less than or equal. If set, value must be less than or equal to this. Only applicable to numbers.

  • multiple_of (float | None) – Value must be a multiple of this. Only applicable to numbers.

  • min_length (int | None) – Minimum length for iterables.

  • max_length (int | None) – Maximum length for iterables.

  • pattern (str | typing.Pattern[str] | None) – Pattern for strings (a regular expression).

  • allow_inf_nan (bool | None) – Allow inf, -inf, nan. Only applicable to numbers.

  • max_digits (int | None) – Maximum number of allow digits for strings.

  • decimal_places (int | None) – Maximum number of decimal places allowed for numbers.

  • union_mode (Literal[‘smart’, ‘left_to_right’]) – The strategy to apply when validating a union. Can be smart (the default), or left_to_right. See [Union Mode](../concepts/unions.md#union-modes) for details.

  • fail_fast (bool | None) – If True, validation will stop on the first error. If False, all validation errors will be collected. This option can be applied only to iterable types (list, tuple, set, and frozenset).

  • extra (Unpack[_EmptyKwargs]) –

    (Deprecated) Extra fields that will be included in the JSON schema.

    !!! warning Deprecated

    The extra kwargs is deprecated. Use json_schema_extra instead.

Return type:

Any

Returns:

A new [FieldInfo][pydantic.fields.FieldInfo]. The return annotation is Any so Field can be used on

type-annotated fields without causing a type error.

fal.toolkit.clone_repository(https_url, *, commit_hash=None, target_dir=None, repo_name=None, force=False, include_to_path=False)

Clones a Git repository from the specified HTTPS URL into a local directory.

This function clones a Git repository from the specified HTTPS URL into a local directory. It can also checkout a specific commit if the commit_hash is provided.

If a custom target_dir or repo_name is not specified, a predefined directory is used for the target directory, and the repository name is determined from the URL.

Parameters:

  • https_url (str) – The HTTPS URL of the Git repository to be cloned.

  • commit_hash (str | None) – The commit hash to checkout after cloning.

  • target_dir (str | Path | None) – The directory where the repository will be saved. If not provided, a predefined directory is used.

  • repo_name (str | None) – The name to be used for the cloned repository directory. If not provided, the repository’s name from the URL is used.

  • force (bool) – If True, the repository is cloned even if it already exists locally and its commit hash matches the provided commit hash. Defaults to False.

  • include_to_path (bool) – If True, the cloned repository is added to the sys.path. Defaults to False.

Return type:

Path

Returns:

A Path object representing the full path to the cloned Git repository.

fal.toolkit.download_file(url, target_dir, *, force=False, request_headers=None, filesize_limit=None)

Downloads a file from the specified URL to the target directory.

The function downloads the file from the given URL and saves it in the specified target directory, provided it is below the given filesize limit.

It also checks whether the local file already exists and whether its content length matches the expected content length from the remote file. If the local file already exists and its content length matches the expected content length from the remote file, the existing file is returned without re-downloading it.

If the file needs to be downloaded or if an existing file’s content length does not match the expected length, the function proceeds to download and save the file. It ensures that the target directory exists and handles any errors that may occur during the download process, raising a DownloadError if necessary.

Parameters:

  • url (str) – The URL of the file to be downloaded.

  • target_dir (str | Path) – The directory where the downloaded file will be saved. If it’s not an absolute path, it’s treated as a relative directory to “/data”.

  • force (bool) – If True, the file is downloaded even if it already exists locally and its content length matches the expected content length from the remote file. Defaults to False.

  • request_headers (dict[str, str] | None) – A dictionary containing additional headers to be included in the HTTP request. Defaults to None.

  • filesize_limit (int | None) – An integer specifying the maximum downloadable size, in megabytes. Defaults to None.

Return type:

Path

Returns:

A Path object representing the full path to the downloaded file.

Raises:

  • ValueError – If the provided file_name contains a forward slash (‘/’).

  • DownloadError – If an error occurs during the download process.

fal.toolkit.download_model_weights(url, force=False, request_headers=None)

Downloads model weights from the specified URL and saves them to a predefined directory.

This function is specifically designed for downloading model weights and stores them in a predefined directory.

It calls the download_file function with the provided URL and the target directory set to a pre-defined location for model weights. The downloaded model weights are saved in this directory, and the function returns the full path to the downloaded weights file.

Parameters:

  • url (str) – The URL from which the model weights will be downloaded.

  • force (bool) – If True, the model weights are downloaded even if they already exist locally and their content length matches the expected content length from the remote file. Defaults to False.

  • request_headers (dict[str, str] | None) – A dictionary containing additional headers to be included in the HTTP request. Defaults to None.

Return type:

Path

Returns:

A Path object representing the full path to the downloaded model weights.

fal.toolkit.get_image_size(source)
Return type:

ImageSize

fal.toolkit.optimize(module, *, optimization_config=None)

Optimize the given torch module with dynamic compilation and quantization techniques. Only applicable under fal’s cloud environment.

Warning: This function is experimental and may not work as expected.

Return type:

torch.nn.Module