Image Service Client #

A Dart client library for interacting with the Image Service server. Provides a simple, type-safe API for uploading, retrieving, transforming, and managing images.

Features #

📤 Upload Images - Multipart form upload or binary PUT with custom filename
🌐 Upload from URL - Fetch and store images from public URLs
⏰ Temporary Upload URLs - Generate secure, single-use tokens for client-side uploads
📥 Retrieve Images - Get original or transformed versions
🎨 Transform Images - On-the-fly resizing and quality adjustment
🗑️ Delete Images - Remove images from the server
📋 List Images - Get all stored images with metadata
🔒 Authenticated - Built-in API key authentication
🧪 Testable - Supports dependency injection for testing

Installation #

Add to your pubspec.yaml:

dependencies:
  image_service_client: ^0.0.1-dev.1

Usage #

Initialize the Client #

import 'package:image_service_client/image_service_client.dart';

final client = ImageServiceClient(
  baseUrl: 'http://localhost:8080',
  apiKey: 'your-secret-api-key',
);

Upload an Image #

Using multipart form (POST):

final imageBytes = await File('photo.jpg').readAsBytes();

final response = await client.uploadImage(
  imageBytes: imageBytes,
  fileName: 'photo.jpg', // optional
);

print('Uploaded: ${response.url}');

With custom filename (PUT):

final imageBytes = await File('photo.jpg').readAsBytes();

final response = await client.uploadImageWithFilename(
  imageBytes: imageBytes,
  fileName: 'my-custom-name.jpg',
  contentType: 'image/jpeg',
);

print('Uploaded: ${response.url}');

Using temporary upload token (no API key needed):

Temporary upload URLs allow you to generate a secure, single-use token that clients can use to upload images directly without exposing your API key. Perfect for client-side uploads in mobile or web apps.

// Step 1: Create a temporary upload URL (requires API key)
final tempUrl = await client.createTemporaryUploadUrl();

print('Token: ${tempUrl.token}');
print('Expires in: ${tempUrl.expiresIn} seconds');

// Step 2: Use the token to upload (no API key needed!)
// This can be done from a mobile app or browser without exposing your API key
final response = await client.uploadImageWithToken(
  token: tempUrl.token,
  imageBytes: imageBytes,
  fileName: 'photo.jpg', // optional
);

print('Uploaded: ${response.url}');

Security Features:

Token is single-use (automatically deleted after upload)
Expires after 15 minutes
Cryptographically secure (32 random bytes)
Perfect for client-side uploads without exposing API keys

Upload from a public URL:

You can also upload images directly from a public URL. The server will fetch the image and store it for you.

// Upload from URL (requires API key)
final response = await client.uploadImageFromUrl(
  url: 'https://example.com/image.jpg',
);

print('Uploaded: ${response.url}');

With custom filename:

final response = await client.uploadImageFromUrl(
  url: 'https://example.com/image.jpg',
  fileName: 'my-custom-name.jpg',
);

With bucket:

final response = await client.uploadImageFromUrl(
  url: 'https://example.com/image.jpg',
  bucket: 'avatars',
);

Features:

Requires API key authentication
10 second timeout for fetching the image
Returns 400 Bad Request if URL is invalid or unreachable
Supports optional custom filename and bucket parameters
Filename is extracted from URL if not provided

Retrieve an Image #

Get original image:

final bytes = await client.getImage('photo.jpg');
await File('downloaded.jpg').writeAsBytes(bytes);

Get transformed image:

final bytes = await client.getImage(
  'photo.jpg',
  transform: ImageTransformOptions(
    width: 500,
    height: 300,
    quality: 85,
  ),
);

Get Image URLs #

// Original image URL
final url = client.getImageUrl('photo.jpg');
print(url); // http://localhost:8080/files/photo.jpg

// Transformed image URL
final transformedUrl = client.getImageUrl(
  'photo.jpg',
  transform: ImageTransformOptions(width: 500),
);
print(transformedUrl); // http://localhost:8080/files/width=500/photo.jpg

Delete an Image #

await client.deleteImage('photo.jpg');
print('Image deleted!');

List All Images #

final images = await client.listImages();

for (final image in images) {
  print('${image.originalName} - ${image.url} (${image.size} bytes)');
}

Error Handling #

try {
  await client.uploadImage(imageBytes: bytes);
} on ImageServiceException catch (e) {
  print('Error: ${e.statusCode} - ${e.message}');
}

Server Setup #

This client library requires the Image Service server to be running. The easiest way to get started is using the pre-built Docker image:

# Pull the latest image
docker pull ghcr.io/mtwichel/image_service:latest

# Run the server
docker run -d \
  -p 8080:8080 \
  -e SECRET_KEY=your-secret-api-key \
  -v $(pwd)/data:/app/data \
  --name image_service \
  ghcr.io/mtwichel/image_service:latest

Available architectures: linux/amd64, linux/arm64

For complete server documentation, deployment options, and building from source, see the Image Service repository.

API Reference #