# Download a Cloud Filter in Flutter

> List typed cloud items from Dart, download a selected cloud identifier, and apply the returned local package path.

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

Product: Nosmai Effects
Group: guide
Source: https://nosmai.com/docs/effects/guides/filters/download-a-cloud-filter/flutter/

## Prerequisites

- A working [Flutter quickstart](/docs/effects/quickstart/flutter/)
- Cloud Filters enabled for the project

## Request the catalog

```dart
final filters = await NosmaiFlutter.instance.getCloudFilters(
  filterType: NosmaiCloudFilterType.effects,
  page: 1,
  limit: 20,
);
```

Other typed values include `filter`, `background`, `beautyEffect`, and `games`.

## Download and apply

```dart
final filter = filters.first;
final result = await NosmaiFlutter.instance.downloadCloudFilter(
  filter.cloudIdentifier,
);
final path = result['path'] as String?;

if (path == null || path.isEmpty) {
  throw StateError('Cloud Filter download returned no path');
}

await NosmaiFlutter.instance.applyEffect(path);
```

Remove a cached item only after an explicit user or product action:

```dart
await NosmaiFlutter.instance.removeCloudFilter(
  filter.cloudIdentifier,
);
```

## Handle cache eviction

Do not persist `path` as a permanent asset path. The cache has no documented
cross-platform TTL and the operating system can reclaim it. Query the SDK's
downloaded state when the item is selected; if it is missing, call
`downloadCloudFilter` again and use the new returned path.

## Verify it worked

Close and reopen the filter UI, then apply the cached item with network disabled.

## Common errors

| Symptom | Fix |
| --- | --- |
| Catalog is empty | Check cloud capability, type, and native key configuration |
| Returned path is null | Treat the download as failed and show Retry |
| Two downloads start | Store one Future per `cloudIdentifier` |

## Next steps

- [Understand Cloud Filters](/docs/effects/concepts/cloud-filters/)
- [Bundle a filter in Flutter](/docs/effects/guides/filters/bundle-an-asset-store-filter/flutter/)

## References

- [Flutter platform guide](/docs/effects/platforms/flutter/)
- [Flutter package](https://pub.dev/packages/nosmai_effects_sdk)