release: 0.31.0 (#260)

* docs: update URLs from stainlessapi.com to stainless.com (#259)

More details at https://www.stainless.com/changelog/stainless-com

* chore(internal): refactor `ErrorHandlingTest` (#264)

* feat(client): allow configuring timeouts granularly (#266)

Note that previously the `timeout(Duration)` method on the client and `RequestOptions` corresponded to connect, read, write, and request timeout. Now it only corresponds to the request timeout. Use the new `timeout(Timeout)` method to configure other timeout values granularly.

* feat(client): add file upload endpoints (#268)

chore(client)!: refactor multipart formdata impl
chore(internal): move `HttpRequestBodies` file
chore(internal): extract function for checking for lists in json fields
# Migration
1. Builder methods that used to take `contentType` and `filename` as positional parameters after the main argument now no longer do. To set a custom `contentType` or `filename`, pass `MultipartField`, which can be constructed via `MultipartField.builder()`.
2. It's unlikely you were referencing it, but `MultipartFormValue` is now called `MultipartField` if you were.

* docs: add raw response readme documentation (#269)

* chore(internal): run example files in CI (#271)

* release: 0.31.0

---------

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

Author: stainless-app[bot]

.github/workflows/ci.yml

@@ -53,4 +53,25 @@ jobs:
 
       - name: Run tests
         run: ./scripts/test
+  examples:
+    name: examples
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: |
+            8
+            17
+          cache: gradle
+      - name: Set up Gradle
+        uses: gradle/gradle-build-action@v2
 
+      - env: 
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: |
+            ./gradlew :openai-java-example:run

.release-please-manifest.json

@@ -1,3 +1,3 @@
 {
-  ".": "0.30.0"
+  ".": "0.31.0"
 }

.stats.yml

@@ -1,2 +1,2 @@
-configured_endpoints: 65
+configured_endpoints: 72
 openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai-5d30684c3118d049682ea30cdb4dbef39b97d51667da484689193dc40162af32.yml

CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.31.0 (2025-03-04)
+
+Full Changelog: [v0.30.0...v0.31.0](https://github.com/openai/openai-java/compare/v0.30.0...v0.31.0)
+
+### Features
+
+* **client:** add file upload endpoints ([#268](https://github.com/openai/openai-java/issues/268)) ([456274d](https://github.com/openai/openai-java/commit/456274d2dc572ad4711d2fc3640c7e01aa08f4b8))
+* **client:** allow configuring timeouts granularly ([#266](https://github.com/openai/openai-java/issues/266)) ([c3bc6e4](https://github.com/openai/openai-java/commit/c3bc6e4fb9717c7f6146f864ce3cc2451619c9f0))
+
+
+### Chores
+
+* **internal:** refactor `ErrorHandlingTest` ([#264](https://github.com/openai/openai-java/issues/264)) ([2472f85](https://github.com/openai/openai-java/commit/2472f859b49f49cf14539e787cf15e8f863f5dac))
+* **internal:** run example files in CI ([#271](https://github.com/openai/openai-java/issues/271)) ([8da7851](https://github.com/openai/openai-java/commit/8da785184c3e039ea4b9d2b26c6d14b607291750))
+
+
+### Documentation
+
+* add raw response readme documentation ([#269](https://github.com/openai/openai-java/issues/269)) ([2839903](https://github.com/openai/openai-java/commit/28399031c60eed8899475c5d1d38677c2eaa2284))
+* update URLs from stainlessapi.com to stainless.com ([#259](https://github.com/openai/openai-java/issues/259)) ([b824bf3](https://github.com/openai/openai-java/commit/b824bf39a44251e15c7c8b5b14bc6cbf9133dff5))
+
 ## 0.30.0 (2025-02-27)
 
 Full Changelog: [v0.29.0...v0.30.0](https://github.com/openai/openai-java/compare/v0.29.0...v0.30.0)

README.md

@@ -9,8 +9,8 @@
 
 <!-- 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/0.30.0)
-[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/0.30.0/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/0.30.0)
+[![Maven Central](https://img.shields.io/maven-central/v/com.openai/openai-java)](https://central.sonatype.com/artifact/com.openai/openai-java/0.31.0)
+[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/0.31.0/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/0.31.0)
 
 <!-- x-release-please-end -->
 
@@ -25,7 +25,7 @@ The REST API documentation can be found on [platform.openai.com](https://platfor
 ### Gradle
 
 ```kotlin
-implementation("com.openai:openai-java:0.30.0")
+implementation("com.openai:openai-java:0.31.0")
 ```
 
 ### Maven
@@ -34,7 +34,7 @@ implementation("com.openai:openai-java:0.30.0")
 <dependency>
     <groupId>com.openai</groupId>
     <artifactId>openai-java</artifactId>
-    <version>0.30.0</version>
+    <version>0.31.0</version>
 </dependency>
 ```
 
@@ -314,6 +314,37 @@ try (HttpResponse response = client.files().content(params)) {
 }
 ```
 
+## Raw responses
+
+The SDK defines methods that deserialize responses into instances of Java classes. However, these methods don't provide access to the response headers, status code, or the raw response body.
+
+To access this data, prefix any HTTP method call on a client or service with `withRawResponse()`:
+
+```java
+import com.openai.core.http.Headers;
+import com.openai.core.http.HttpResponseFor;
+import com.openai.models.ChatCompletion;
+import com.openai.models.ChatCompletionCreateParams;
+import com.openai.models.ChatModel;
+
+ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
+    .addUserMessage("Say this is a test")
+    .model(ChatModel.O3_MINI)
+    .build();
+HttpResponseFor<ChatCompletion> chatCompletion = client.chat().completions().withRawResponse().create(params);
+
+int statusCode = chatCompletion.statusCode();
+Headers headers = chatCompletion.headers();
+```
+
+You can still deserialize the response into an instance of a Java class if needed:
+
+```java
+import com.openai.models.ChatCompletion;
+
+ChatCompletion parsedChatCompletion = chatCompletion.parse();
+```
+
 ## Error handling
 
 The SDK throws custom unchecked exception types:

SECURITY.md

@@ -2,9 +2,9 @@
 
 ## Reporting Security Issues
 
-This SDK is generated by [Stainless Software Inc](http://stainlessapi.com). Stainless takes security seriously, and encourages you to report any security vulnerability promptly so that appropriate action can be taken.
+This SDK is generated by [Stainless Software Inc](http://stainless.com). Stainless takes security seriously, and encourages you to report any security vulnerability promptly so that appropriate action can be taken.
 
-To report a security issue, please contact the Stainless team at security@stainlessapi.com.
+To report a security issue, please contact the Stainless team at security@stainless.com.
 
 ## Responsible Disclosure
 

build.gradle.kts

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

openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OkHttpClient.kt

@@ -1,6 +1,7 @@
 package com.openai.client.okhttp
 
 import com.openai.core.RequestOptions
+import com.openai.core.Timeout
 import com.openai.core.checkRequired
 import com.openai.core.http.Headers
 import com.openai.core.http.HttpClient
@@ -88,13 +89,12 @@ private constructor(private val okHttpClient: okhttp3.OkHttpClient, private val
             )
         }
 
-        val timeout = requestOptions.timeout
-        if (timeout != null) {
+        requestOptions.timeout?.let {
             clientBuilder
-                .connectTimeout(timeout)
-                .readTimeout(timeout)
-                .writeTimeout(timeout)
-                .callTimeout(if (timeout.seconds == 0L) timeout else timeout.plusSeconds(30))
+                .connectTimeout(it.connect())
+                .readTimeout(it.read())
+                .writeTimeout(it.write())
+                .callTimeout(it.request())
         }
 
         val client = clientBuilder.build()
@@ -195,23 +195,24 @@ private constructor(private val okHttpClient: okhttp3.OkHttpClient, private val
     class Builder internal constructor() {
 
         private var baseUrl: HttpUrl? = null
-        // The default timeout is 10 minutes.
-        private var timeout: Duration = Duration.ofSeconds(600)
+        private var timeout: Timeout = Timeout.default()
         private var proxy: Proxy? = null
 
         fun baseUrl(baseUrl: String) = apply { this.baseUrl = baseUrl.toHttpUrl() }
 
-        fun timeout(timeout: Duration) = apply { this.timeout = timeout }
+        fun timeout(timeout: Timeout) = apply { this.timeout = timeout }
+
+        fun timeout(timeout: Duration) = timeout(Timeout.builder().request(timeout).build())
 
         fun proxy(proxy: Proxy?) = apply { this.proxy = proxy }
 
         fun build(): OkHttpClient =
             OkHttpClient(
                 okhttp3.OkHttpClient.Builder()
-                    .connectTimeout(timeout)
-                    .readTimeout(timeout)
-                    .writeTimeout(timeout)
-                    .callTimeout(if (timeout.seconds == 0L) timeout else timeout.plusSeconds(30))
+                    .connectTimeout(timeout.connect())
+                    .readTimeout(timeout.read())
+                    .writeTimeout(timeout.write())
+                    .callTimeout(timeout.request())
                     .proxy(proxy)
                     .build(),
                 checkRequired("baseUrl", baseUrl),

openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OpenAIOkHttpClient.kt

@@ -7,6 +7,7 @@ import com.openai.azure.AzureOpenAIServiceVersion
 import com.openai.client.OpenAIClient
 import com.openai.client.OpenAIClientImpl
 import com.openai.core.ClientOptions
+import com.openai.core.Timeout
 import com.openai.core.http.Headers
 import com.openai.core.http.QueryParams
 import com.openai.credential.Credential
@@ -30,8 +31,7 @@ class OpenAIOkHttpClient private constructor() {
 
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
         private var baseUrl: String = ClientOptions.PRODUCTION_URL
-        // The default timeout for the client is 10 minutes.
-        private var timeout: Duration = Duration.ofSeconds(600)
+        private var timeout: Timeout = Timeout.default()
         private var proxy: Proxy? = null
 
         fun baseUrl(baseUrl: String) = apply {
@@ -127,7 +127,19 @@ class OpenAIOkHttpClient private constructor() {
             clientOptions.removeAllQueryParams(keys)
         }
 
-        fun timeout(timeout: Duration) = apply { this.timeout = timeout }
+        fun timeout(timeout: Timeout) = apply {
+            clientOptions.timeout(timeout)
+            this.timeout = timeout
+        }
+
+        /**
+         * Sets the maximum time allowed for a complete HTTP call, not including retries.
+         *
+         * See [Timeout.request] for more details.
+         *
+         * For fine-grained control, pass a [Timeout] object.
+         */
+        fun timeout(timeout: Duration) = timeout(Timeout.builder().request(timeout).build())
 
         fun maxRetries(maxRetries: Int) = apply { clientOptions.maxRetries(maxRetries) }
 

openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OpenAIOkHttpClientAsync.kt

@@ -7,6 +7,7 @@ import com.openai.azure.AzureOpenAIServiceVersion
 import com.openai.client.OpenAIClientAsync
 import com.openai.client.OpenAIClientAsyncImpl
 import com.openai.core.ClientOptions
+import com.openai.core.Timeout
 import com.openai.core.http.Headers
 import com.openai.core.http.QueryParams
 import com.openai.credential.Credential
@@ -30,8 +31,7 @@ class OpenAIOkHttpClientAsync private constructor() {
 
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
         private var baseUrl: String = ClientOptions.PRODUCTION_URL
-        // The default timeout for the client is 10 minutes.
-        private var timeout: Duration = Duration.ofSeconds(600)
+        private var timeout: Timeout = Timeout.default()
         private var proxy: Proxy? = null
 
         fun baseUrl(baseUrl: String) = apply {
@@ -127,7 +127,19 @@ class OpenAIOkHttpClientAsync private constructor() {
             clientOptions.removeAllQueryParams(keys)
         }
 
-        fun timeout(timeout: Duration) = apply { this.timeout = timeout }
+        fun timeout(timeout: Timeout) = apply {
+            clientOptions.timeout(timeout)
+            this.timeout = timeout
+        }
+
+        /**
+         * Sets the maximum time allowed for a complete HTTP call, not including retries.
+         *
+         * See [Timeout.request] for more details.
+         *
+         * For fine-grained control, pass a [Timeout] object.
+         */
+        fun timeout(timeout: Duration) = timeout(Timeout.builder().request(timeout).build())
 
         fun maxRetries(maxRetries: Int) = apply { clientOptions.maxRetries(maxRetries) }