README.md

cloudinary_java — documentation for coding agents

Task documentation for the Cloudinary Java SDK. Each page is self-contained: imports, configuration, a complete runnable flow, expected results, and common failures. Every Java snippet compiles against this SDK, and the documented behaviour was observed against a live Cloudinary product environment. Runnable versions of several tasks are in examples/.

These pages describe the 2.x API. Methods from the 1.x line are not present in 2.x.

Where these pages live

In the repository, at docs/. They are not shipped inside the published jars — Java libraries distribute prose documentation alongside the artifact, not inside it. Read them from a checkout, or from the repository on GitHub at the tag matching your dependency version. Without repository access, Cloudinary's own documentation serves raw Markdown at https://cloudinary.com/documentation/<page>.md, indexed by llms.txt; that covers the platform rather than this SDK's Java specifics.

To confirm which version you are running, compare Cloudinary.VERSION with the version these pages describe. That constant can differ from the released artifact version.

Start here

• What this library covers — the agent tooling to set up first (Skills, MCP servers, CLI, documentation indexes), what this library covers, and what lives elsewhere on the platform.
• Get Cloudinary credentials — console signup, or a throwaway environment for testing.
• Add the dependency and make a first call — the two-artifact dependency and the Cloudinary entry point.

Tasks

• Configure Cloudinary
• Upload an image
• Upload a large video
• Sign a browser upload
• Transform and deliver an image
• Transform and deliver a video
• Search and manage assets
• Moderate an upload
• Use structured metadata
• Use with Spring Boot
• Use the JSP tag library
• Troubleshoot errors

Behaviours to know

1. cloudinary-core provides URL building and parameter handling; uploads and Admin API calls need cloudinary-http5 on the classpath. Without it the Cloudinary constructor throws java.lang.UnknownError, which is an Error rather than an Exception. See import-and-call.md.
2. Upload API errors are RuntimeException carrying a message; Admin API errors are typed ApiException subclasses. See troubleshoot-errors.md.
3. Cloud names containing an underscore are configured with a Map rather than a cloudinary:// URL; parsing such a URL yields null cloud name, API key, and secret. See configure-cloudinary.md.
4. buildUploadParams forwards a defined parameter set; unrecognised keys are not sent. See upload-image.md.
5. Moderation status is metadata to check in your own code; a pending asset is deliverable. See moderate-upload.md.
6. uploadLarge defaults resource_type to image; pass video, raw, or auto as appropriate. With the default, a video upload throws RuntimeException: Invalid image file. See upload-large-video.md.

Security boundary

This is a server-side SDK. It holds your api_secret, which belongs on your server only. Frontend code should receive delivery URLs or short-lived signatures generated by your server (how). For attribute values that come from user input, render tags with your template engine rather than imageTag() / videoTag() (details).

Canonical docs

• Java SDK guide
• Full platform reference

Link convention: documentation links in these docs end in .md and return raw Markdown — the preferred format for agents and for anything that parses text. Remove the .md suffix for the same page as browsable HTML. The repository README links the HTML form first, since it is read by people.

Snippet conventions: snippets assume import com.cloudinary.*; and import com.cloudinary.utils.ObjectUtils; unless shown otherwise. Placeholder credentials and identifiers are obviously fake but correctly shaped — a real asset ID is 32 lowercase hex characters, shown here as abcdef0123456789abcdef0123456789. Never copy a placeholder into production.