release: 2.18.2 (#551)

* fix(client): support structured outputs in async requests (#548). (#550)

* release: 2.18.2

---------

Co-authored-by: D Gardner <[email protected]>
Co-authored-by: stainless-app[bot] <142633134+stainless-app[bot]@users.noreply.github.com>

Author: stainless-app[bot]

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "2.18.1"
+  ".": "2.18.2"
 }

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 2.18.2 (2025-07-22)
+
+Full Changelog: [v2.18.1...v2.18.2](https://github.com/openai/openai-java/compare/v2.18.1...v2.18.2)
+
+### Bug Fixes
+
+* **client:** support structured outputs in async requests ([#548](https://github.com/openai/openai-java/issues/548)). ([#550](https://github.com/openai/openai-java/issues/550)) ([b9d52cf](https://github.com/openai/openai-java/commit/b9d52cf6e03c886dcdd5e0da3f16ea436220f09c))
+
 ## 2.18.1 (2025-07-22)
 
 Full Changelog: [v2.18.0...v2.18.1](https://github.com/openai/openai-java/compare/v2.18.0...v2.18.1)

README.md

@@ -2,16 +2,16 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.openai/openai-java)](https://central.sonatype.com/artifact/com.openai/openai-java/2.18.1)
-[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/2.18.1/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/2.18.1)
+[![Maven Central](https://img.shields.io/maven-central/v/com.openai/openai-java)](https://central.sonatype.com/artifact/com.openai/openai-java/2.18.2)
+[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/2.18.2/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/2.18.2)
 
 <!-- x-release-please-end -->
 
 The OpenAI Java SDK provides convenient access to the [OpenAI REST API](https://platform.openai.com/docs) from applications written in Java.
 
 <!-- x-release-please-start-version -->
 
-The REST API documentation can be found on [platform.openai.com](https://platform.openai.com/docs). Javadocs are available on [javadoc.io](https://javadoc.io/doc/com.openai/openai-java/2.18.1).
+The REST API documentation can be found on [platform.openai.com](https://platform.openai.com/docs). Javadocs are available on [javadoc.io](https://javadoc.io/doc/com.openai/openai-java/2.18.2).
 
 <!-- x-release-please-end -->
 
@@ -24,7 +24,7 @@ The REST API documentation can be found on [platform.openai.com](https://platfor
 ### Gradle
 
 ```kotlin
-implementation("com.openai:openai-java:2.18.1")
+implementation("com.openai:openai-java:2.18.2")
 ```
 
 ### Maven
@@ -33,7 +33,7 @@ implementation("com.openai:openai-java:2.18.1")
 <dependency>
   <groupId>com.openai</groupId>
   <artifactId>openai-java</artifactId>
-  <version>2.18.1</version>
+  <version>2.18.2</version>
 </dependency>
 ```
 
@@ -1321,7 +1321,7 @@ If you're using Spring Boot, then you can use the SDK's [Spring Boot starter](ht
 #### Gradle
 
 ```kotlin
-implementation("com.openai:openai-java-spring-boot-starter:2.18.1")
+implementation("com.openai:openai-java-spring-boot-starter:2.18.2")
 ```
 
 #### Maven
@@ -1330,7 +1330,7 @@ implementation("com.openai:openai-java-spring-boot-starter:2.18.1")
 <dependency>
   <groupId>com.openai</groupId>
   <artifactId>openai-java-spring-boot-starter</artifactId>
-  <version>2.18.1</version>
+  <version>2.18.2</version>
 </dependency>
 ```
 

build.gradle.kts

@@ -8,7 +8,7 @@ repositories {
 
 allprojects {
     group = "com.openai"
-    version = "2.18.1" // x-release-please-version
+    version = "2.18.2" // x-release-please-version
 }
 
 subprojects {

openai-java-core/src/main/kotlin/com/openai/services/async/ResponseServiceAsync.kt

@@ -15,6 +15,8 @@ import com.openai.models.responses.ResponseCreateParams
 import com.openai.models.responses.ResponseDeleteParams
 import com.openai.models.responses.ResponseRetrieveParams
 import com.openai.models.responses.ResponseStreamEvent
+import com.openai.models.responses.StructuredResponse
+import com.openai.models.responses.StructuredResponseCreateParams
 import com.openai.services.async.responses.InputItemServiceAsync
 import java.util.concurrent.CompletableFuture
 import java.util.function.Consumer
@@ -63,6 +65,30 @@ interface ResponseServiceAsync {
     fun create(requestOptions: RequestOptions): CompletableFuture<Response> =
         create(ResponseCreateParams.none(), requestOptions)
 
+    /**
+     * Creates a model response. The model's structured output in JSON form will be deserialized
+     * automatically into an instance of the class `T`. See the SDK documentation for more details.
+     *
+     * @see create
+     */
+    fun <T : Any> create(
+        params: StructuredResponseCreateParams<T>
+    ): CompletableFuture<StructuredResponse<T>> = create(params, RequestOptions.none())
+
+    /**
+     * Creates a model response. The model's structured output in JSON form will be deserialized
+     * automatically into an instance of the class `T`. See the SDK documentation for more details.
+     *
+     * @see create
+     */
+    fun <T : Any> create(
+        params: StructuredResponseCreateParams<T>,
+        requestOptions: RequestOptions = RequestOptions.none(),
+    ): CompletableFuture<StructuredResponse<T>> =
+        create(params.rawParams, requestOptions).thenApply {
+            StructuredResponse<T>(params.responseType, it)
+        }
+
     /**
      * Creates a model response. Provide [text](https://platform.openai.com/docs/guides/text) or
      * [image](https://platform.openai.com/docs/guides/images) inputs to generate
@@ -92,6 +118,26 @@ interface ResponseServiceAsync {
     fun createStreaming(requestOptions: RequestOptions): AsyncStreamResponse<ResponseStreamEvent> =
         createStreaming(ResponseCreateParams.none(), requestOptions)
 
+    /**
+     * Creates a streaming model response for the given response conversation. The input parameters
+     * can define a JSON schema derived automatically from an arbitrary class to request a
+     * structured output in JSON form. However, that structured output is split over multiple
+     * streamed events, so it will not be deserialized automatically into an instance of that class.
+     * To deserialize the output, first use a helper class to accumulate the stream of events into a
+     * single output value. See the
+     * [SDK documentation](https://github.com/openai/openai-java/#usage-with-streaming) for full
+     * details.
+     */
+    fun createStreaming(
+        params: StructuredResponseCreateParams<*>
+    ): AsyncStreamResponse<ResponseStreamEvent> = createStreaming(params, RequestOptions.none())
+
+    /** @see [createStreaming] */
+    fun createStreaming(
+        params: StructuredResponseCreateParams<*>,
+        requestOptions: RequestOptions = RequestOptions.none(),
+    ): AsyncStreamResponse<ResponseStreamEvent> = createStreaming(params.rawParams, requestOptions)
+
     /** Retrieves a model response with the given ID. */
     fun retrieve(responseId: String): CompletableFuture<Response> =
         retrieve(responseId, ResponseRetrieveParams.none())

openai-java-core/src/main/kotlin/com/openai/services/async/chat/ChatCompletionServiceAsync.kt

@@ -17,6 +17,8 @@ import com.openai.models.chat.completions.ChatCompletionListPageAsync
 import com.openai.models.chat.completions.ChatCompletionListParams
 import com.openai.models.chat.completions.ChatCompletionRetrieveParams
 import com.openai.models.chat.completions.ChatCompletionUpdateParams
+import com.openai.models.chat.completions.StructuredChatCompletion
+import com.openai.models.chat.completions.StructuredChatCompletionCreateParams
 import com.openai.services.async.chat.completions.MessageServiceAsync
 import java.util.concurrent.CompletableFuture
 import java.util.function.Consumer
@@ -64,6 +66,32 @@ interface ChatCompletionServiceAsync {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): CompletableFuture<ChatCompletion>
 
+    /**
+     * Creates a model response for the given chat conversation. The model's structured output in
+     * JSON form will be deserialized automatically into an instance of the class `T`. See the SDK
+     * documentation for more details.
+     *
+     * @see create
+     */
+    fun <T : Any> create(
+        params: StructuredChatCompletionCreateParams<T>
+    ): CompletableFuture<StructuredChatCompletion<T>> = create(params, RequestOptions.none())
+
+    /**
+     * Creates a model response for the given chat conversation. The model's structured output in
+     * JSON form will be deserialized automatically into an instance of the class `T`. See the SDK
+     * documentation for more details.
+     *
+     * @see create
+     */
+    fun <T : Any> create(
+        params: StructuredChatCompletionCreateParams<T>,
+        requestOptions: RequestOptions = RequestOptions.none(),
+    ): CompletableFuture<StructuredChatCompletion<T>> =
+        create(params.rawParams, requestOptions).thenApply {
+            StructuredChatCompletion<T>(params.responseType, it)
+        }
+
     /**
      * **Starting a new project?** We recommend trying
      * [Responses](https://platform.openai.com/docs/api-reference/responses) to take advantage of
@@ -92,6 +120,26 @@ interface ChatCompletionServiceAsync {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): AsyncStreamResponse<ChatCompletionChunk>
 
+    /**
+     * Creates a streaming model response for the given chat conversation. The input parameters can
+     * define a JSON schema derived automatically from an arbitrary class to request a structured
+     * output in JSON form. However, that structured output is split over multiple streamed events,
+     * so it will not be deserialized automatically into an instance of that class. To deserialize
+     * the output, first use a helper class to accumulate the stream of events into a single output
+     * value. See the
+     * [SDK documentation](https://github.com/openai/openai-java/#usage-with-streaming) for full
+     * details.
+     */
+    fun createStreaming(
+        params: StructuredChatCompletionCreateParams<*>
+    ): AsyncStreamResponse<ChatCompletionChunk> = createStreaming(params, RequestOptions.none())
+
+    /** @see [createStreaming] */
+    fun createStreaming(
+        params: StructuredChatCompletionCreateParams<*>,
+        requestOptions: RequestOptions = RequestOptions.none(),
+    ): AsyncStreamResponse<ChatCompletionChunk> = createStreaming(params.rawParams, requestOptions)
+
     /**
      * Get a stored chat completion. Only Chat Completions that have been created with the `store`
      * parameter set to `true` will be returned.

openai-java-core/src/main/kotlin/com/openai/services/blocking/ResponseService.kt

@@ -121,8 +121,10 @@ interface ResponseService {
      * can define a JSON schema derived automatically from an arbitrary class to request a
      * structured output in JSON form. However, that structured output is split over multiple
      * streamed events, so it will not be deserialized automatically into an instance of that class.
-     * See the [SDK documentation](https://github.com/openai/openai-java/#usage-with-streaming) for
-     * full details.
+     * To deserialize the output, first use a helper class to accumulate the stream of events into a
+     * single output value. See the
+     * [SDK documentation](https://github.com/openai/openai-java/#usage-with-streaming) for full
+     * details.
      */
     @MustBeClosed
     fun createStreaming(

openai-java-example/src/main/java/com/openai/example/ResponsesStructuredOutputsStreamingAsyncExample.java

@@ -0,0 +1,86 @@
+package com.openai.example;
+
+import com.fasterxml.jackson.annotation.JsonIgnore;
+import com.fasterxml.jackson.annotation.JsonPropertyDescription;
+import com.openai.client.OpenAIClientAsync;
+import com.openai.client.okhttp.OpenAIOkHttpClientAsync;
+import com.openai.helpers.ResponseAccumulator;
+import com.openai.models.ChatModel;
+import com.openai.models.responses.ResponseCreateParams;
+import com.openai.models.responses.StructuredResponseCreateParams;
+import java.util.List;
+
+public final class ResponsesStructuredOutputsStreamingAsyncExample {
+
+    public static class Person {
+        @JsonPropertyDescription("The first name and surname of the person.")
+        public String name;
+
+        public int birthYear;
+
+        @JsonPropertyDescription("The year the person died, or 'present' if the person is living.")
+        public String deathYear;
+
+        @Override
+        public String toString() {
+            return name + " (" + birthYear + '-' + deathYear + ')';
+        }
+    }
+
+    public static class Book {
+        public String title;
+
+        public Person author;
+
+        @JsonPropertyDescription("The year in which the book was first published.")
+        public int publicationYear;
+
+        public String genre;
+
+        @JsonIgnore
+        public String isbn;
+
+        @Override
+        public String toString() {
+            return '"' + title + "\" (" + publicationYear + ") [" + genre + "] by " + author;
+        }
+    }
+
+    public static class BookList {
+        public List<Book> books;
+    }
+
+    private ResponsesStructuredOutputsStreamingAsyncExample() {}
+
+    public static void main(String[] args) {
+        // Configure using one of:
+        // - The `OPENAI_API_KEY` environment variable
+        // - The `OPENAI_BASE_URL` and `AZURE_OPENAI_KEY` environment variables
+        OpenAIClientAsync client = OpenAIOkHttpClientAsync.fromEnv();
+
+        StructuredResponseCreateParams<BookList> createParams = ResponseCreateParams.builder()
+                .input("List some famous late twentieth century novels.")
+                .text(BookList.class)
+                .model(ChatModel.GPT_4O)
+                .build();
+
+        ResponseAccumulator accumulator = ResponseAccumulator.create();
+
+        client.responses()
+                .createStreaming(createParams)
+                .subscribe(event -> accumulator
+                        .accumulate(event)
+                        .outputTextDelta()
+                        .ifPresent(textEvent -> System.out.print(textEvent.delta())))
+                .onCompleteFuture()
+                .join();
+        System.out.println();
+
+        accumulator.response(BookList.class).output().stream()
+                .flatMap(item -> item.message().stream())
+                .flatMap(message -> message.content().stream())
+                .flatMap(content -> content.outputText().stream())
+                .flatMap(bookList -> bookList.books.stream())
+                .forEach(book -> System.out.println(" - " + book));
+    }
+}