cloudinary library

A complete Cloudinary SDK for Dart and Flutter.

Covers the Upload, Admin and Search APIs plus signed delivery URL construction, with no Flutter dependency, so the same package serves a Flutter app, a Dart backend and a CLI.

Create a client, then reach an API family through Cloudinary.upload, Cloudinary.admin, Cloudinary.search or Cloudinary.url:

import 'package:cloudinary/cloudinary.dart';

Future<void> main() async {
  final cloudinary = Cloudinary.signed(
    cloudName: 'your-cloud',
    apiKey: 'your-key',
    apiSecret: 'your-secret',
  );

  final result = await cloudinary.upload.upload(
    file: CloudinaryFileSource.path('photo.jpg'),
    folder: 'trips',
  );
  print(result.secureUrl);

  cloudinary.close();
}

Calls return typed models and throw a CloudinaryException subtype on failure. Every model also exposes raw, the complete decoded response, so a field this package does not model is still reachable.

In a Flutter or web app an API secret must not be present at all. Use Cloudinary.unsigned with an upload preset, or supply a SignatureProvider that signs on your own server.

Classes

AccountApi: Environment-level Admin endpoints: reachability, usage and configuration.
AdminAck: A generic acknowledgement, used by endpoints that answer with a message.
AdminApi: The Cloudinary Admin API, grouped by resource family.
ArchiveResult: A generated archive, either created in storage or returned as a URL.
AssetResource: A stored asset as the Admin API describes it.
AuthToken: A signed __cld_token__ granting time-limited access to delivery URLs.
Cloudinary: Entry point for the Cloudinary API.
CloudinaryBytesSource: An upload sourced from an in-memory buffer.
CloudinaryConfig: Credentials and signing options for a Cloudinary product environment.
CloudinaryFileSource: Where the bytes of an upload come from.
CloudinaryModel: Base for every parsed Cloudinary response.
CloudinaryPathSource: An upload sourced from a local file path.
CloudinaryTransport: Sends requests to Cloudinary and turns failures into typed exceptions.
CloudinaryUrlBuilder: A chainable delivery URL under construction.
CloudinaryUrlSource: An upload Cloudinary fetches from a remote URL itself.
ConfigResult: Environment configuration, as the Admin API reports it.
DeleteResourcesResult: The outcome of a delete call, per public ID.
DestroyResult: The outcome of a destroy or delete-by-token call.
ExplodeResult: The status of an asynchronous explode job.
Folder: A folder in the media library.
FolderListResult: A page of folders.
FoldersApi: Admin endpoints for managing media library folders.
FolderSearchResult: A page of folder search results.
MetadataField: A structured metadata field definition.
MetadataFieldsApi: Admin endpoints for structured metadata field definitions.
MetadataRule: A dependency rule between structured metadata fields.
MetadataRulesApi: Admin endpoints for structured metadata rules.
PingResult: Reachability check result.
PublicIdsResult: A response listing the public IDs an operation touched.
RemoteSignature: A signature produced by a SignatureProvider.
ResourceListResult: A page of assets, with a cursor for the next page.
ResourcesApi: Admin endpoints for listing, updating and deleting assets.
RetryPolicy: Controls retry behaviour for transient Cloudinary failures.
SearchApi: The Cloudinary Search API.
SearchQuery: A chainable Cloudinary search query.
SearchResult: A page of search results.
SignatureProvider: Supplies request signatures from somewhere other than this process.
SpriteResult: A generated sprite sheet or multi-frame asset.
StreamingProfile: An adaptive streaming profile.
StreamingProfileListResult: A page of streaming profiles.
StreamingProfilesApi: Admin endpoints for adaptive streaming profiles.
TagListResult: A page of tags.
TagsApi: Admin endpoints for listing tags.
TextResult: A text image generated from a string.
Transformation: One transformation component set, serialized as w_100,h_150,c_fill.
TransformationChain: Several transformations applied in order, joined with /.
TransformationInfo: A named, stored transformation.
TransformationListResult: A page of stored transformations.
TransformationsApi: Admin endpoints for stored transformations.
UploadApi: The Cloudinary Upload API.
UploadMapping: A mapping from a folder to a remote origin.
UploadMappingListResult: A page of upload mappings.
UploadMappingsApi: Admin endpoints for upload mappings.
UploadPreset: An upload preset: a saved set of upload options.
UploadPresetListResult: A page of upload presets.
UploadPresetsApi: Admin endpoints for upload presets.
UploadResult: The result of an upload or an explicit re-processing call.
UrlApi: Builds delivery URLs.
UrlConfig: Options controlling how delivery URLs are built.
UsageReport: Storage, bandwidth and transformation usage for the environment.

Enums

ApiVersion: Which Cloudinary API version a request targets.
CloudinaryDeliveryType: How an asset is delivered and how Cloudinary obtained it.
CloudinaryResourceType: The kind of asset an operation acts on.
CloudinarySignatureAlgorithm: Hash algorithms Cloudinary accepts for request and URL signatures.
CropMode: How an asset is resized and cropped.
DeliveryFormat: Delivery format.
Effect: Named visual effects that need no argument.
Flag: Transformation flags, which alter how other parameters behave.
Gravity: Which part of an asset to keep when cropping.
MetadataFieldType: The type of a structured metadata field.
Quality: Output quality.
SearchTarget: Which collection a search runs against.
SortDirection: Sort direction for a search ordering.

Constants

unsignedUploadParams → const Set<String>: Parameters Cloudinary excludes from the signature of an upload request.

Functions

cloudinaryTimestamp() → int: Returns the current UNIX time in seconds, which is what Cloudinary expects.
encodeContext(Map<String, String> context) → String: Encodes contextual metadata as Cloudinary's key=value|key=value format.
encodeMetadata(Map<String, String> metadata) → String: Encodes structured metadata values.
escapeTokenComponent(String value) → String: Percent-escapes value the way Cloudinary's token signer does, using lowercase hex escapes.
signRequest(Map<String, dynamic> params, String apiSecret, {int version = 2, CloudinarySignatureAlgorithm algorithm = CloudinarySignatureAlgorithm.sha1}) → String: Signs params with apiSecret, returning a lowercase hex digest.
splitFolderPath(String path) → List<String>: Splits a folder path into URL segments.
stringToSign(Map<String, dynamic> params, {int version = 2}) → String: Builds the canonical string Cloudinary signs.
stripUnsignedParams(Map<String, dynamic> params) → Map<String, dynamic>: Returns a copy of params with the parameters Cloudinary never signs removed.
verifyNotificationSignature({required String body, required int timestamp, required String signature, required String apiSecret, Duration validFor = const Duration(seconds: 7200), CloudinarySignatureAlgorithm algorithm = CloudinarySignatureAlgorithm.sha1}) → bool: Verifies the signature Cloudinary sends with a webhook notification.

Typedefs

CloudinaryProgressCallback = void Function(int sent, int total): Reports upload progress as bytes are sent.

Exceptions / Errors

CloudinaryApiException: Thrown when Cloudinary answers with a non-2xx status.
CloudinaryAuthException: Thrown when Cloudinary rejects the credentials.
CloudinaryConfigException: Thrown when the client is configured wrongly, before any request is sent.
CloudinaryException: Base type for every error this package throws.
CloudinaryNotFoundException: Thrown when the requested asset or resource does not exist.
CloudinaryRateLimitException: Thrown when Cloudinary rate-limits the request.
CloudinarySignatureException: Thrown when generating or verifying a signature fails.
CloudinaryTransportException: Thrown when the request never reached Cloudinary.

cloudinary library

Classes

Enums

Constants

Functions

Typedefs

Exceptions / Errors

cloudinary package

cloudinary library