Java ImageKit SDK

The ImageKit Java SDK provides a complete Java library for integrating ImageKit into your applications. Built with modern Java patterns and full type safety using immutable builders.

What the SDK Does

URL generation with image/video transformations
File uploads to ImageKit's media library
File management - list, search, update, delete files
Signed URLs for private content delivery
Client-side upload authentication tokens
Webhook verification for event handling
Full type safety with builder patterns
Sync & async support with OkHttp
Immutable classes for thread safety

Installation

Gradle

Copy

implementation("io.imagekit:image-kit-java:3.0.0")

Maven

Copy

<dependency>
  <groupId>io.imagekit</groupId>
  <artifactId>image-kit-java</artifactId>
  <version>3.0.0</version>
</dependency>

Requirements

This library requires Java 8 or later.

Quick Start

Get your API credentials from the ImageKit Dashboard:

Copy

import io.imagekit.client.ImageKitClient;
import io.imagekit.client.okhttp.ImageKitOkHttpClient;

// From environment variables or system properties
ImageKitClient client = ImageKitOkHttpClient.fromEnv();

// Or configure manually
ImageKitClient client = ImageKitOkHttpClient.builder()
    .privateKey(System.getenv("IMAGEKIT_PRIVATE_KEY"))
    .publicKey(System.getenv("IMAGEKIT_PUBLIC_KEY"))
    .webhookSecret(System.getenv("IMAGEKIT_WEBHOOK_SECRET"))
    .build();

Environment variables:

IMAGEKIT_PRIVATE_KEY - Your private API key
IMAGEKIT_WEBHOOK_SECRET - Your webhook secret (optional)

Common Examples

Upload a File

Copy

import io.imagekit.models.files.FileUploadParams;
import io.imagekit.models.files.FileUploadResponse;
import java.nio.file.Paths;

// Upload from file path
FileUploadParams params = FileUploadParams.builder()
    .file(Paths.get("/path/to/product.jpg"))
    .fileName("product.jpg")
    .folder("/products")
    .addTag("product")
    .addTag("featured")
    .build();

FileUploadResponse response = client.files().upload(params);
System.out.println("File ID: " + response.fileId());
System.out.println("URL: " + response.url());

// Upload from byte array
byte[] imageData = request.getInputStream().readAllBytes();
FileUploadParams params = FileUploadParams.builder()
    .file(imageData)
    .fileName("upload.jpg")
    .build();
FileUploadResponse response = client.files().upload(params);

// Upload from InputStream
try (InputStream stream = new FileInputStream("/path/to/video.mp4")) {
    FileUploadParams params = FileUploadParams.builder()
        .file(stream)
        .fileName("video.mp4")
        .build();
    FileUploadResponse response = client.files().upload(params);
}

Generate Image URLs

Copy

import io.imagekit.models.SrcOptions;
import io.imagekit.models.Transformation;

// Basic transformation
String url = client.helper().buildUrl(
    SrcOptions.builder()
        .urlEndpoint("https://ik.imagekit.io/your_imagekit_id")
        .src("/product.jpg")
        .addTransformation(
            Transformation.builder()
                .width(800.0)
                .height(600.0)
                .format(Transformation.Format.WEBP)
                .build()
        )
        .build()
);

Signed URLs

Copy

// Expires in 1 hour
String url = client.helper().buildUrl(
    SrcOptions.builder()
        .urlEndpoint("https://ik.imagekit.io/your_imagekit_id")
        .src("/private/doc.pdf")
        .signed(true)
        .expiresIn(3600.0)
        .build()
);

Image Overlays

Copy

import io.imagekit.models.ImageOverlay;
import io.imagekit.models.Overlay;
import io.imagekit.models.OverlayPosition;

// Add watermark
String url = client.helper().buildUrl(
    SrcOptions.builder()
        .urlEndpoint("https://ik.imagekit.io/your_imagekit_id")
        .src("/photo.jpg")
        .addTransformation(
            Transformation.builder()
                .overlay(Overlay.ofImage(
                    ImageOverlay.builder()
                        .input("/logo.png")
                        .position(OverlayPosition.builder()
                            .focus(OverlayPosition.Focus.BOTTOM_RIGHT)
                            .build())
                        .addTransformation(
                            Transformation.builder()
                                .width(100.0)
                                .opacity(70.0)
                                .build()
                        )
                        .build()
                ))
                .build()
        )
        .build()
);

Text Overlays

Copy

import io.imagekit.models.Overlay;
import io.imagekit.models.OverlayPosition;
import io.imagekit.models.TextOverlay;
import io.imagekit.models.TextOverlayTransformation;

String url = client.helper().buildUrl(
    SrcOptions.builder()
        .urlEndpoint("https://ik.imagekit.io/your_imagekit_id")
        .src("/product.jpg")
        .addTransformation(
            Transformation.builder()
                .overlay(Overlay.ofText(
                    TextOverlay.builder()
                        .text("SALE")
                        .position(OverlayPosition.builder()
                            .focus(OverlayPosition.Focus.TOP_LEFT)
                            .build())
                        .addTransformation(
                            TextOverlayTransformation.builder()
                                .fontSize(48.0)
                                .fontColor("FF0000")
                                .build()
                        )
                        .build()
                ))
                .build()
        )
        .build()
);

Client-Side Upload Auth

For browser-based uploads, generate auth tokens:

Copy

import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.util.Map;

@WebServlet("/api/imagekit-auth")
public class AuthServlet extends HttpServlet {
    protected void doGet(HttpServletRequest request, HttpServletResponse response) {
        Map<String, Object> authParams = client.helper()
            .getAuthenticationParameters(null, null);
        
        response.setContentType("application/json");
        response.getWriter().write(new Gson().toJson(authParams));
    }
}

Webhook Verification

Copy

import io.imagekit.models.webhooks.UnwrapWebhookParams;
import io.imagekit.models.webhooks.UnwrapWebhookEvent;
import io.imagekit.core.http.Headers;

@PostMapping("/webhooks/imagekit")
public ResponseEntity<String> handleWebhook(@RequestBody String payload, 
                                            @RequestHeader HttpHeaders headers) {
    try {
        Headers webhookHeaders = Headers.builder()
            .putAll(Map.of(
                "webhook-id", headers.getFirst("webhook-id"),
                "webhook-timestamp", headers.getFirst("webhook-timestamp"),
                "webhook-signature", headers.getFirst("webhook-signature")
            ))
            .build();
        
        UnwrapWebhookEvent event = client.webhooks().unwrap(
            UnwrapWebhookParams.builder()
                .payload(payload)
                .headers(webhookHeaders)
                .build()
        );
        
        // Handle different event types
        if (event.isVideoTransformationReady()) {
            var videoEvent = event.asVideoTransformationReady();
            System.out.println("Video ready: " + videoEvent.data().transformation().output().url());
        }
        
        return ResponseEntity.ok("success");
    } catch (Exception e) {
        return ResponseEntity.status(401).body("Invalid signature");
    }
}

Advanced Features

Asynchronous Execution

Copy

import io.imagekit.client.ImageKitClientAsync;
import io.imagekit.client.okhttp.ImageKitOkHttpClientAsync;
import java.util.concurrent.CompletableFuture;

// Create async client
ImageKitClientAsync asyncClient = ImageKitOkHttpClientAsync.fromEnv();

// Or convert sync client to async
CompletableFuture<FileUploadResponse> future = client.async()
    .files()
    .upload(params);

future.thenAccept(response -> {
    System.out.println("Uploaded: " + response.url());
});

File Management

Copy

import io.imagekit.models.assets.AssetListParams;
import io.imagekit.models.assets.AssetListResponse;
import java.util.List;

// List files
List<AssetListResponse> assets = client.assets().list(
    AssetListParams.builder()
        .skip(0L)
        .limit(100L)
        .build()
);

// Search with query
List<AssetListResponse> results = client.assets().list(
    AssetListParams.builder()
        .searchQuery("tags IN ['sale', 'summer']")
        .build()
);

// Get file details
import io.imagekit.models.files.FileGetParams;
var file = client.files().get(FileGetParams.builder()
    .fileId("file_id_here")
    .build());

// Delete file
import io.imagekit.models.files.FileDeleteParams;
client.files().delete(FileDeleteParams.builder()
    .fileId("file_id_here")
    .build());

Error Handling

Copy

import io.imagekit.errors.ImageKitException;

try {
    FileUploadResponse response = client.files().upload(params);
} catch (ImageKitException e) {
    System.err.println("Upload failed: " + e.getMessage());
    // Handle specific error codes
    if (e.statusCode() == 401) {
        System.err.println("Authentication error");
    }
}

Complete API Reference

Every endpoint in the ImageKit REST API Reference includes Java code snippets. For detailed documentation of all SDK methods and models, visit:

GitHub Repository - Source code and examples
Javadoc - Complete API documentation

Learn More

Image Transformations - All transformation parameters
Video Transformations - Video-specific transformations
Overlays - Advanced overlay options
Webhooks - Event types and webhook setup

Support

Issues: GitHub Issues
Email: support@imagekit.io