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 - Direct binary upload 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 unmodified or transformed versions
🎨 Transform Images - On-the-fly resizing and quality adjustment
🗑️ Delete Images - Remove images from the server
🔒 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

Direct upload with custom filename:

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

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

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

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(
  fileName: 'photo.jpg',
);

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,
);

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

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',
);

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
Filename is extracted from URL if not provided

Retrieve an Image

Get image URL:

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

// 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!');

Error Handling

try {
  await client.uploadImage(
    imageBytes: bytes,
    fileName: 'example.jpg',
    contentType: 'image/jpeg',
  );
} 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