Cloudinary Java SDK

Upload, transform, optimize, and manage images and videos with Cloudinary from Java — the com.cloudinary artifacts on Maven Central.

Install

<dependency>
    <groupId>com.cloudinary</groupId>
    <artifactId>cloudinary-http5</artifactId>
    <version>2.6.0</version>
</dependency>

implementation 'com.cloudinary:cloudinary-http5:2.6.0'

For JSP tags, also add cloudinary-taglib.

Quick start

Set your API environment variable (Console > Settings > API Keys):

export CLOUDINARY_URL=cloudinary://<api_key>:<api_secret>@<cloud_name>

Upload an image and get an optimized delivery URL:

import com.cloudinary.Cloudinary;
import com.cloudinary.Transformation;
import com.cloudinary.utils.ObjectUtils;
import java.util.Map;

public class QuickStart {
    public static void main(String[] args) {
        try {
            // Reads CLOUDINARY_URL from the environment
            Cloudinary cloudinary = new Cloudinary();

            // Upload a remote image (a local File or path works the same way)
            Map result = cloudinary.uploader().upload(
                    "https://res.cloudinary.com/demo/image/upload/sample.jpg",
                    ObjectUtils.asMap("public_id", "quickstart-sample"));
            System.out.println("Uploaded: " + result.get("public_id"));

            // Build a 400x400 auto-cropped URL with automatic format and quality
            String url = cloudinary.url()
                    .transformation(new Transformation()
                            .width(400).height(400).crop("fill").gravity("auto")
                            .fetchFormat("auto").quality("auto"))
                    .generate((String) result.get("public_id"));
            System.out.println("Optimized URL: " + url);
        } catch (Exception e) {
            System.err.println("Quick start failed: " + e.getMessage());
            System.err.println("Check that CLOUDINARY_URL is set (Console > Settings > API Keys).");
            System.exit(1);
        }
    }
}

Save as QuickStart.java, compile against cloudinary-http5 and its dependencies, and run. Create a free account if you don't have one — see Get credentials for the options, including a throwaway environment for testing.

Common tasks

Runnable versions live in examples/ — each is a complete file you can run directly.

When to use this SDK

Use this library in server-side Java: uploads, signed operations, asset administration, search, moderation, and delivery URL generation.

For other jobs, better-fitting tools exist:

Android apps: the Android SDK (md); cloudinary-http5 targets server-side JVMs.
Complete in-browser upload UI: Upload Widget (md).
Text-to-image generation and image-to-video: platform APIs (md), not wrapped by this library.
Multi-step media workflow automation: MediaFlows (md).
Interactive agent-driven asset operations: Cloudinary MCP servers and Skills (md).

The full capability map — plus the Skills, MCP servers, and CLI worth setting up first — is in docs/platform-capabilities.md.

Status and compatibility

Stable, actively maintained. See CHANGELOG.md.

SDK version	Java
2.x	8 and later
1.1.0 – 1.39.0	6 and later (no longer maintained)

cloudinary-taglib targets javax.servlet / javax.servlet.jsp, not Jakarta EE 9+.

Documentation

Task docs for this repository — snippets compile against this SDK, and documented behaviour was observed against a live environment.
Java SDK guide — the full documentation (md).

Documentation links in this README point at the browsable HTML page, with an (md) companion link that returns the same page as raw Markdown. Inside docs/ and examples/ the links are Markdown-only, since those files are written to be read by coding agents. Either form works for any page: add .md for Markdown, drop it for HTML.

For AI coding agents

Contributing to this repo: read AGENTS.md.
Using the SDK in your own project: the pages in docs/ describe this SDK's behaviour; start with platform-capabilities for what the library covers. They describe the 2.x API.

Support

SDK bugs and feature requests: GitHub issues
Account and platform questions: Cloudinary support

Security

See SECURITY.md for private vulnerability reporting. Keep your api_secret in server-side code; for client uploads, use the server-signed pattern in Sign a browser upload.

License

Released under the MIT license — see LICENSE. Copyright (c) Cloudinary Ltd.

Latest commit

History

Folders and files