openai/openai-java

openai/openai-java

Description: The official Java library for the OpenAI API

Language: Kotlin

License: Apache-2.0

Stars: 1474

Forks: 229

Open issues: 54

Created: 2024-10-31T17:42:57Z

Pushed: 2026-06-04T17:36:45Z

Default branch: main

Fork: no

Archived: no

README:

OpenAI Java API Library


The OpenAI Java SDK provides convenient access to the OpenAI REST API from applications written in Java.

The REST API documentation can be found on platform.openai.com. Javadocs are available on javadoc.io.

Installation

[_Try openai-java-spring-boot-starter if you're using Spring Boot!_](#spring-boot)

Gradle

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

Maven

com.openai
openai-java
4.39.1

Requirements

This library requires Java 8 or later.

Usage

> [!TIP] > See the [openai-java-example](openai-java-example/src/main/java/com/openai/example) directory for complete and runnable examples!

The primary API for interacting with OpenAI models is the Responses API. You can generate text from the model with the code below.

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;

// Configures using the `OPENAI_API_KEY`, `OPENAI_ORG_ID` and `OPENAI_PROJECT_ID` 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);

The previous standard (supported indefinitely) for generating text is the Chat Completions API. You can use that API to generate text from the model with the code below.

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.ChatModel;
import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

// Configures using the `openai.apiKey`, `openai.adminKey`, `openai.orgId`, `openai.projectId`, `openai.webhookSecret` and `openai.baseUrl` system properties
// Or configures using the `OPENAI_API_KEY`, `OPENAI_ADMIN_KEY`, `OPENAI_ORG_ID`, `OPENAI_PROJECT_ID`, `OPENAI_WEBHOOK_SECRET` and `OPENAI_BASE_URL` environment variables
OpenAIClient client = OpenAIOkHttpClient.fromEnv();

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

Client configuration

Configure the client using system properties or environment variables:

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

// Configures using the `openai.apiKey`, `openai.adminKey`, `openai.orgId`, `openai.projectId`, `openai.webhookSecret` and `openai.baseUrl` system properties
// Or configures using the `OPENAI_API_KEY`, `OPENAI_ADMIN_KEY`, `OPENAI_ORG_ID`, `OPENAI_PROJECT_ID`, `OPENAI_WEBHOOK_SECRET` and `OPENAI_BASE_URL` environment variables
OpenAIClient client = OpenAIOkHttpClient.fromEnv();

Or manually:

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

OpenAIClient client = OpenAIOkHttpClient.builder()
.apiKey("My API Key")
.adminApiKey("My Admin API Key")
.build();

Or using a combination of the two approaches:

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

OpenAIClient client = OpenAIOkHttpClient.builder()
// Configures using the `openai.apiKey`, `openai.adminKey`, `openai.orgId`, `openai.projectId`, `openai.webhookSecret` and `openai.baseUrl` system properties
// Or configures using the `OPENAI_API_KEY`, `OPENAI_ADMIN_KEY`, `OPENAI_ORG_ID`, `OPENAI_PROJECT_ID`, `OPENAI_WEBHOOK_SECRET` and `OPENAI_BASE_URL` environment variables
.fromEnv()
.apiKey("My API Key")
.build();

See this table for the available options:

| Setter | System property | Environment variable | Required | Default value | | --------------- | ---------------------- | ----------------------- | -------- | ----------------------------- | | apiKey | openai.apiKey | OPENAI_API_KEY | false | - | | adminApiKey | openai.adminKey | OPENAI_ADMIN_KEY | false | - | | organization | openai.orgId | OPENAI_ORG_ID | false | - | | project | openai.projectId | OPENAI_PROJECT_ID | false | - | | webhookSecret | openai.webhookSecret | OPENAI_WEBHOOK_SECRET | false | - | | baseUrl | openai.baseUrl | OPENAI_BASE_URL | true | "https://api.openai.com/v1" |

System properties take precedence over environment variables.

> [!TIP] > Don't create more than one client in the same application. Each client has a connection pool and > thread pools, which are more efficient to share between requests.

Modifying configuration

To temporarily use a modified client configuration, while reusing the same connection and thread pools, call withOptions() on any client or service:

import com.openai.client.OpenAIClient;

OpenAIClient clientWithOptions = client.withOptions(optionsBuilder -> {
optionsBuilder.baseUrl("https://example.com");
optionsBuilder.maxRetries(42);
});

The withOptions() method does not affect the original client or service.

Workload identity authentication

Workload identity authentication allows applications running in cloud environments (Kubernetes, Azure, GCP) to authenticate using short-lived tokens issued by the cloud provider, instead of long-lived API keys.

Basic setup

import com.openai.auth.*;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;

SubjectTokenProvider provider = K8sServiceAccountTokenProvider.builder().build();

WorkloadIdentity workloadIdentity = WorkloadIdentity.builder()
.identityProviderId("your-identity-provider-id")…