Skip to content

V- Modal AI: Visual Video / Image Search - Flutter Video SDK

5.3 KB
Raw Blame

SDK guide

Begin with Choose authentication. Direct runtime keys keep the setup below; backend-scoped credentials use VModal.connectWithBackend and its typed callback. Backend authentication describes strict envelopes, server grants, renewal and account transitions.

For account-based apps, start with Component patterns: activate a verified app-user session, discover its allowed library, and inject the resulting UserScope into a feature controller. The examples below use the compatible tenant-scoped API, whose host owns isolation and lifecycle. See the documentation index for the recommended reading paths.

The generated class and method reference is published at https://v-modal.github.io/vmodal_sdk_flutter/ and is built from the public Dart declarations in lib/vmodal_sdk_flutter.dart. The monorepo release pipeline builds the Pages artifact in doc/; that generated tree is not part of the standalone package. Backend hosts, wire paths, and implementation bodies are intentionally excluded; mobile applications should use the typed resources described there.

Use VModal.configure with a developer-owned project ID and an app-owned ApiKeyProvider, then create immutable collection/stream scopes:

final keys = MutableApiKeyProvider(runtimeApiKey);
final project = VModal.configure(
  projectId: 'food_app',
  apiKeyProvider: keys,
);
final scope = project.scope(
  collectionName: 'user_123',
  streamName: 'favorites',
);

final upload = scope.upload(UploadSource.fromFile(video));
final result = await scope.search('birthday dinner');

await project.close();

Configuration and scope creation perform no network I/O. Every Future-based scoped operation accepts CancellationToken?; uploads retain UploadTask progress and cancellation. VModalProject.close() owns and idempotently closes the low-level client.

Names are trimmed, required, limited to ASCII letters, digits, and underscore, and limited to 80 characters. projectId and collectionName cannot contain __. The SDK internally maps project plus collection to one backend collection and maps stream directly; callers never construct or parse that value.

listCollections returns logical names for the exact project prefix in backend order, removes duplicates after their first occurrence, and excludes other projects. A malformed name under the current project is a MalformedResponse.

Common layouts include one global collection, one user_123 collection per end user, several streams in one user collection, a product_catalog collection, and separate VModalProject values for separate apps. Account switching creates fresh project/client state; API-key rotation alone does not change identity or content scope.

VmodalClient remains the advanced compatibility API for auth, image lookup, usage, and direct resource access. VModal.fromClient accepts an existing fully configured client and transfers close ownership to the returned project. All ordinary operations are asynchronous. Gateway mode sends only Authorization: Bearer <credential> as caller identity. Scoped backend tokens use the same header and data paths; they require the backend connection and server capability described in the authentication guides.

Resources are grouped under auth, searches, collections, indexes, admin, r2, and images. Request models preserve server snake_case during serialization and response classes retain the raw JSON map for extension fields.

Scoped migration replaces low-level groupName or collectionName plus streamName arguments with one immutable VModalScope. Use scoped option classes for operation settings; they deliberately contain no organization override fields.

Responses are consumed through one bounded stream reader: JSON/text is limited to 8 MiB, errors to 1 MiB, and binary results to 64 MiB. Only GET and HEAD retry recognized transport failures or 500/502/503/504. Mutating requests are sent once; reconcile server state before explicitly retrying an ambiguous mutation.

Uploads use reopenable UploadSource streams. Signed single upload is always the default. UploadTask exposes a result future, broadcast progress stream, and per-task cancellation. Multipart requires explicit opt-in and is experimental.

CCTV signed uploads use VideoUploadOptions(videoFilename, metadataText, metadataTags, startDatetimeUser, reProcess). The timestamp input must contain Z or an explicit UTC offset and is sent unchanged; the backend owns normalization and the canonical startTsUnixUserMs response. Tags remain ordered repeated wire values, including after multipart resume, bulk upload, or transcoding. A timestamp with no public name derives the original source filename.

CollectionsResource.uploadFile accepts the same CCTV fields for direct multipart compatibility. Use SearchRequest.queryMetadataText or ScopedSearchOptions.queryMetadataText for the backend string metadata contract. In vid_file mode, startDate and endDate are a required pair, with inclusive start and exclusive end; datetime values require Z or an explicit UTC offset and are never converted by the SDK.

Flutter Web, login UI, key persistence, file picking, widget state management, and background scheduling are outside the package. The first release supports Flutter applications on Android and iOS.