Java SDK
Install
The JARs can be downloaded manually from Maven Central Search, or can be installed from the Maven repository.
Existing users should take note of the JCenter shutdown and update their build files to receive the most recent versions.
The examples below target Java SDK 2.2.4, including its external signature provider API.
Gradle:
implementation 'com.transloadit.sdk:transloadit:2.2.4'
Maven:
<dependency>
<groupId>com.transloadit.sdk</groupId>
<artifactId>transloadit</artifactId>
<version>2.2.4</version>
</dependency>
Usage
All interactions with the SDK begin with the com.transloadit.sdk.Transloadit class.
The complete Main examples below run on a trusted server using server-held credentials. Replace
the credential, file, Assembly, and Template placeholders with your own server configuration.
Keep account and Template administration on your backend. For uploads from mobile or desktop
apps distributed to users, use the external signature provider described below.
Authentication
The SDK supports two authentication methods:
1. API key + secret
On a trusted server, the SDK can sign requests using your Auth Key and Auth Secret. Load real credentials from your server’s secret store; never include the Auth Secret in a distributed app or commit it to source control. Server-side initialization:
Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", System.getenv("TRANSLOADIT_SECRET"));
2. External signature provider
For client uploads, keep the Auth Secret on your backend and require Signature Authentication for the Workspace or Template used by the app. See the Android SDK guide for the application/backend integration.
SignatureProvider.generateSignature(String paramsJson) runs synchronously. Your implementation
must obtain a signature for the exact UTF-8 bytes of paramsJson from your authenticated HTTPS
backend, with a finite network timeout. Throw if authorization, transport, or response validation
fails, and run SDK requests off the UI thread. The backend must authenticate the user and authorize
the upload’s Steps or Template, destinations, limits, nonce, and expiry before signing. It must
not sign arbitrary client-supplied params. For a server-owned Template, disable
allow_steps_override.
The constructor below requests an expiry five minutes in the future; the backend must validate it
against its own clock. Return only the approved HMAC-SHA384 signature (sha384: followed by 96
hexadecimal digits), never the Auth Secret. Do not reserialize the params before signing or reuse
a signature for different params.
Save this helper as SignedClient.java and supply your application’s SignatureProvider:
import com.transloadit.sdk.SignatureProvider;
import com.transloadit.sdk.Transloadit;
public final class SignedClient {
private SignedClient() {}
public static Transloadit create(String authKey, SignatureProvider approvedSignatures) {
return new Transloadit(authKey, approvedSignatures);
}
}
Create an Assembly
To create an assembly, you use the newAssembly method.
import com.transloadit.sdk.Assembly;
import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.AssemblyResponse;
import java.io.File;
import java.util.HashMap;
import java.util.Map;
public class Main {
public static void main(String[] args) {
Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", System.getenv("TRANSLOADIT_SECRET"));
Assembly assembly = transloadit.newAssembly();
Map<String, Object> stepOptions = new HashMap<>();
stepOptions.put("width", 75);
stepOptions.put("height", 75);
assembly.addStep("resize", "/image/resize", stepOptions);
assembly.addFile(new File("PATH/TO/FILE.jpg"));
// you can skip this part if you don't want to wait till the
// assembly is complete
assembly.setShouldWaitForCompletion(true);
try {
AssemblyResponse response = assembly.save();
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
System.out.println(response.getId());
System.out.println(response.getUrl());
System.out.println(response.json());
} catch (RequestException | LocalOperationException e) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
Get an Assembly
The method, getAssembly, retrieves the JSON status of an assembly identified by the given
assembly_Id.
import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.AssemblyResponse;
public class Main {
public static void main(String[] args) {
Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", System.getenv("TRANSLOADIT_SECRET"));
try {
AssemblyResponse response = transloadit.getAssembly("ASSEMBLY_ID");
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
System.out.println(response.getUrl());
System.out.println(response.json());
} catch (RequestException | LocalOperationException e) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
You may also get an assembly by url with the getAssemblyByUrl method.
AssemblyResponse response = transloadit.getAssemblyByUrl("ASSEMBLY_URL");
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
Cancel an Assembly
To cancel an executing assembly, use the cancelAssembly method with the full HTTPS Assembly URL
from AssemblyResponse.getSslUrl() (the assembly_ssl_url response field).
import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.AssemblyResponse;
public class Main {
public static void main(String[] args) {
Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", System.getenv("TRANSLOADIT_SECRET"));
try {
AssemblyResponse response = transloadit.cancelAssembly("ASSEMBLY_URL");
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
System.out.println(response.isCanceled()); // true when cancellation succeeded
} catch (RequestException | LocalOperationException e) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
List Assemblies
The method, listAssemblies, retrieves an array of assemblies according to the given options.
Valid options can be page, pagesize, type, fromdate and todate. Please consult the
Transloadit API docs for details.
import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.ListResponse;
import java.util.HashMap;
import java.util.Map;
public class Main {
public static void main(String[] args) {
Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", System.getenv("TRANSLOADIT_SECRET"));
try {
Map<String, Object> options = new HashMap<>();
options.put("pagesize", 10);
ListResponse response = transloadit.listAssemblies(options);
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
System.out.println(response.size()); // number of assemblies on the list.
System.out.println(response.getItems()); // returns an iterable json array
} catch (RequestException | LocalOperationException e) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
Create a Template
To create a new template, you use the newTemplate method, passing the template name as a
parameter. Step names must be unique: this example resizes and optimizes the original image in
separate Steps.
import com.transloadit.sdk.Template;
import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.Response;
import java.util.HashMap;
import java.util.Map;
public class Main {
public static void main(String[] args) {
Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", System.getenv("TRANSLOADIT_SECRET"));
Template template = transloadit.newTemplate("MY_TEMPLATE_NAME");
Map<String, Object> resizeOptions = new HashMap<>();
resizeOptions.put("width", 75);
resizeOptions.put("height", 75);
Map<String, Object> optimizeOptions = new HashMap<>();
optimizeOptions.put("use", ":original");
template.addStep("resize", "/image/resize", resizeOptions);
template.addStep("optimize", "/image/optimize", optimizeOptions);
try {
Response response = template.save();
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
System.out.println(response.json());
System.out.println(response.json().getString("id")); // gets the Template ID.
} catch (RequestException | LocalOperationException e) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
Update a Template
To update a template, use the updateTemplate method with the Template ID and options to update.
Pass Instructions as JSON in the template option, alongside the new name; see the
Template update API.
import com.transloadit.sdk.Steps;
import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.Response;
import java.util.HashMap;
import java.util.Map;
import org.json.JSONObject;
public class Main {
public static void main(String[] args) {
Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", System.getenv("TRANSLOADIT_SECRET"));
Steps steps = new Steps();
Map<String, Object> stepOptions = new HashMap<>();
stepOptions.put("width", 150);
stepOptions.put("height", 150);
steps.addStep("resize", "/image/resize", stepOptions);
Map<String, Object> instructions = new HashMap<>();
instructions.put("steps", steps.toMap());
Map<String, Object> templateOptions = new HashMap<>();
templateOptions.put("template", new JSONObject(instructions).toString());
templateOptions.put("name", "MY_NEW_TEMPLATE_NAME");
try {
Response response = transloadit.updateTemplate("TEMPLATE_ID", templateOptions);
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
} catch (RequestException | LocalOperationException e) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
Delete a Template
To delete a template, you use the deleteTemplate method, passing the Template ID as a parameter.
import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.Response;
import java.util.HashMap;
public class Main {
public static void main(String[] args) {
Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", System.getenv("TRANSLOADIT_SECRET"));
try {
Response response = transloadit.deleteTemplate("TEMPLATE_ID");
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
} catch (RequestException | LocalOperationException e) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
List Templates
To get a list of all templates under your account, you use the listTemplates method.
import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.ListResponse;
public class Main {
public static void main(String[] args) {
Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", System.getenv("TRANSLOADIT_SECRET"));
try {
ListResponse response = transloadit.listTemplates();
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
System.out.println(response.size()); // number of assemblies on the list.
System.out.println(response.getItems()); // returns an iterable json array
} catch (RequestException | LocalOperationException e) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
Get a template
To get a particular template, you use the getTemplate method, passing the Template ID as a
parameter.
import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.Response;
public class Main {
public static void main(String[] args) {
Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", System.getenv("TRANSLOADIT_SECRET"));
try {
Response response = transloadit.getTemplate("TEMPLATE_ID");
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
System.out.println(response.json());
} catch (RequestException | LocalOperationException e) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
Get bill
To get your account billing details for a particular month, you use the getBill method, passing
the month and year as parameters.
import com.transloadit.sdk.Transloadit;
import com.transloadit.sdk.exceptions.LocalOperationException;
import com.transloadit.sdk.exceptions.RequestException;
import com.transloadit.sdk.response.Response;
public class Main {
public static void main(String[] args) {
Transloadit transloadit = new Transloadit("YOUR_TRANSLOADIT_KEY", System.getenv("TRANSLOADIT_SECRET"));
try {
Response response = transloadit.getBill(3, 2017);
if (response.json().has("error")) throw new IllegalStateException(response.json().getString("error"));
System.out.println(response.json());
} catch (RequestException | LocalOperationException e) {
System.err.println("Request failed.");
System.exit(1);
}
}
}
Example
For fully working examples take a look at /examples.
Documentation
See Javadoc for full API documentation.