> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://fastpix.com/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://fastpix.com/docs/_mcp/server.

# FastPix Java SDK

The FastPix Java SDK is a type-safe Java client for the FastPix video API. From any Java 11+ application, built with Maven or Gradle, you can upload and manage videos, run live streams and simulcasts, create and secure playback IDs, manage playlists and signing keys, pull video analytics, and use in-video AI features. It provides both synchronous and asynchronous APIs.

\


> **Find more in the SDK reference**
>
> For all methods, runnable examples, and advanced usage, see the [FastPix Java SDK](https://github.com/FastPix/fastpix-java) on GitHub.

\


## Before you begin

Make sure you have:

* Java 11 or later (JDK)
* Maven or Gradle
* Internet access
* A FastPix account
* A FastPix Access Token and Secret Key, generated from the [FastPix Dashboard](https://dashboard.fastpix.com). See [Activate your account](/getting-started/activate-your-account).

FastPix uses HTTP Basic Authentication. The SDK maps your credentials as follows:

| SDK value  | FastPix credential |
| ---------- | ------------------ |
| `username` | Access Token       |
| `password` | Secret Key         |

> **Security:** Never commit your Access Token or Secret Key to source control. Use environment variables or a secure credential-management system.

Follow the steps below in order, and do not skip the verification steps. If a build, dependency, authentication, or first-request problem occurs, fix it before continuing. For best performance, Java 17 or later is recommended.

\


## Check your Java version

```bash
java -version
```

The output is similar to `openjdk version "17.0.8" 2023-07-18`. The SDK supports Java 11 and later. If your version is earlier than 11, install a supported JDK before continuing.

Confirm your build tool is available:

```bash
mvn -version
```

```bash
gradle -version
```

\


## Add the SDK to your project

The FastPix Java SDK is published to Maven Central as `io.fastpix:sdk`. Add it with your build tool.

Gradle, in `build.gradle`:

```groovy
dependencies {
    implementation 'io.fastpix:sdk:1.1.0'
}
```

Maven, in `pom.xml`:

```xml
<dependency>
    <groupId>io.fastpix</groupId>
    <artifactId>sdk</artifactId>
    <version>1.1.0</version>
</dependency>
```

Gradle (Kotlin DSL), in `build.gradle.kts`:

```kotlin
implementation("io.fastpix:sdk:1.1.0")
```

Refresh dependencies (`./gradlew build` or `mvn compile`) and confirm the dependency resolves on the classpath before continuing.

\


## Configure authentication

FastPix uses HTTP Basic Authentication, where `username` is your Access Token and `password` is your Secret Key. For local development, set these as environment variables so they stay out of your source code:

```bash
# macOS and Linux
export FASTPIX_USERNAME="<YOUR_ACCESS_TOKEN>"
export FASTPIX_PASSWORD="<YOUR_SECRET_KEY>"
```

```powershell
# Windows PowerShell
$env:FASTPIX_USERNAME="<YOUR_ACCESS_TOKEN>"
$env:FASTPIX_PASSWORD="<YOUR_SECRET_KEY>"
```

\


## Verify that your credentials are set

Check that both variables are set without printing their values:

```bash
# macOS and Linux
[ -n "$FASTPIX_USERNAME" ] && echo "Access Token: set" || echo "Access Token: missing"
[ -n "$FASTPIX_PASSWORD" ] && echo "Secret Key: set" || echo "Secret Key: missing"
```

Both should report `set`. If either is `missing`, set the corresponding environment variable before continuing.

\


## Initialize the FastPix client

Build the SDK client with your credentials read from the environment:

```java
// Import required classes from the FastPix SDK
import io.fastpix.sdk.FastPixSDK;
import io.fastpix.sdk.models.components.Security;

FastPixSDK sdk = FastPixSDK.builder()
    .security(Security.builder()
        .username(System.getenv("FASTPIX_USERNAME")) // Your Access Token
        .password(System.getenv("FASTPIX_PASSWORD")) // Your Secret Key
        .build())
    .build();
```

Building the client does not call the API. A request happens only when you call an operation such as `sdk.inputVideos().create().request(req).call()`.

\


## Create your first media

The easiest way to verify the integration is to create media from a publicly accessible video URL. FastPix provides a sample video at `https://static.fastpix.com/fp-sample-video.mp4`.

> **Note:** `package hello.world;` is for demonstration. When creating your own Java files, match the package name to your directory structure (for example, a file at `src/main/java/com/example/MyApp.java` uses `package com.example;`).

```java
// Package declaration - adjust to match your project's directory structure
package hello.world;

// Import required classes from the FastPix SDK
import java.lang.Exception;
import java.util.List;
import java.util.Map;
import com.fasterxml.jackson.databind.SerializationFeature;
import io.fastpix.sdk.FastPixSDK;
import io.fastpix.sdk.models.components.*;
import io.fastpix.sdk.models.operations.CreateMediaResponse;
import io.fastpix.sdk.utils.JSON;

public class Application {
    public static void main(String[] args) throws Exception {
        FastPixSDK sdk = FastPixSDK.builder()
                .security(Security.builder()
                    .username(System.getenv("FASTPIX_USERNAME"))
                    .password(System.getenv("FASTPIX_PASSWORD"))
                    .build())
            .build();
        CreateMediaRequest req = CreateMediaRequest.builder()
                .inputs(List.of(
                    Input.of(PullVideoInput.builder()
                        .url("https://static.fastpix.com/fp-sample-video.mp4")
                        .build())))
                .metadata(Map.ofEntries(
                    Map.entry("source", "fastpix-java-demo")))
                .build();
        CreateMediaResponse res = sdk.inputVideos().create()
                .request(req)
                .call();
        if (res.createMediaSuccessResponse().isPresent()) {
            var mapper = JSON.getMapper();
            mapper.enable(SerializationFeature.INDENT_OUTPUT);
            System.out.println(mapper.writeValueAsString(res.createMediaSuccessResponse().get()));
        }
    }
}
```

Compile and run `Application` with your build tool or IDE. For a Maven project with the [exec-maven-plugin](https://www.mojohaus.org/exec-maven-plugin/), run:

```bash
mvn -q compile exec:java -Dexec.mainClass="hello.world.Application"
```

A successful request returns information about the newly created media asset, similar to:

```json
{
  "success": true,
  "data": {
    "id": "..."
  }
}
```

The exact fields depend on the API response and the installed SDK version.

\


## Capture the media ID

The create-media response contains the unique ID assigned to the media asset, at `data.id`:

```json
{
  "success": true,
  "data": {
    "id": "12345678-1234-1234-1234-123456789abc"
  }
}
```

Save this value for later operations:

```text
MEDIA_ID=<value returned in data.id>
```

A `media_id` is not the same as a `playback_id`. They identify different resources and are used for different operations.

\


## Verify the integration

A successful create-media request confirms that Java is installed and supported, the `io.fastpix:sdk` dependency resolves on the classpath, your credentials are configured, the client can authenticate, and FastPix returns a media ID.

Creating media is usually the first step in a FastPix on-demand workflow: you create the media, poll it until processing finishes, then create a playback ID to play it. The initial SDK integration is now complete.

\


## Resources, error handling, and reference

The SDK is generated from the FastPix API specification, so the complete and always-current reference lives in the repo and the API docs:

* **All resources, operations, error handling, retries, server selection, custom HTTP clients, async and reactive usage, and debugging**: the [FastPix Java SDK on GitHub](https://github.com/FastPix/fastpix-java), with runnable code in the [examples](https://github.com/FastPix/fastpix-java/tree/main/examples) directory.
* **Media** (upload, manage, playback, playlists, signing keys, DRM): [Video on Demand API](https://fastpix.com/docs/video-on-demand-api/overview).
* **Live** (streams, simulcasts, live playback): [Live Stream API](https://fastpix.com/docs/live-stream-api/overview).
* **Video Data** (metrics, views, dimensions, errors): [Video Data API](https://fastpix.com/docs/video-data-api/overview).
* **In-video AI** (summaries, chapters, named entities, moderation): [In-Video AI](/in-video-ai/overview).

\


#### Frequently asked questions

The SDK is a type-safe Java wrapper around the same FastPix REST API. It handles authentication, request serialization, and response parsing for you, so you call methods like `sdk.inputVideos().create().request(req).call()` instead of building raw HTTP requests. Anything the SDK does, you can also do by calling the REST API directly. See [Create your first media](#create-your-first-media).

Add `io.fastpix:sdk` to your build: `implementation 'io.fastpix:sdk:1.1.0'` for Gradle, or the equivalent `<dependency>` for Maven. See [Add the SDK to your project](#add-the-sdk-to-your-project).

FastPix uses HTTP Basic Authentication. Build a `Security` with your Access Token as the `username` and your Secret Key as the `password`, then pass it to `FastPixSDK.builder()`. See [Initialize the FastPix client](#initialize-the-fastpix-client).

Create media from a URL or a direct upload through the input-videos resource on the client, for example `sdk.inputVideos().create()`. See [Create your first media](#create-your-first-media).

FastPix uploads are not limited by your JVM heap. When you pull from a URL, FastPix fetches the file directly, and when you upload from a device, the SDK gives you a signed URL that the file goes to directly, so the bytes never pass through your Java application. Large multi-gigabyte files upload without extra configuration. See the [Video on Demand API](https://fastpix.com/docs/video-on-demand-api/overview).

Yes. The SDK provides asynchronous APIs using `CompletableFuture` and Reactive Streams `Publisher`, so it integrates with Project Reactor, RxJava, and other reactive libraries. See the [SDK reference on GitHub](https://github.com/FastPix/fastpix-java).

Use the Live API resources to create and manage streams, simulcasts, and live playback IDs. See the [SDK reference on GitHub](https://github.com/FastPix/fastpix-java) and the [Live Stream API](https://fastpix.com/docs/live-stream-api/overview).

Generate playback IDs and manage signing keys and DRM configurations through the Media API resources. See the [SDK reference on GitHub](https://github.com/FastPix/fastpix-java) and the [Video on Demand API](https://fastpix.com/docs/video-on-demand-api/overview).

Create the media with a private access policy, then generate a signed playback ID so only holders of a valid token can play it. For stronger protection, enable DRM on the playback ID. You revoke access by deleting the playback ID. Handle all of this through the Media API resources. See the [Video on Demand API](https://fastpix.com/docs/video-on-demand-api/overview).

The Video Data API exposes metrics, views, dimensions, and errors for quality-of-experience monitoring. See the [Video Data API](https://fastpix.com/docs/video-data-api/overview).

Catch `FastpixException`, the base class for HTTP error responses, which exposes the message, status code, headers, and body. See the [SDK reference on GitHub](https://github.com/FastPix/fastpix-java) for the error types each operation can throw.

Provide a `RetryConfig` per call or at SDK initialization to control the backoff strategy. See the [SDK reference on GitHub](https://github.com/FastPix/fastpix-java).

Provide your own `HTTPClient` implementation, with custom executors, SSL context, connection pools, or request hooks, or wrap the default client. See the [SDK reference on GitHub](https://github.com/FastPix/fastpix-java).

The SDK logs through SLF4j. You can also call `enableHTTPDebugLogging(true)` on the builder for local development. See the [SDK reference on GitHub](https://github.com/FastPix/fastpix-java).

Java 11 and later (JDK). Java 17 or later is recommended. See [Before you begin](#before-you-begin).

\


## What's next

Want to go further? Browse runnable, end-to-end samples for the FastPix Java SDK in the [examples folder](https://github.com/FastPix/fastpix-java/tree/main/examples) of the GitHub repository.

\


## Release notes

For a complete history of releases, improvements, and fixes, see the [FastPix Java SDK CHANGELOG on GitHub](https://github.com/FastPix/fastpix-java/blob/main/CHANGELOG.md).