# Cloud Filters

> Learn how apps list, download, cache, apply, and remove protected effect packages without uploading camera frames.

> For AI agents: the complete documentation index is at https://nosmai.com/llms/effects.txt

Product: Nosmai Effects
Group: core-concepts
Source: https://nosmai.com/docs/effects/concepts/cloud-filters/

## Lifecycle

![Cloud Filter catalog, download, apply, and cache lifecycle](/images/docs/cloud-filter-lifecycle-v1.svg)

Only the catalog metadata and selected filter package use the network. Camera
frames stay on the device.

## Catalog categories

The supported request categories cover effects, regular filters, backgrounds,
beauty effects, and games. Use the typed enum supplied by Flutter or the exact
request value documented by the native platform. Do not copy a catalog
category into a package manifest.

Use the downloadable cloud identifier for download and removal. A catalog may
also expose an internal record ID, which is not always interchangeable.

## Download and cache behaviour

- Treat the download completion result as authoritative.
- Apply only the local path returned by the SDK.
- Deduplicate repeated taps by cloud identifier.
- Keep one in-flight download per item.
- Reuse an already downloaded package instead of downloading it again.
- Remove a cached package only after an explicit product decision.
- Treat cache presence as a runtime check, not a permanent promise. The SDK
  does not publish one cross-platform cache TTL, and the operating system or a
  user storage action can reclaim cached files.

Progress callbacks are useful for UI, but completion decides whether the file
is usable. If the screen closes during a download, ignore the stale UI update
without deleting a successful cached package.

## Offline use

An already downloaded package can be applied from its local path without
fetching it again. A package that has never been downloaded is not available
offline. License policy still applies, and catalog refresh naturally requires
network access.

If cache state reports that the package is missing, download it again and use
the new completion path. Never persist a returned filesystem path as permanent
application data or classify every existing `.nosmai` path as a bundled local
asset; Cloud Filters remain cloud-managed entries even after they are cached.

## Product and storage considerations

Do not prefetch a large catalog without a product reason. Downloads consume
network, storage, and any download allowance attached to the project. Show
progress, provide retry, and preserve the previously active effect when a new
download fails.

Cache location and operating-system cleanup rules differ by platform. Store
the cloud identifier in application state, not a guessed filesystem path.

## Next steps

- [Download a Cloud Filter in Flutter](/docs/effects/guides/filters/download-a-cloud-filter/flutter/)
- [Download a Cloud Filter in Android](/docs/effects/guides/filters/download-a-cloud-filter/android/)
- [Choose bundled or cloud delivery](/docs/effects/concepts/filters-and-effects/)
- [Troubleshoot downloads](/docs/effects/troubleshooting/)

## References

- [Platform support](/docs/effects/platform-support/)
- [Nosmai Effects](https://nosmai.com/effects/)