Java SDK
Convert files between 240+ formats from Java. One call uploads your file, converts it, waits and downloads the result; jobs, webhooks and the format list are there when you need more. Java 11+, one dependency (Jackson). Exceptions are unchecked.
Installing
Install it with your package manager. Java 11+.
$ implementation("com.runconvert:runconvert-java:0.1.0")$ <dependency>
<groupId>com.runconvert</groupId>
<artifactId>runconvert-java</artifactId>
<version>0.1.0</version>
</dependency>Initializing
RunConvert.builder().apiKey(…).baseUrl(…).timeout(…).maxRetries(…).httpClient(…).build()Create one client and reuse it. Without an API key it reads the RUNCONVERT_API_KEY environment variable. Get a key in Dashboard → API Keys, and keep it on your server: never put it in browser or mobile app code.
Example
import com.runconvert.RunConvert;
RunConvert rc = RunConvert.builder().build(); // reads RUNCONVERT_API_KEYRunConvert rc = RunConvert.builder()
.apiKey(System.getenv("RUNCONVERT_API_KEY"))
.timeout(Duration.ofSeconds(60))
.maxRetries(2)
.build();Parameters
apiKey(String)BuilderYour API key. Defaults to the RUNCONVERT_API_KEY environment variable.baseUrl(String)BuilderDefaults to https://api.runconvert.com/v3.timeout(Duration)BuilderTime limit per API request. Default 60 s. Uploads and downloads have none.maxRetries(int)BuilderRetries for network errors, 429 and 5xx. Default 2.httpClient(HttpClient)BuilderYour own java.net.http.HttpClient, e.g. for proxies.
Quick start
Convert a file in one call: the SDK uploads it, converts it, waits for the job and saves the result.
Example
import com.runconvert.RunConvert;
import com.runconvert.RunConvert.ConvertOptions;
import java.nio.file.Path;
RunConvert rc = RunConvert.builder().build();
RunConvert.ConvertResult r = rc.convert(Path.of("report.docx"),
ConvertOptions.to("pdf").outDir(Path.of("out")));
System.out.println(r.saved); // [out/report.pdf][out/report.pdf]Convert
Convert a file
rc.convert(Path file | URI url, ConvertOptions o) → ConvertResultConverts one file in one call: uploads a local file (or imports a URL), converts it, waits for the job and, when an output folder is given, downloads the result. Uses credits.
Example
ConvertResult r = rc.convert(Path.of("report.docx"),
ConvertOptions.to("pdf").outDir(Path.of("out")));
System.out.println(r.saved);// Imported by RunConvert: nothing to upload
ConvertResult r = rc.convert(URI.create("https://example.com/talk.mp4"),
ConvertOptions.to("mp3").outDir(Path.of("out")));rc.convert(Path.of("talk.mp4"), ConvertOptions.to("mp3")
.options(Map.of("audioBitrate", "192k"))
.outDir(Path.of("out")));rc.convert(Path.of("movie.mov"), ConvertOptions.to("mp4")
.outDir(Path.of("out"))
.timeout(Duration.ofMinutes(10))
.onUpdate(job -> System.out.println(job.status)));[out/report.pdf][out/talk.mp3]waiting
processing
finishedParameters
file / urlPath | URIA local file, or an http(s) URL (imported by RunConvert).RequiredConvertOptions.to(String)The target format, e.g. "pdf" or "mp3".Required.from(String)The source format. Read from the file name or URL when left out; needed for bytes or streams without a filename..options(Map<String, ?>)Engine options for the conversion, e.g. audioBitrate or image_quality. List them with Formats → engines for a pair..outDir(Path)Save the results in this folder (created if needed). Without it nothing is downloaded; use the result's files..tag(String)A label to find the job later, e.g. "invoices"..timeout(Duration)How long to wait for the job before giving up..onUpdate(Consumer<Job>)Called with the job after every check, e.g. to show progress.
Returns
ConvertResult with job (the finished job), files (each with filename, url and size) and saved (local paths, when outDir is set).
Jobs
Create a job
rc.jobs().create(Map<String, ?> tasks, String tag, Map<String, ?> metadata) → JobCreates a job from named tasks that run in order: import → convert → export. Tasks refer to each other by name in input. The job comes back with its tasks; an upload task carries the upload_url to send your file to. Build tasks with Tasks.importUrl, importUpload, convert and exportUrl.
Example
Map<String, Object> tasks = new LinkedHashMap<>();
tasks.put("a", Tasks.importUrl("https://example.com/cover.pdf"));
tasks.put("b", Tasks.importUrl("https://example.com/body.pdf"));
tasks.put("merge", Tasks.convert("pdf", "pdf", List.of("a", "b"), null));
tasks.put("export", Tasks.exportUrl("merge"));
Job job = rc.jobs().create(tasks, "merge", null);Map<String, Object> tasks = new LinkedHashMap<>();
tasks.put("upload", Tasks.importUpload());
tasks.put("convert", Tasks.convert("png", "webp", "upload", Map.of("image_quality", 80)));
tasks.put("export", Tasks.exportUrl("convert"));
Job job = rc.jobs().create(tasks);
rc.files().upload(job.task("upload").upload_url, Path.of("image.png"), null);Parameters
tasksMap<String, ?>Named task definitions. Names use letters, digits, - or _ (up to 64 characters).RequiredtagStringA label to find the job later, e.g. "invoices". null for none.metadataMap<String, ?>Your own key-value data, returned with the job and in webhooks. null for none.
Returns
The job, with its tasks.
Get a job
rc.jobs().get(String id) → JobGets one job with its tasks: status, credits used, and the result files of its export tasks.
Example
Job job = rc.jobs().get("job_01hx4k9m2p7w");
System.out.println(job.status);{
"id": "job_01hx4k9m2p7w",
"status": "finished",
"tag": "invoices",
"credits_used": 2,
"created_at": "2026-11-16T09:12:04Z",
"ended_at": "2026-11-16T09:12:09Z",
"tasks": [
{ "name": "import-1", "operation": "import/direct/upload", "status": "finished" },
{ "name": "convert-1", "operation": "convert", "status": "finished" },
{ "name": "export-1", "operation": "export/url", "status": "finished",
"result": { "files": [
{ "filename": "report.pdf", "size": 72841, "url": "https://storage.runconvert.com/…/report.pdf" }
] } }
]
}Parameters
idStringThe job's ID.Required
Returns
The job, with its tasks.
List jobs
rc.jobs().list(String status, String tag, int page, int perPage) → Jobs.PageOne page of jobs, newest first, with paging details. Filter by status or tag.
Example
Jobs.Page page = rc.jobs().list("finished", null, 1, 20);
for (Job job : page.data) System.out.println(job.id);{
"data": [ { "id": "job_01hx4k9m2p7w", "status": "finished", … } ],
"meta": { "page": 1, "per_page": 20, "total": 42, "total_pages": 3 }
}Parameters
statusStringOnly jobs with this status: waiting, processing, finished, error or canceled. null for any.tagStringA label to find the job later, e.g. "invoices". null for any.pageintPage number, from 1.perPageintJobs per page (max 100).
Returns
Jobs.Page with data, page, total and totalPages.
Every job
rc.jobs().all(String status, String tag, int perPage) → Iterable<Job>Every job, page by page, so you can loop over all of them without handling pages yourself.
Example
for (Job job : rc.jobs().all(null, "invoices", 100)) {
System.out.println(job.id + " " + job.status);
}Parameters
statusStringOnly jobs with this status: waiting, processing, finished, error or canceled. null for any.tagStringA label to find the job later, e.g. "invoices". null for any.perPageintJobs per page (max 100).
Wait for a job
rc.jobs().waitFor(String id, Duration timeout, Consumer<Job> onUpdate) → JobPolls a job until it finishes (every 0.7 s, slowing to 3 s). Fails with the task's code and reason if the job fails, and stops after the timeout if you give one.
Example
Job done = rc.jobs().waitFor(job.id, Duration.ofMinutes(5), null);
for (ResultFile f : done.exportedFiles()) rc.files().download(f, Path.of("out"));try {
rc.jobs().waitFor(job.id);
} catch (JobFailedException e) {
Task t = e.getTask();
System.out.println(t.code + " " + t.reason + " " + t.message);
}Parameters
idStringThe job's ID.RequiredtimeoutDurationHow long to wait; throws WaitTimeoutException after it. null: no limit.onUpdateConsumer<Job>Called with the job after every check, e.g. to show progress.
Returns
The finished job. waitFor(id) waits with no limit.
Cancel a job
rc.jobs().cancel(String id) → JobCancels a job's pending tasks. Credits for tasks that didn't finish are refunded.
Example
rc.jobs().cancel("job_01hx4k9m2p7w");Parameters
idStringThe job's ID.Required
Returns
The canceled job.
Delete a job
rc.jobs().delete(String id) → voidDeletes a job and its files.
Example
rc.jobs().delete("job_01hx4k9m2p7w");Parameters
idStringThe job's ID.Required
Result files
job.exportedFiles() → List<ResultFile>The files produced by a finished job's export tasks: file name, a temporary download URL and size.
Example
for (ResultFile f : job.exportedFiles()) {
System.out.println(f.filename + " " + f.url);
}[
{ "filename": "report.pdf", "size": 72841, "url": "https://storage.runconvert.com/…/report.pdf" }
]Files
Upload a file
rc.files().upload(String uploadUrl, Path file, String filename) → voidSends a file to an import/direct/upload task before its deadline. Use it with a job you created yourself.
Example
rc.files().upload(job.task("upload").upload_url, Path.of("image.png"), null);Parameters
uploadUrlStringThe upload task's upload_url: job.task("upload").upload_url.RequiredfilePathThe local file.RequiredfilenameStringThe file's name when you pass bytes or a stream. null to use the file's name.
Download a result
rc.files().download(ResultFile file, Path dir) → PathSaves a result file into a folder, keeping its name, and returns the path. Streams, so big files use little memory. download(String url, Path dir, String filename) saves a URL under a name you choose.
Example
for (ResultFile f : job.exportedFiles()) {
System.out.println(rc.files().download(f, Path.of("out")));
}out/report.pdfParameters
fileResultFileA result file from a job's export task, or its URL.RequireddirPathThe folder to save into.Required
Returns
The saved file's path.
Formats
List formats
rc.operations().list(String category) → JsonNodeEvery input format and what it converts to. Public: no API key needed.
Example
JsonNode catalog = rc.operations().list("audio");
System.out.println(catalog.get("formats").size());Parameters
categoryStringOnly one category: document, image, video, audio, ebook, archive, font, cad, … null for all.
Targets for a format
rc.operations().forInput(String input) → JsonNodeWhat one format converts to, with the credit cost of each conversion. Public.
Example
JsonNode mp4 = rc.operations().forInput("mp4");
for (JsonNode o : mp4.get("outputs")) {
System.out.println(o.get("format").asText() + " " + o.get("credits").asInt());
}{
"format": "mp4",
"category": "video",
"outputs": [
{ "format": "mp3", "category": "audio", "engine": "ffmpeg", "credits": 1 },
{ "format": "gif", "category": "image", "engine": "ffmpeg", "credits": 4 },
…
]
}Parameters
inputStringThe input format, e.g. "mp4".Required
Engines for a pair
rc.operations().forPair(String input, String output) → JsonNodeThe engines for one conversion and the options its convert task accepts, e.g. bitrate or quality. Public.
Example
JsonNode pair = rc.operations().forPair("mp4", "mp3");
for (JsonNode opt : pair.get("engines").get(0).get("options")) {
System.out.println(opt.get("name").asText());
}{
"input": "mp4",
"output": "mp3",
"engines": [
{ "name": "ffmpeg", "credits": 1,
"options": [
{ "name": "audioBitrate", "type": "string",
"description": "Target audio bitrate in kbps.",
"supported_values": ["32k", "48k", "64k", "80k", …] },
…
] }
]
}Parameters
inputStringThe input format, e.g. "mp4".RequiredoutputStringThe output format, e.g. "mp3".Required
Account
Credits and team
rc.me() → JsonNodeThe account, team and credit balance behind the API key.
Example
JsonNode me = rc.me();
System.out.println(me.at("/credits/total_remaining").asLong());{
"user": { "email": "[email protected]", "full_name": "Ada Lovelace" },
"team": { "name": "Acme" },
"credits": { "mode": "wallet", "total_remaining": 4820 }
}Webhooks
Verify a signature
Webhooks.verify(byte[] | String rawBody, String signature, String secret) → booleanChecks that a webhook delivery really came from RunConvert: an HMAC-SHA256 of the raw request body with your webhook secret, compared with the X-RunConvert-Signature header in constant time.
Example
boolean ok = Webhooks.verify(body, signatureHeader, System.getenv("RUNCONVERT_WEBHOOK_SECRET"));Parameters
rawBodybyte[] | StringThe raw request body, exactly as received (not parsed JSON).RequiredsignatureStringThe X-RunConvert-Signature header.RequiredsecretStringYour webhook's signing secret.Required
Parse an event
Webhooks.constructEvent(byte[] rawBody, String signature, String secret) → JsonNodeVerifies the signature and parses the event in one step. Fails if the signature is wrong.
Throws IllegalArgumentException when the signature doesn't match: answer 400 and ignore the request.
Example
@PostMapping("/webhooks/runconvert")
ResponseEntity<Void> webhook(@RequestBody byte[] body,
@RequestHeader("X-RunConvert-Signature") String signature) {
JsonNode event;
try {
event = Webhooks.constructEvent(body, signature, System.getenv("RUNCONVERT_WEBHOOK_SECRET"));
} catch (IllegalArgumentException e) {
return ResponseEntity.badRequest().build();
}
if ("job.finished".equals(event.get("event").asText())) {
log.info("done {}", event.at("/job/id").asText());
}
return ResponseEntity.ok().build();
}{
"event": "job.finished",
"job": { "id": "job_01hx4k9m2p7w", "status": "finished", … }
}Parameters
rawBodybyte[]The raw request body, exactly as received (not parsed JSON).RequiredsignatureStringThe X-RunConvert-Signature header.RequiredsecretStringYour webhook's signing secret.Required
More
Errors
Every failure is a typed error. The API's code tells you what happened, for example BILLING_INSUFFICIENT_CREDITS, UNAUTHORIZED or INVALID_DATA. All are unchecked (RuntimeException).
Example
try {
rc.convert(Path.of("report.docx"), ConvertOptions.to("pdf").outDir(Path.of("out")));
} catch (JobFailedException e) {
System.out.println("conversion failed: " + e.getTask().reason);
} catch (RunConvertException e) {
System.out.println(e.getStatus() + " " + e.getCode() + " " + e.getMessage());
}422 BILLING_INSUFFICIENT_CREDITS Insufficient credits.Error types
RunConvertExceptionclassThe API said no: getStatus() (HTTP status), getCode() (e.g. BILLING_INSUFFICIENT_CREDITS), getMessage().JobFailedExceptionclassThe job ended in error: getJob(), and getTask() with code, reason and message.WaitTimeoutExceptionclasswaitFor ran past its timeout: getJob() is the job as last seen.
Retries and timeouts
Network errors, rate limits (429) and server errors (5xx) are retried twice with backoff, honouring Retry-After. Creating a job is only retried when the request never reached the API, so a job is never created twice.
Example
RunConvert rc = RunConvert.builder()
.maxRetries(4)
.timeout(Duration.ofSeconds(30))
.build();