uploadcare_client

Description:

uploadcare client

Uploadcare client for Dart/Flutter #
Uploadcare is a complete file handling platform that helps you ship products faster and focus on your business goals, not files. With Uploadcare, you can build infrastructure, optimize content, conversions, load times, traffic, and user experience. Read more...
A dart/flutter library for working with Uploadcare REST API. File uploads, media processing, and adaptive delivery for web and mobile.
Features #

Upload

Base
Multipart
From url
Auto
In isolate
Progress tracking
Cancellable
Signed


Image and file transformations

Full list of image/file processing operations


Files

Get file info
Get list of files
Remove files
Store files
Metadata
Create file copies


Groups
Video processing
Document conversion
Addons

Object recognition
Malware protection
Background removal


Webhooks
Project
FAQ

Note about uploadcare_flutter package #
The uploadcare_flutter package introduced a few extensions for the base package (Dimensions, Offsets, FaceRect, FacesEntityExtension), UploadcareImageProvider. If you don't need these features, you can use uploadcare_client directly
Installation #
Dart:
dart pub add uploadcare_client # or uploadcare_flutter
copied to clipboard
Flutter:
flutter pub add uploadcare_client # or uploadcare_flutter
copied to clipboard
Create an client
final client = UploadcareClient.withSimpleAuth(
publicKey: 'puplic_key',
apiVersion: 'v0.7',
);
copied to clipboard
UploadcareClient has following API sections
final ApiUpload upload;
final ApiFiles files;
final ApiGroups groups;
final ApiDocumentConverting documentConverting;
final ApiVideoEncoding videoEncoding;
final ApiAddons addons;
final ApiWebhooks webhooks;
final ApiProject project;
copied to clipboard
You can use each API section separately, for example:
final options = ClientOptions(
authorizationScheme: AuthSchemeRegular(
apiVersion: 'v0.7',
publicKey: 'public_key',
privateKey: 'private_key',
)
);

final upload = ApiUpload(options: options);
final fileId = await upload.base(UCFile(File('...some/file')));
// ...etc.
copied to clipboard
Upload #
Base upload
/// For small files
final fileId = await client.upload.base(UCFile(File('path/to/small_file')));
copied to clipboard
Chunked upload
/// For large files
/// You can manage the number of concurrent requests by setting `ClientOptions.maxConcurrentChunkRequests` field.
final fileId = await client.upload.multipart(UCFile(File('path/to/large_file')));
copied to clipboard
From url
final fileId = await client.upload.fromUrl('https://files.st/path_to_file');
copied to clipboard
Auto
/// Auto method accepts small/large/url files as a parameter and calls the necessary method for upload
final fileId1 = await client.upload.auto(UCFile(File('path/to/small_file')));
final fileId2 = await client.upload.auto(UCFile(File('path/to/large_file')));
final fileId3 = await client.upload.auto('https://files.st/path_to_file');
copied to clipboard
Isolate
/// Also files can be uploaded in dart `isolate`
/// You can manage the number of isolates by setting `ClientOptions.maxIsolatePoolSize` field.
///
/// NOTE: Doesn't work in web environment
final fileId = await client.upload.auto(UCFile(File('path/to/file')), runInIsolate: true);
copied to clipboard
Progress tracking
/// Also you can track upload progress, all methods accept `onProgress` callback for this
final fileId = await client.upload.(auto|base|multipart|fromUrl)(UCFile(File('path/to/file')), onProgress: (progress) => print(progress));
copied to clipboard
Cancellable
/// All upload processes can be canceled with `CancelToken`
final cancelToken = CancelToken();

Timer(Duration(seconds: 1), cancelToken.cancel);

try {
final fileId = await client.upload.auto(UCFile(File('/some/file')), cancelToken: cancelToken);
} on CancelUploadException catch (e) {
// cancelled
}

copied to clipboard
Signed upload
Official documentation
/// For signed upload you should provide the project's private key
final client = UploadcareClient(options: ClientOptions(
authorizationScheme: AuthSchemeRegular(
publicKey: 'public_key',
privateKey: 'private_key',
apiVersion: 'v0.7',
),
useSignedUploads: true,

/// Optionally you can customize signature lifetime for signed uploads via the `signedUploadsSignatureLifetime` property (default: 30 minutes)
));

/// Now, all your uploads will be signed
await client.uploads.(base|multipart|fromUrl|auto)(UCFile(File('path/to/file')));
copied to clipboard
Image and file transformations #
Official documentation
final cropedCdnImage = CdnImage('<image-uuid>')..transform(CropTransformation(ascpectRatio: AspectRatio(9, 16)));

/// Use the following field for the croped image
/// cropedCdnImage.url;

final cropedAndInlined = CdnImage('<image-uuid>')..transformAll([
CropTransformation(ascpectRatio: AspectRatio(9, 16)),
InlineTransformation(true);
]);

/// Use the following field to download the croped image
/// cropedAndInlined.url
copied to clipboard
If you use uploadcare_flutter you can specify the provider for the Image widget
final image = Image(
image: UploadcareImageProvider(
'<image-uuid>',
transformations: [
ImageResizeTransformation(
const Dimensions.fromHeight(1000)),
],
),
copied to clipboard
Full list of image processing operations
Compression:



Operation
Type




Format
ImageFormatTransformation


Quality, SmartCompression
QualityTransformation


Progressive JPEG
ProgressiveTransformation


Meta information control
StripMetaTransformation



Resize, Crop, Rotate:



Operation
Type




Preview
PreviewTransformation


Resize, Smart resize
ImageResizeTransformation


Crop, Crop by ratio, Crop by objects
CropTransformation


Scale crop, Smart crop
ScaleCropTransformation


Border radius and circle crop
BorderRadiusTransformation


Set fill color
SetFillTransformation


Zoom objects
ZoomObjectTransformation


Automatic rotation, EXIF-based
AutoRotateTransformation


Manual rotation
RotateTransformation


Flip
FlipTransformation


Mirror
MirrorTransformation



Overlays and watermarks:



Operation
Type




Image overlay, Self overlay
OverlayTransformation


Text overlay
TextOverlayTransformation



Effects and enhancements:



Operation
Type




Color adjustment
Color(Brightness|Exposure|Gamma|Contrast|Sauration|Vibrance|Warmth)Transformation


Enhance
EnhanceTransformation


Grayscale
GrayscaleTransformation


Inverting
InvertTransformation


Conversion to sRGB
SrgbTransformation


ICC profile size threshold
MaxIccSizeTransformation


Photo filters
FilterTransformation


Blur
BlurTransformation


Blur region, Blur faces
BlurRegionTransformation


Unsharp masking
UnsharpMaskingTransformation


Sharpen
SharpTransformation



Rasterization:



Operation
Type




Rasterization
RasterizeTransformation



Gif to video:



Operation
Type




Gif to video
GifToVideoTransformation



final file = CdnFile('<gif-uuid>')
..transform(GifToVideoTransformation([
VideoFormatTransformation(VideoFormatTValue.Mp4),
QualityTransformation(QualityTValue.Best),
]));

/// Use `file.url` to get video link
copied to clipboard
Non-image specific operations:



Operation
Type




Get file info as JSON
JsonFileInfoTransformation


Get file info as application/javascript
JsonpFileInfoTransformation


Show or download
InlineTransformation


Change filename
ChangeFilenameTransformation



Face detection:
Official documentation
/// Detect faces for the image
final FacesEntity entity = await client.files.getFacesEntity('<image-uuid>');
copied to clipboard
Files #
Get file info
/// Get info about the file
final FileInfoEntity file = await client.files.file('<file-uuid>');

/// To get extended file data use `FilesIncludeFields include` field
final FileInfoEntity file = await client.files.file(
'<file-uuid>',
include: FilesIncludeFields.withAppData(), /// shortcut for `FilesIncludeFields(predefined: const [FilesIncludeFieldsValue.AppData])`
);
copied to clipboard
Get list of files
/// Get list of files with default params (offset 0, limit 100, ordered by upload time)
final ListEntity<FileInfoEntity> list = await client.files.list();
copied to clipboard
Remove files
/// Remove files by the list of ids
await client.files.remove(['<file-uuid>', '<file-uuid>']);
copied to clipboard
Store files
/// Store files by the list of ids
await client.files.store(['<file-uuid>', '<file-uuid>']);
copied to clipboard
Metadata
/// Retrieve all metadata values of the file
final Map<String, String> metadata = await client.files.getFileMetadata('<file-uuid>');

/// Retrieve the metadata value of the file for the specific metadata key
final String value = await client.files.getFileMetadataValue('<file-uuid>', '<metadata-key>');

/// Update the metadata value of the file for the specific metadata metadata-key
final String updatedValue = await client.files.updateFileMetadataValue('<file-uuid>', '<metadata-key>', '<new-value>');

/// Delete the metadata value of the file for the specific metadata key
await client.files.deleteFileMetadataValue('<file-uuid>', '<metadata-key>');
copied to clipboard
Create file copies
/// Copy original files or their modified versions to a default storage
final FileInfoEntity copiedFile = await client.files.copyToLocalStorage('<file-uuid>', metadata: {'<metadata-key>': '<metadata-value>'});

/// Copy original files or their modified versions to a custom storage
final String remoteFileUrl = await client.files.copyToRemoteStorage(file: '<file-uuid>', target: '<remote-storage>');
copied to clipboard
Groups #
/// Create a group of files
final GroupInfoEntity group = await client.groups.create({
/// Without transformation
'<image-uuid>': [],

/// With list of transformations
'<image-uuid>': [RotateTransformation(90)]
});

/// Retrieve group info
final GroupInfoEntity group = await client.groups.group('<group-uuid>');

/// Store all files in the group
await client.groups.storeFiles('<group-uuid>');

/// Retrieve list of groups
final ListEntity<GroupInfoEntity> list = await client.groups.list();

/// Delete the group by id
await client.groups.delete('<group-uuid>');
copied to clipboard
Download group as an archive
final group = CdnGroup('<group-uuid>')
..transform(ArchiveTransformation(ArchiveTValue.Tar, 'archive.tar'));

/// Use the following field for download the group as archive `group.url`
copied to clipboard
Video processing #
Official documentation
/// Create a task for processing uploaded video files
final ConvertEntity<VideoEncodingResultEntity> result = await client.videoEncoding.process({
'<video-file-uuid>': [
/// Cut video from 10 to 40 seconds
CutTransformation(
const Duration(seconds: 10),
length: const Duration(
seconds: 30,
),
)
],
'<video-file-uuid>': [
/// Change video resolution
VideoResizeTransformation(const Size(512, 384)),
/// Generate 10 thumbnails for the video
VideoThumbsGenerateTransformation(10),
],
});

/// Checks processing status for the task
final Stream<ConvertJobEntity<VideoEncodingResultEntity>> processingStream = client.videoEncoding.statusAsStream(
result.results.first.token,
checkInterval: const Duration(seconds: 2),
)..listen((ConvertJobEntity<VideoEncodingResultEntity> status) {
// do something
});
copied to clipboard
Document conversion #
Official documentation
/// Create a task for processing uploaded document files
final ConvertEntity<DocumentConvertingResultEntity> result = client.documentConverting.process({
'<document-file-uuid>': [
/// Convert document to pdf
DocumentFormatTransformation(DucumentOutFormatTValue.PDF),
],
'<document-file-uuid>': [
/// Converts the 10th page of the document
DocumentFormatTransformation(DucumentOutFormatTValue.PNG, page: 10),
],
});

/// Checks processing status for the task
final Stream<ConvertJobEntity<DocumentConvertingResultEntity>> processingStream = client.documentConverting.statusAsStream(
result.results.first.token,
checkInterval: const Duration(seconds: 2),
)..listen((ConvertJobEntity<DocumentConvertingResultEntity> status) {
// do something
});
copied to clipboard
Addons #
Object recognition
Official documentation
final taskId = await client.addons.executeAWSRekognition('<image-uuid>');

final result = await client.addons.checkAWSRekognitionExecutionStatus(taskId);

if (result.status == AddonExecutionStatusValue.Done) {
/// Retrieve file info with appdata fields
final file = await client.files.file('<image-uuid>', include: FilesIncludeFields.withAppData());

/// Now you can access recognition info with the following field
final recognitionData = file.appData.awsRecognition;
}
copied to clipboard
Malware protection
Official documentation
final taskId = await client.addons.executeClamAV('<file-uuid>');

final result = await client.addons.checkClamAVExecutionStatus(taskId);

if (result.status == AddonExecutionStatusValue.Done) {
/// Retrieve file info with appdata fields
final file = await client.files.file('<file-uuid>', include: FilesIncludeFields.withAppData());

/// Now you can access clamAV result with the following field
final clamAVData = file.appData.clamAV;
}
copied to clipboard
Background removal
Official documentation
final taskId = await client.addons.executeRemoveBg('<image-uuid>');

final result = await client.addons.checkRemoveBgExecutionStatus(taskId);

if (result.status == AddonExecutionStatusValue.Done) {
/// Retrieve file info with appdata fields
final file = await client.files.file('<image-uuid>', include: FilesIncludeFields.withAppData());

/// Now you can access removeBg result with the following field
final removeBgData = file.appData.removeBg;
}
copied to clipboard
Webhooks #
Official documentation
/// Get list of project webhooks
final List<WebhookEntity> hooks = await client.webhooks.list();

/// Create webhook
final WebhookEntity webhook = await client.webhooks.create(targetUrl: '<webhook-endpoint>', event: WebhookEvent.Uploaded);

/// Update webhook
final WebhookEntity webhook = await client.webhooks.update(hookId: '<webhook-id>', isActive: false);

/// Delete webhook
await client.webhooks.delete('<webhook-endpoint>');
copied to clipboard
Project #
/// Get project common information
final ProjectEntity info = await client.project.info();
copied to clipboard
FAQ #


How to pick files on different platforms?

See uploadcare example project



Do you like the package? Buy me a coffee :)