# qiniu-java-sdk packages Qiniu object storage into a plain Java client

> The Qiniu Resource Storage SDK for Java is a MIT licensed client library published on Maven Central as com.qiniu:qiniu-java-sdk, covering upload, download, bucket management, CDN refresh and image processing. It runs on JDK 7 and later, and the repository documents both a v1 and a v2 resumable upload path.

**qiniu/java-sdk** — Qiniu Resource (Cloud) Storage SDK for Java

- Repository: https://github.com/qiniu/java-sdk
- Stars: 559 · Forks: 468
- Language: Java
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/qiniu-java-sdk

## What the SDK covers for a Java team

The repository describes itself as the Qiniu Resource Storage SDK for Java, and the package on Maven Central is com.qiniu:qiniu-java-sdk. The scope is object storage for a Java application, and the example directory shows how broad that is in practice. There are files for uploading and downloading, for copying, moving and deleting objects, for listing a bucket, and for fetching bucket info. CDN operations have their own examples, including refreshing directories and refreshing URLs, and there is a FusionRefreshDemo. Media processing is covered too, with examples named for image operations such as fops, a video frame extraction called pfop_vframe, and a watermark example. The naming makes a point about the SDK's shape: the operations mirror the Qiniu Kodo API surface one to one, so a developer reading the API documentation can map a service call to the Java method without translation. There is also a SendMessageDemo and a QvmUploadDemo, and a ResourcesCensor example for content moderation.

## Adding the dependency and running the build

The README offers three ways in. The simplest is to download the latest JAR, and the Maven route is a coordinate block with a version range rather than a fixed number.

```xml
<dependency>
  <groupId>com.qiniu</groupId>
  <artifactId>qiniu-java-sdk</artifactId>
  <version>[7.19.0, 7.19.99]</version>
</dependency>
```

The Gradle equivalent uses a dynamic version suffix.

```groovy
implementation 'com.qiniu:qiniu-java-sdk:7.19.+'
```

The runtime requirement is stated plainly: JDK 7 and above. The repository builds with Gradle, and the README gives two tasks.

```bash
$ ./gradlew build
```

That runs the test suite, which the README points to as the place to find API usage demos, since the unit tests under src/test double as examples. A second task exists for people who still live in Eclipse.

```bash
$ ./gradlew gen_eclipse
```

The build files themselves are conventional Gradle, with build.gradle, settings.gradle, gradle.properties, a gradlew wrapper and gradlew.bat for Windows, plus a separate mvn_push.gradle for publishing, a config directory, a code-gen directory and a codecov.yml. The presence of codecov.yml and the coverage badge in the README says the project measures test coverage rather than treating tests as optional.

## The upload path and the two resumable API versions

The usage example shows the shape of an upload. You build a Configuration, create an UploadManager from it, create an Auth from an access key and secret key, mint an upload token for a bucket, and then put bytes under a key.

```java
import com.qiniu.storage.UploadManager;
import com.qiniu.util.Auth;
import com.qiniu.storage.Configuration;
import com.qiniu.http.Response;

String accessKey = "Your AccessKey";
String secretKey = "Your SecretKey";
String bucketName = "upload to bucket";
Configuration cfg = Configuration.create();
UploadManager uploadManager = new UploadManager(cfg);
Auth auth = Auth.create(accessKey, secretKey);
String token = auth.uploadToken(bucketName);
String key = "file save key";
Response r = uploadManager.put("hello world".getBytes(), key, token);
```

The second example is the same sequence with one line changed, and that line is the whole difference.

```java
cfg.resumableUploadAPIVersion = Configuration.ResumableUploadAPIVersion.V2;
```

So the SDK exposes two resumable upload protocol versions behind one switch, and the decision is made on the Configuration rather than on the manager. The token is minted with the bucket name and passed alongside the key and the payload, which is the shape of the Qiniu upload token model, where the token carries the permission rather than the request carrying credentials. The returned Response is the HTTP response object, and the README notes that QiniuExeption, spelled that way in the documentation, retains the request and response information and is thrown on failure so that a failure can be reported for investigation.

## Where the real documentation lives

The README is a starting point and says so. For other uses it points to the developer guide at developer.qiniu.com/kodo/1239/java, and for detailed examples it points to the examples directory in the repository. The examples directory is genuinely the reference to read, and the file names make it browsable: UploadBySelfDefiningDomain and UploadBySelfDefiningParam cover the two upload variations that matter in practice, one for a custom domain and one for custom parameters, while upload.java, download.java, copy.java, move.java and delete.java cover the object operations and ListDemo and GetBucketInfo cover the bucket side. There is also a separate Qiniu Java SDK documentation site published under the qiniu GitHub Pages domain and a link to the official documentation site at developer.qiniu.com. For support the README asks you to open a ticket in the portal, or email support@qiniu.com, and points to a question and answer community. Bug reports and feature requests go to the issue tracker, and code goes in as a pull request, with the contribution process detailed in CONTRIBUTING.md at the repository root.

## Version cadence, licences and the gap between master and the releases

The release history is where the caution lies. The listed releases are v7.19.0 from 2025-06-20, v7.18.0 from 2025-02-13 and v7.17.0 from 2024-10-25, while the last push to the master branch was on 2026-10-19. In other words, the branch is being worked on after the newest tag, and a developer who installs from the Maven version range will get something close to but not identical to the master branch. The repository also carries a CHANGELOG.md, which is where you would look before upgrading, and a Travis CI build badge plus an R build badge... in fact the README carries a Travis CI build status badge alongside the GitHub release and coverage badges, which suggests the original CI setup predates the GitHub Actions workflows now present in the .github directory. Licensing is the MIT License, and the README states it plainly, with the full text in the LICENSE file at the repository root. The MIT grant means a proprietary application can depend on it without licensing obligations, though that is a statement about the licence, not advice about your own obligations.

## Where this SDK is the wrong choice

There are three honest limits. The first is that it is Java only. The examples, the class names, the Maven coordinates and the whole API surface are Java, and the alternative for a Go, Python or Node service is to call the Qiniu HTTP API directly with your own signing code, which is more work but is not blocked by this SDK. The second is that the documented surface is a moving target relative to the Kodo documentation. The README defers to the developer guide for everything beyond uploads, so the SDK's own documentation is thin in exactly the places where the service surface changes often, and you are expected to read the external guide to understand what a parameter does. The third is the version gap described above, which bites hardest for anyone who pins a Maven version range expecting the newest work. And there is a limit about the alternative approach itself: because the SDK is a thin client over the HTTP API, it does not give you a storage abstraction you can swap for another provider. If you might move off Qiniu, the object access in your code will still be Qiniu-shaped, and a port means rewriting the calls, not swapping an interface.

## Conclusion

Adopt qiniu-java-sdk if your Java service stores objects in Qiniu and you want the upload, refresh and image processing calls covered by a maintained client rather than hand-written HTTP. Skip it if your stack is not Java, since the examples and the whole SDK surface are Java-only. Before you pin a version, check the release list, because the newest published release is v7.19.0 from 2025-06-20 while the last push to the repository was on 2026-10-19, so the default branch carries work that is not yet in a tagged release.

## FAQ

### How do I add the Qiniu Java SDK to a Maven project?

Add the com.qiniu dependency with groupId com.qiniu, artifactId qiniu-java-sdk and a version range such as [7.19.0, 7.19.99]. The Gradle equivalent is `implementation 'com.qiniu:qiniu-java-sdk:7.19.+'`, and the JAR can also be downloaded directly.

### What Java version does the Qiniu Java SDK require?

The README states the runtime requirement as JDK 7 and above.

### How do I switch between resumable upload API versions in qiniu-java-sdk?

You set the version on the Configuration object before creating the UploadManager, for example `cfg.resumableUploadAPIVersion = Configuration.ResumableUploadAPIVersion.V2;`. The rest of the upload sequence, creating Auth, minting an upload token and calling put, stays the same.

### How do I build and test the Qiniu Java SDK locally?

The build uses Gradle and the README gives `./gradlew build` for the build and tests, and `./gradlew gen_eclipse` to generate Eclipse project files. The unit tests under src/test are described as a source of API usage examples.

## Sources

- [Issues](https://github.com/qiniu/java-sdk/issues)
- [License: MIT](https://github.com/qiniu/java-sdk/blob/master/LICENSE)
- [qiniu/java-sdk on GitHub](https://github.com/qiniu/java-sdk)
- [README](https://github.com/qiniu/java-sdk/blob/master/README.md)
- [Releases](https://github.com/qiniu/java-sdk/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/qiniu-java-sdk