> ## Documentation Index
> Fetch the complete documentation index at: https://autorender.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Java

> Upload files, manage folders, and call the full Autorender API from your Java server. Requires Java 8 or later.

The `io.autorender:autorender-java` SDK is the official server-side client for Java. Use it to upload files, list and manage files and folders, run multipart uploads, and call the Autorender API from your backend.

## Prerequisites

* An Autorender account with an API key — [create one in the dashboard](https://app.autorender.io)
* Java **8** or later

## Guide

<Steps>
  <Step title="Install the package.">
    <CodeGroup>
      ```kotlin Gradle theme={null}
      implementation("io.autorender:autorender-java:0.1.2")
      ```

      ```xml Maven theme={null}
      <dependency>
        <groupId>io.autorender</groupId>
        <artifactId>autorender-java</artifactId>
        <version>0.1.2</version>
      </dependency>
      ```
    </CodeGroup>
  </Step>

  <Step title="Set your API key.">
    Create an API key in the dashboard and set it as an environment variable:

    ```bash theme={null}
    export AUTORENDER_API_KEY=your-api-key
    ```

    The client reads `AUTORENDER_API_KEY` from the environment with `fromEnv()`, or you can pass it explicitly — never hardcode the key:

    ```java theme={null}
    AutorenderClient client = AutorenderOkHttpClient.builder()
        .apiKey(System.getenv("AUTORENDER_API_KEY"))
        .build();
    ```
  </Step>

  <Step title="Upload a file.">
    Create a client and upload your first file:

    ```java {12} theme={null}
    import io.autorender.client.AutorenderClient;
    import io.autorender.client.okhttp.AutorenderOkHttpClient;
    import io.autorender.models.uploads.UploadCreateParams;
    import io.autorender.models.uploads.UploadCreateResponse;
    import java.nio.file.Paths;

    AutorenderClient client = AutorenderOkHttpClient.fromEnv();

    UploadCreateParams params = UploadCreateParams.builder()
        .fileName("chair.jpg")
        .file(Paths.get("products/chair.jpg"))
        .build();

    UploadCreateResponse upload = client.uploads().create(params);
    System.out.println(upload.fileNo());  // e.g. "fi_abc123"
    System.out.println(upload.url());     // CDN URL
    ```
  </Step>
</Steps>

## Examples

### Upload from URL

```java theme={null}
import io.autorender.models.uploads.UploadCreateFromUrlParams;

UploadCreateFromUrlParams params = UploadCreateFromUrlParams.builder()
    .remoteUrl("https://acme-assets.s3.amazonaws.com/products/chair.jpg")
    .build();

client.uploads().createFromUrl(params);
```

### List files

```java theme={null}
import io.autorender.models.files.FileListParams;
import io.autorender.models.files.FileListResponse;

FileListParams params = FileListParams.builder()
    .limit(10L)
    .build();

FileListResponse result = client.files().list(params);
result.files().forEach(file ->
    System.out.println(file.fileNo() + " " + file.name() + " " + file.url())
);
```

### Get file details

```java theme={null}
import io.autorender.models.files.FileRetrieveResponse;

FileRetrieveResponse file = client.files().retrieve("fi_abc123");
System.out.println(file.data().url());
```

### Rename a file

```java theme={null}
import io.autorender.models.files.FileRenameParams;

FileRenameParams params = FileRenameParams.builder()
    .fileNo("fi_abc123")
    .name("new-name")
    .build();

client.files().rename(params);
```

### Delete a file

```java theme={null}
client.files().delete("fi_abc123");
```

### Folders

```java theme={null}
import io.autorender.models.folders.FolderCreateParams;
import io.autorender.models.folders.FolderRenameParams;

// List folders
client.folders().list();

// Create a folder
FolderCreateParams createParams = FolderCreateParams.builder()
    .name("products")
    .build();
var folder = client.folders().create(createParams);

// Rename a folder
FolderRenameParams renameParams = FolderRenameParams.builder()
    .folderNo(folder.data().folderNo())
    .name("product-images")
    .build();
client.folders().rename(renameParams);

// Delete a folder
client.folders().delete(folder.data().folderNo());
```

### Multipart upload

For files larger than **100 MB**, use a multipart upload to split the file into parts:

```java theme={null}
import io.autorender.models.multipartuploads.MultipartUploadStartParams;
import io.autorender.models.multipartuploads.MultipartUploadCompleteParams;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import java.nio.file.Files;
import java.nio.file.Paths;

byte[] fileData = Files.readAllBytes(Paths.get("large-video.mp4"));

// Start session
MultipartUploadStartParams startParams = MultipartUploadStartParams.builder()
    .fileName("large-video.mp4")
    .fileSize((long) fileData.length)
    .build();
var session = client.multipartUploads().start(startParams);

// Upload parts
HttpClient http = HttpClient.newHttpClient();
HttpRequest req = HttpRequest.newBuilder()
    .uri(URI.create(session.parts().get(0).url()))
    .PUT(HttpRequest.BodyPublishers.ofByteArray(fileData))
    .build();
HttpResponse<Void> res = http.send(req, HttpResponse.BodyHandlers.discarding());
String etag = res.headers().firstValue("etag").orElseThrow();

// Complete
MultipartUploadCompleteParams completeParams = MultipartUploadCompleteParams.builder()
    .uploadId(session.uploadId())
    .addPart(MultipartUploadCompleteParams.Part.builder()
        .partNumber(1L)
        .etag(etag)
        .build())
    .build();
client.multipartUploads().complete(completeParams);
```

### Error handling

```java theme={null}
import io.autorender.errors.AutorenderServiceException;
import io.autorender.errors.NotFoundException;

try {
    client.files().retrieve("fi_notexist");
} catch (NotFoundException e) {
    System.out.println(e.statusCode());  // 404
    System.out.println(e.getMessage());
} catch (AutorenderServiceException e) {
    System.out.println(e.statusCode());
    System.out.println(e.getMessage());
}
```

## Resources

* [Maven Central](https://central.sonatype.com/artifact/io.autorender/autorender-java)
* [GitHub](https://github.com/autorender/autorender-java)
* [Javadoc](https://javadoc.io/doc/io.autorender/autorender-java)

## Next steps

<CardGroup cols={2}>
  <Card title="Direct upload API" icon="cloud-arrow-up" iconType="solid" href="/docs/api-reference/direct-upload">
    The upload endpoint this SDK calls.
  </Card>

  <Card title="Create an API key" icon="key" iconType="solid" href="/docs/create-an-api-key">
    Generate the key the client reads from the environment.
  </Card>

  <Card title="Image transformations" icon="wand-magic-sparkles" iconType="solid" href="/docs/transformations/introduction">
    Build delivery URLs from your uploaded files.
  </Card>

  <Card title="All SDKs" icon="cubes" iconType="solid" href="/docs/resources/sdks">
    Server-side clients for every language.
  </Card>
</CardGroup>