openai/openai-java

OpenAI Java SDK – What It Is

The openai‑java repository is the official Java client library for the OpenAI REST API. It lets Java applications talk to OpenAI services (ChatGPT, DALL‑E, embeddings, etc.) without having to hand‑craft HTTP requests. The SDK handles authentication, request building, response parsing, streaming, async execution, and even integrates with Amazon Bedrock and cloud‑native workload‑identity authentication.

How to Get It

Add the library to your build – the README shows the latest version (4.81.0 at the time of writing):

Gradle (Kotlin DSL)

implementation("com.openai:openai-java:4.81.0")

Maven

<dependency>
  <groupId>com.openai</groupId>
  <artifactId>openai-java</artifactId>
  <version>4.81.0</version>
</dependency>

The SDK requires Java 8 or newer.

Quick‑Start Example

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.ChatModel;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

// Reads API key etc. from environment variables
OpenAIClient client = OpenAIOkHttpClient.fromEnv();

ResponseCreateParams params = ResponseCreateParams.builder()
        .input("Say this is a test")
        .model(ChatModel.GPT_5_2)
        .build();

Response response = client.responses().create(params);
System.out.println(response);

The same pattern works for the classic Chat Completions endpoint:

ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
    .addUserMessage("Say this is a test")
    .model(ChatModel.GPT_5_2)
    .build();
ChatCompletion chat = client.chat().completions().create(params);
System.out.println(chat);

Key Features

Feature	What It Gives You
Synchronous & Asynchronous APIs	Call `client` for blocking calls or `client.async()` for `CompletableFuture`‑based non‑blocking calls.
Streaming support	Receive partial results as they arrive via `createStreaming` methods, with helper classes (`ChatCompletionAccumulator`) to re‑assemble the final object.
Immutable model objects	All request/response objects are built with builders and are immutable once created, making them safe to share across threads.
Configurable authentication	API keys can be supplied via environment variables, system properties, or workload‑identity mechanisms (Kubernetes service‑account tokens, Azure Managed Identity, GCP ID tokens, or X.509 client certificates).
Amazon Bedrock integration	An optional `openai-java-bedrock` artifact lets you call OpenAI‑compatible models hosted on Bedrock using normal AWS credentials.
Client pooling	The SDK re‑uses a single `OpenAIClient` (connection pool + thread pool). The README advises creating only one client per application.
Fine‑grained options	Use `withOptions` to temporarily tweak settings (base URL, retry count, etc.) while keeping the underlying pools intact.
Java‑centric ergonomics	Builders, type‑safe enums (`ChatModel.GPT_5_2`), and comprehensive Javadoc make the API feel native to Java developers.

Configuration Details

Authentication can be supplied in three ways:

Environment variables – OPENAI_API_KEY, OPENAI_ORG_ID, OPENAI_PROJECT_ID, etc.
System properties – openai.apiKey, openai.orgId, … (properties win over env vars).
Programmatic builder – OpenAIOkHttpClient.builder().apiKey("…").adminApiKey("…").build();

All options are listed in a table in the README, with baseUrl defaulting to https://api.openai.com/v1.

Advanced Use Cases

Workload Identity – The SDK can exchange short‑lived tokens from Kubernetes, Azure, or GCP for OpenAI access tokens, removing the need to store long‑lived API keys.
X.509 Mutual TLS – For highly regulated environments, you can provide a client certificate and private key; the SDK will perform a token exchange over a mutual‑TLS channel.
Custom Executors for Streaming – Override the default thread pool used for async streaming by passing your own Executor to subscribe or via streamHandlerExecutor on the client builder.

Where to Find More

Full Javadoc – https://javadoc.io/doc/com.openai/openai-java
Example code – See the openai-java-example module for runnable demos of chat, streaming, async, and workload‑identity usage.
Contribution guide – CONTRIBUTING.md explains how to set up the development JDK, run linting, and submit PRs.
Version support policy – docs/version-support-policy.md lists which Java versions each artifact supports.

TL;DR

openai-java is a production‑ready, officially maintained Java SDK that abstracts the OpenAI HTTP API into idiomatic Java objects. It supports synchronous, asynchronous, and streaming calls, works with standard API keys or cloud‑native workload‑identity tokens, and even lets you call OpenAI‑compatible models on Amazon Bedrock. Add it to your Maven/Gradle project, configure your key, and start sending prompts to GPT‑5‑style models in a few lines of code.