From 41182d164e3739af338ad8f6d17955792c3a48a5 Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Tue, 17 Feb 2026 18:01:38 +0000
Subject: [PATCH 1/8] chore(internal): update `TestServerExtension` comment

---
 .../kotlin/com/openai/TestServerExtension.kt    | 17 ++---------------
 1 file changed, 2 insertions(+), 15 deletions(-)

diff --git a/openai-java-core/src/test/kotlin/com/openai/TestServerExtension.kt b/openai-java-core/src/test/kotlin/com/openai/TestServerExtension.kt
index 7dfdef2b1..dbbc3f07c 100644
--- a/openai-java-core/src/test/kotlin/com/openai/TestServerExtension.kt
+++ b/openai-java-core/src/test/kotlin/com/openai/TestServerExtension.kt
@@ -15,25 +15,12 @@ class TestServerExtension : BeforeAllCallback, ExecutionCondition {
         } catch (e: Exception) {
             throw RuntimeException(
                 """
-                The test suite will not run without a mock Prism server running against your OpenAPI spec.
+                The test suite will not run without a mock server running against your OpenAPI spec.
 
                 You can set the environment variable `SKIP_MOCK_TESTS` to `true` to skip running any tests
                 that require the mock server.
 
-                To fix:
-
-                1. Install Prism (requires Node 16+):
-
-                  With npm:
-                    $ npm install -g @stoplight/prism-cli
-
-                  With yarn:
-                    $ yarn global add @stoplight/prism-cli
-
-                2. Run the mock server
-
-                  To run the server, pass in the path of your OpenAPI spec to the prism command:
-                    $ prism mock path/to/your.openapi.yml
+                To fix run `./scripts/mock` in a separate terminal.
                 """
                     .trimIndent(),
                 e,

From 360edde0e5ea5d0ee30c926905a950db3e14b6fa Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Tue, 17 Feb 2026 18:13:47 +0000
Subject: [PATCH 2/8] chore(internal): remove unnecessary base URL

---
 .../com/openai/services/async/WebhookServiceAsyncTest.kt    | 6 +-----
 .../com/openai/services/blocking/WebhookServiceTest.kt      | 6 +-----
 2 files changed, 2 insertions(+), 10 deletions(-)

diff --git a/openai-java-core/src/test/kotlin/com/openai/services/async/WebhookServiceAsyncTest.kt b/openai-java-core/src/test/kotlin/com/openai/services/async/WebhookServiceAsyncTest.kt
index f7325c5f9..392d1b7cf 100644
--- a/openai-java-core/src/test/kotlin/com/openai/services/async/WebhookServiceAsyncTest.kt
+++ b/openai-java-core/src/test/kotlin/com/openai/services/async/WebhookServiceAsyncTest.kt
@@ -59,11 +59,7 @@ internal class WebhookServiceAsyncTest {
 
     @Test
     fun unwrapWithoutSecretShouldThrow() {
-        val client =
-            OpenAIOkHttpClientAsync.builder()
-                .baseUrl(TestServerExtension.BASE_URL)
-                .apiKey("My API Key")
-                .build()
+        val client = OpenAIOkHttpClientAsync.builder().apiKey("My API Key").build()
         val webhookServiceAsync = client.webhooks()
 
         val headers =
diff --git a/openai-java-core/src/test/kotlin/com/openai/services/blocking/WebhookServiceTest.kt b/openai-java-core/src/test/kotlin/com/openai/services/blocking/WebhookServiceTest.kt
index 72f417683..b17da5d15 100644
--- a/openai-java-core/src/test/kotlin/com/openai/services/blocking/WebhookServiceTest.kt
+++ b/openai-java-core/src/test/kotlin/com/openai/services/blocking/WebhookServiceTest.kt
@@ -72,11 +72,7 @@ internal class WebhookServiceTest {
 
     @Test
     fun unwrapWithoutSecretShouldThrow() {
-        val client =
-            OpenAIOkHttpClient.builder()
-                .baseUrl(TestServerExtension.BASE_URL)
-                .apiKey("My API Key")
-                .build()
+        val client = OpenAIOkHttpClient.builder().apiKey("My API Key").build()
         val webhookService = client.webhooks()
 
         val exception =

From f5018f5bfc839b22397d184c18fc5a359fabd430 Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Wed, 18 Feb 2026 02:31:18 +0000
Subject: [PATCH 3/8] docs(api): update docstrings across audio, chatkit,
 skills, videos, and other endpoints

---
 .stats.yml                                     |  4 ++--
 .../models/audio/speech/SpeechCreateParams.kt  |  6 +++++-
 .../TranscriptionCreateParams.kt               |  7 ++++++-
 .../chatkit/sessions/SessionCancelParams.kt    |  6 +++++-
 .../chatkit/sessions/SessionCreateParams.kt    |  2 +-
 .../beta/chatkit/threads/ThreadDeleteParams.kt |  2 +-
 .../chatkit/threads/ThreadListItemsParams.kt   |  2 +-
 .../beta/chatkit/threads/ThreadListParams.kt   |  2 +-
 .../chatkit/threads/ThreadRetrieveParams.kt    |  2 +-
 .../completions/ChatCompletionCreateParams.kt  |  3 +++
 .../completions/CompletionCreateParams.kt      |  6 +++++-
 .../clientsecrets/ClientSecretCreateParams.kt  | 18 +++++++++++++++++-
 .../models/responses/ResponseCompactParams.kt  |  9 ++++++++-
 .../inputtokens/InputTokenCountParams.kt       |  6 +++++-
 .../openai/models/skills/SkillCreateParams.kt  |  2 +-
 .../openai/models/skills/SkillDeleteParams.kt  |  2 +-
 .../openai/models/skills/SkillListParams.kt    |  2 +-
 .../models/skills/SkillRetrieveParams.kt       |  2 +-
 .../openai/models/skills/SkillUpdateParams.kt  |  2 +-
 .../skills/content/ContentRetrieveParams.kt    |  2 +-
 .../skills/versions/VersionCreateParams.kt     |  2 +-
 .../skills/versions/VersionDeleteParams.kt     |  2 +-
 .../skills/versions/VersionListParams.kt       |  2 +-
 .../skills/versions/VersionRetrieveParams.kt   |  2 +-
 .../versions/content/ContentRetrieveParams.kt  |  2 +-
 .../models/uploads/UploadCancelParams.kt       |  6 +++++-
 .../models/uploads/UploadCompleteParams.kt     |  4 +++-
 .../models/uploads/UploadCreateParams.kt       |  2 ++
 .../openai/models/videos/VideoCreateParams.kt  |  2 +-
 .../openai/models/videos/VideoDeleteParams.kt  |  2 +-
 .../videos/VideoDownloadContentParams.kt       |  6 +++++-
 .../openai/models/videos/VideoListParams.kt    |  2 +-
 .../openai/models/videos/VideoRemixParams.kt   |  2 +-
 .../models/videos/VideoRetrieveParams.kt       |  2 +-
 .../services/async/CompletionServiceAsync.kt   | 12 ++++++++++--
 .../services/async/ResponseServiceAsync.kt     |  9 ++++++++-
 .../openai/services/async/SkillServiceAsync.kt | 10 +++++-----
 .../services/async/UploadServiceAsync.kt       | 11 +++++++++--
 .../openai/services/async/VideoServiceAsync.kt | 16 ++++++++++------
 .../services/async/audio/SpeechServiceAsync.kt |  6 +++++-
 .../async/audio/TranscriptionServiceAsync.kt   | 14 ++++++++++++--
 .../async/beta/chatkit/SessionServiceAsync.kt  |  8 ++++++--
 .../async/beta/chatkit/ThreadServiceAsync.kt   |  8 ++++----
 .../async/chat/ChatCompletionServiceAsync.kt   |  6 ++++++
 .../async/realtime/ClientSecretServiceAsync.kt | 18 +++++++++++++++++-
 .../async/responses/InputTokenServiceAsync.kt  |  6 +++++-
 .../async/skills/ContentServiceAsync.kt        |  2 +-
 .../async/skills/VersionServiceAsync.kt        |  8 ++++----
 .../skills/versions/ContentServiceAsync.kt     |  2 +-
 .../services/blocking/CompletionService.kt     | 12 ++++++++++--
 .../services/blocking/ResponseService.kt       |  9 ++++++++-
 .../openai/services/blocking/SkillService.kt   | 10 +++++-----
 .../openai/services/blocking/UploadService.kt  | 11 +++++++++--
 .../openai/services/blocking/VideoService.kt   | 16 ++++++++++------
 .../services/blocking/audio/SpeechService.kt   |  6 +++++-
 .../blocking/audio/TranscriptionService.kt     | 14 ++++++++++++--
 .../blocking/beta/chatkit/SessionService.kt    |  8 ++++++--
 .../blocking/beta/chatkit/ThreadService.kt     |  8 ++++----
 .../blocking/chat/ChatCompletionService.kt     |  6 ++++++
 .../blocking/realtime/ClientSecretService.kt   | 18 +++++++++++++++++-
 .../blocking/responses/InputTokenService.kt    |  6 +++++-
 .../services/blocking/skills/ContentService.kt |  2 +-
 .../services/blocking/skills/VersionService.kt |  8 ++++----
 .../blocking/skills/versions/ContentService.kt |  2 +-
 64 files changed, 298 insertions(+), 99 deletions(-)

diff --git a/.stats.yml b/.stats.yml
index 2eb104c35..0568092aa 100644
--- a/.stats.yml
+++ b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 147
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-0db5326a0fb6a30ffad9242c72872c3388ef927e8a4549ddd20aec3420541209.yml
-openapi_spec_hash: 9523fe30739802e15c88f4e7aac44e7f
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-c20486f46004d6be2d280d7792c64d47fcea3e5b7fbbb50d3ffc6241aba653df.yml
+openapi_spec_hash: bf1dbabc5a923d897309273183525c02
 config_hash: 948733484caf41e71093c6582dbc319c
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/audio/speech/SpeechCreateParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/audio/speech/SpeechCreateParams.kt
index f3be773de..0983dc9a0 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/audio/speech/SpeechCreateParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/audio/speech/SpeechCreateParams.kt
@@ -21,7 +21,11 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Generates audio from the input text. */
+/**
+ * Generates audio from the input text.
+ *
+ * Returns the audio file content, or a stream of audio events.
+ */
 class SpeechCreateParams
 private constructor(
     private val body: Body,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/audio/transcriptions/TranscriptionCreateParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/audio/transcriptions/TranscriptionCreateParams.kt
index ebccd5c09..2efe394d5 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/audio/transcriptions/TranscriptionCreateParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/audio/transcriptions/TranscriptionCreateParams.kt
@@ -34,7 +34,12 @@ import kotlin.io.path.inputStream
 import kotlin.io.path.name
 import kotlin.jvm.optionals.getOrNull
 
-/** Transcribes audio into the input language. */
+/**
+ * Transcribes audio into the input language.
+ *
+ * Returns a transcription object in `json`, `diarized_json`, or `verbose_json` format, or a stream
+ * of transcript events.
+ */
 class TranscriptionCreateParams
 private constructor(
     private val body: Body,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/sessions/SessionCancelParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/sessions/SessionCancelParams.kt
index d5cadea11..7cf8abee7 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/sessions/SessionCancelParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/sessions/SessionCancelParams.kt
@@ -11,7 +11,11 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Cancel a ChatKit session */
+/**
+ * Cancel an active ChatKit session and return its most recent metadata.
+ *
+ * Cancelling prevents new requests from using the issued client secret.
+ */
 class SessionCancelParams
 private constructor(
     private val sessionId: String?,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/sessions/SessionCreateParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/sessions/SessionCreateParams.kt
index c2a9a4b16..f5880fdae 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/sessions/SessionCreateParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/sessions/SessionCreateParams.kt
@@ -24,7 +24,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Create a ChatKit session */
+/** Create a ChatKit session. */
 class SessionCreateParams
 private constructor(
     private val body: Body,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/threads/ThreadDeleteParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/threads/ThreadDeleteParams.kt
index 44976cad5..fdf90a7c6 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/threads/ThreadDeleteParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/threads/ThreadDeleteParams.kt
@@ -11,7 +11,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Delete a ChatKit thread */
+/** Delete a ChatKit thread along with its items and stored attachments. */
 class ThreadDeleteParams
 private constructor(
     private val threadId: String?,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/threads/ThreadListItemsParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/threads/ThreadListItemsParams.kt
index 96c164986..ebbeef984 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/threads/ThreadListItemsParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/threads/ThreadListItemsParams.kt
@@ -13,7 +13,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** List ChatKit thread items */
+/** List items that belong to a ChatKit thread. */
 class ThreadListItemsParams
 private constructor(
     private val threadId: String?,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/threads/ThreadListParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/threads/ThreadListParams.kt
index 3c0d94f50..d4f277f59 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/threads/ThreadListParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/threads/ThreadListParams.kt
@@ -13,7 +13,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** List ChatKit threads */
+/** List ChatKit threads with optional pagination and user filters. */
 class ThreadListParams
 private constructor(
     private val after: String?,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/threads/ThreadRetrieveParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/threads/ThreadRetrieveParams.kt
index fe70c6cf0..e7d28fa0d 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/threads/ThreadRetrieveParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/beta/chatkit/threads/ThreadRetrieveParams.kt
@@ -9,7 +9,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Retrieve a ChatKit thread */
+/** Retrieve a ChatKit thread by its identifier. */
 class ThreadRetrieveParams
 private constructor(
     private val threadId: String?,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionCreateParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionCreateParams.kt
index 3a4d33af7..4e66cb423 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionCreateParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionCreateParams.kt
@@ -60,6 +60,9 @@ import kotlin.jvm.optionals.getOrNull
  * for newer reasoning models. Parameters that are only supported for reasoning models are noted
  * below. For the current state of unsupported parameters in reasoning models,
  * [refer to the reasoning guide](https://platform.openai.com/docs/guides/reasoning).
+ *
+ * Returns a chat completion object, or a streamed sequence of chat completion chunk objects if the
+ * request is streamed.
  */
 class ChatCompletionCreateParams
 private constructor(
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/completions/CompletionCreateParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/completions/CompletionCreateParams.kt
index bfcd2d128..3bac4ec72 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/completions/CompletionCreateParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/completions/CompletionCreateParams.kt
@@ -34,7 +34,11 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Creates a completion for the provided prompt and parameters. */
+/**
+ * Creates a completion for the provided prompt and parameters.
+ *
+ * Returns a completion object, or a sequence of completion objects if the request is streamed.
+ */
 class CompletionCreateParams
 private constructor(
     private val body: Body,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/realtime/clientsecrets/ClientSecretCreateParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/realtime/clientsecrets/ClientSecretCreateParams.kt
index e892b2fc6..531bb4f32 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/realtime/clientsecrets/ClientSecretCreateParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/realtime/clientsecrets/ClientSecretCreateParams.kt
@@ -32,7 +32,23 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Create a Realtime client secret with an associated session configuration. */
+/**
+ * Create a Realtime client secret with an associated session configuration.
+ *
+ * Client secrets are short-lived tokens that can be passed to a client app, such as a web frontend
+ * or mobile client, which grants access to the Realtime API without leaking your main API key. You
+ * can configure a custom TTL for each client secret.
+ *
+ * You can also attach session configuration options to the client secret, which will be applied to
+ * any sessions created using that client secret, but these can also be overridden by the client
+ * connection.
+ *
+ * [Learn more about authentication with client secrets over
+ * WebRTC](https://platform.openai.com/docs/guides/realtime-webrtc).
+ *
+ * Returns the created client secret and the effective session object. The client secret is a string
+ * that looks like `ek_1234`.
+ */
 class ClientSecretCreateParams
 private constructor(
     private val body: Body,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseCompactParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseCompactParams.kt
index 88c43f69c..c8738e56a 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseCompactParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/responses/ResponseCompactParams.kt
@@ -33,7 +33,14 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Compact conversation */
+/**
+ * Compact a conversation. Returns a compacted response object.
+ *
+ * Learn when and how to compact long-running conversations in the
+ * [conversation state guide](https://platform.openai.com/docs/guides/conversation-state#managing-the-context-window).
+ * For ZDR-compatible compaction details, see
+ * [Compaction (advanced)](https://platform.openai.com/docs/guides/conversation-state#compaction-advanced).
+ */
 class ResponseCompactParams
 private constructor(
     private val body: Body,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/responses/inputtokens/InputTokenCountParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/responses/inputtokens/InputTokenCountParams.kt
index ddf647e9c..882460fd3 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/responses/inputtokens/InputTokenCountParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/responses/inputtokens/InputTokenCountParams.kt
@@ -57,7 +57,11 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Get input token counts */
+/**
+ * Returns input token counts of the request.
+ *
+ * Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count.
+ */
 class InputTokenCountParams
 private constructor(
     private val body: Body,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillCreateParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillCreateParams.kt
index 841227b48..ee8e0b548 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillCreateParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillCreateParams.kt
@@ -26,7 +26,7 @@ import java.util.Optional
 import kotlin.io.path.inputStream
 import kotlin.io.path.name
 
-/** Create Skill */
+/** Create a new skill. */
 class SkillCreateParams
 private constructor(
     private val body: Body,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillDeleteParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillDeleteParams.kt
index ab90810a3..8fb1915e4 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillDeleteParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillDeleteParams.kt
@@ -11,7 +11,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Delete Skill */
+/** Delete a skill by its ID. */
 class SkillDeleteParams
 private constructor(
     private val skillId: String?,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillListParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillListParams.kt
index ae9fde01b..ca18da014 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillListParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillListParams.kt
@@ -13,7 +13,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** List Skills */
+/** List all skills for the current project. */
 class SkillListParams
 private constructor(
     private val after: String?,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillRetrieveParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillRetrieveParams.kt
index e4ea93ec5..52e504241 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillRetrieveParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillRetrieveParams.kt
@@ -9,7 +9,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Get Skill */
+/** Get a skill by its ID. */
 class SkillRetrieveParams
 private constructor(
     private val skillId: String?,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillUpdateParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillUpdateParams.kt
index 3e97254ee..bd11b640f 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillUpdateParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/skills/SkillUpdateParams.kt
@@ -20,7 +20,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Update Skill Default Version */
+/** Update the default version pointer for a skill. */
 class SkillUpdateParams
 private constructor(
     private val skillId: String?,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/skills/content/ContentRetrieveParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/skills/content/ContentRetrieveParams.kt
index 99930a5ec..856b2735f 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/skills/content/ContentRetrieveParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/skills/content/ContentRetrieveParams.kt
@@ -9,7 +9,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Get Skill Content */
+/** Download a skill zip bundle by its ID. */
 class ContentRetrieveParams
 private constructor(
     private val skillId: String?,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/VersionCreateParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/VersionCreateParams.kt
index 469e6afd3..5db99b56e 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/VersionCreateParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/VersionCreateParams.kt
@@ -27,7 +27,7 @@ import kotlin.io.path.inputStream
 import kotlin.io.path.name
 import kotlin.jvm.optionals.getOrNull
 
-/** Create Skill Version */
+/** Create a new immutable skill version. */
 class VersionCreateParams
 private constructor(
     private val skillId: String?,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/VersionDeleteParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/VersionDeleteParams.kt
index dc2430313..2f6f26f1b 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/VersionDeleteParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/VersionDeleteParams.kt
@@ -12,7 +12,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Delete Skill Version */
+/** Delete a skill version. */
 class VersionDeleteParams
 private constructor(
     private val skillId: String,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/VersionListParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/VersionListParams.kt
index 6aeab426f..6930518f4 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/VersionListParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/VersionListParams.kt
@@ -13,7 +13,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** List Skill Versions */
+/** List skill versions for a skill. */
 class VersionListParams
 private constructor(
     private val skillId: String?,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/VersionRetrieveParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/VersionRetrieveParams.kt
index ca57e71a9..d5088e16e 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/VersionRetrieveParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/VersionRetrieveParams.kt
@@ -10,7 +10,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Get Skill Version */
+/** Get a specific skill version. */
 class VersionRetrieveParams
 private constructor(
     private val skillId: String,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/content/ContentRetrieveParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/content/ContentRetrieveParams.kt
index c4bce5803..5adfa611d 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/content/ContentRetrieveParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/skills/versions/content/ContentRetrieveParams.kt
@@ -10,7 +10,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Get Skill Version Content */
+/** Download a skill version zip bundle. */
 class ContentRetrieveParams
 private constructor(
     private val skillId: String,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/uploads/UploadCancelParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/uploads/UploadCancelParams.kt
index 7d81b03cf..4bdd76b54 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/uploads/UploadCancelParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/uploads/UploadCancelParams.kt
@@ -11,7 +11,11 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Cancels the Upload. No Parts may be added after an Upload is cancelled. */
+/**
+ * Cancels the Upload. No Parts may be added after an Upload is cancelled.
+ *
+ * Returns the Upload object with status `cancelled`.
+ */
 class UploadCancelParams
 private constructor(
     private val uploadId: String?,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/uploads/UploadCompleteParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/uploads/UploadCompleteParams.kt
index 107468399..e85fb05b9 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/uploads/UploadCompleteParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/uploads/UploadCompleteParams.kt
@@ -32,7 +32,9 @@ import kotlin.jvm.optionals.getOrNull
  * You can specify the order of the Parts by passing in an ordered list of the Part IDs.
  *
  * The number of bytes uploaded upon completion must match the number of bytes initially specified
- * when creating the Upload object. No Parts may be added after an Upload is completed.
+ * when creating the Upload object. No Parts may be added after an Upload is completed. Returns the
+ * Upload object with status `completed`, including an additional `file` property containing the
+ * created usable File object.
  */
 class UploadCompleteParams
 private constructor(
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/uploads/UploadCreateParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/uploads/UploadCreateParams.kt
index cba2807b7..c4498d9b4 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/uploads/UploadCreateParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/uploads/UploadCreateParams.kt
@@ -37,6 +37,8 @@ import kotlin.jvm.optionals.getOrNull
  *
  * For guidance on the proper filename extensions for each purpose, please follow the documentation
  * on [creating a File](https://platform.openai.com/docs/api-reference/files/create).
+ *
+ * Returns the Upload object with status `pending`.
  */
 class UploadCreateParams
 private constructor(
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoCreateParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoCreateParams.kt
index a2de32d45..74eb3b4fe 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoCreateParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoCreateParams.kt
@@ -22,7 +22,7 @@ import java.util.Optional
 import kotlin.io.path.inputStream
 import kotlin.io.path.name
 
-/** Create a video */
+/** Create a new video generation job from a prompt and optional reference assets. */
 class VideoCreateParams
 private constructor(
     private val body: Body,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoDeleteParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoDeleteParams.kt
index a1c5e19b2..f9c53fa53 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoDeleteParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoDeleteParams.kt
@@ -11,7 +11,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Delete a video */
+/** Permanently delete a completed or failed video and its stored assets. */
 class VideoDeleteParams
 private constructor(
     private val videoId: String?,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoDownloadContentParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoDownloadContentParams.kt
index 9749eeb94..2fbfba863 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoDownloadContentParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoDownloadContentParams.kt
@@ -13,7 +13,11 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Download video content */
+/**
+ * Download the generated video bytes or a derived preview asset.
+ *
+ * Streams the rendered video content for the specified video job.
+ */
 class VideoDownloadContentParams
 private constructor(
     private val videoId: String?,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoListParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoListParams.kt
index 21ac909e5..2c70c01ed 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoListParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoListParams.kt
@@ -13,7 +13,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** List videos */
+/** List recently generated videos for the current project. */
 class VideoListParams
 private constructor(
     private val after: String?,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoRemixParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoRemixParams.kt
index 7588d5d13..cf085ec9b 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoRemixParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoRemixParams.kt
@@ -19,7 +19,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Create a video remix */
+/** Create a remix of a completed video using a refreshed prompt. */
 class VideoRemixParams
 private constructor(
     private val videoId: String?,
diff --git a/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoRetrieveParams.kt b/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoRetrieveParams.kt
index 364d1a868..cc40e8f0a 100644
--- a/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoRetrieveParams.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/models/videos/VideoRetrieveParams.kt
@@ -9,7 +9,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
-/** Retrieve a video */
+/** Fetch the latest metadata for a generated video. */
 class VideoRetrieveParams
 private constructor(
     private val videoId: String?,
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/async/CompletionServiceAsync.kt b/openai-java-core/src/main/kotlin/com/openai/services/async/CompletionServiceAsync.kt
index 96dcdb47d..c0e8f7158 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/async/CompletionServiceAsync.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/async/CompletionServiceAsync.kt
@@ -27,7 +27,11 @@ interface CompletionServiceAsync {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): CompletionServiceAsync
 
-    /** Creates a completion for the provided prompt and parameters. */
+    /**
+     * Creates a completion for the provided prompt and parameters.
+     *
+     * Returns a completion object, or a sequence of completion objects if the request is streamed.
+     */
     fun create(params: CompletionCreateParams): CompletableFuture<Completion> =
         create(params, RequestOptions.none())
 
@@ -37,7 +41,11 @@ interface CompletionServiceAsync {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): CompletableFuture<Completion>
 
-    /** Creates a completion for the provided prompt and parameters. */
+    /**
+     * Creates a completion for the provided prompt and parameters.
+     *
+     * Returns a completion object, or a sequence of completion objects if the request is streamed.
+     */
     fun createStreaming(params: CompletionCreateParams): AsyncStreamResponse<Completion> =
         createStreaming(params, RequestOptions.none())
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/async/ResponseServiceAsync.kt b/openai-java-core/src/main/kotlin/com/openai/services/async/ResponseServiceAsync.kt
index edcb64591..9e07ba1fa 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/async/ResponseServiceAsync.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/async/ResponseServiceAsync.kt
@@ -280,7 +280,14 @@ interface ResponseServiceAsync {
     fun cancel(responseId: String, requestOptions: RequestOptions): CompletableFuture<Response> =
         cancel(responseId, ResponseCancelParams.none(), requestOptions)
 
-    /** Compact conversation */
+    /**
+     * Compact a conversation. Returns a compacted response object.
+     *
+     * Learn when and how to compact long-running conversations in the
+     * [conversation state guide](https://platform.openai.com/docs/guides/conversation-state#managing-the-context-window).
+     * For ZDR-compatible compaction details, see
+     * [Compaction (advanced)](https://platform.openai.com/docs/guides/conversation-state#compaction-advanced).
+     */
     fun compact(params: ResponseCompactParams): CompletableFuture<CompactedResponse> =
         compact(params, RequestOptions.none())
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/async/SkillServiceAsync.kt b/openai-java-core/src/main/kotlin/com/openai/services/async/SkillServiceAsync.kt
index 33508ee23..7659e1d31 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/async/SkillServiceAsync.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/async/SkillServiceAsync.kt
@@ -36,7 +36,7 @@ interface SkillServiceAsync {
 
     fun versions(): VersionServiceAsync
 
-    /** Create Skill */
+    /** Create a new skill. */
     fun create(): CompletableFuture<Skill> = create(SkillCreateParams.none())
 
     /** @see create */
@@ -53,7 +53,7 @@ interface SkillServiceAsync {
     fun create(requestOptions: RequestOptions): CompletableFuture<Skill> =
         create(SkillCreateParams.none(), requestOptions)
 
-    /** Get Skill */
+    /** Get a skill by its ID. */
     fun retrieve(skillId: String): CompletableFuture<Skill> =
         retrieve(skillId, SkillRetrieveParams.none())
 
@@ -85,7 +85,7 @@ interface SkillServiceAsync {
     fun retrieve(skillId: String, requestOptions: RequestOptions): CompletableFuture<Skill> =
         retrieve(skillId, SkillRetrieveParams.none(), requestOptions)
 
-    /** Update Skill Default Version */
+    /** Update the default version pointer for a skill. */
     fun update(skillId: String, params: SkillUpdateParams): CompletableFuture<Skill> =
         update(skillId, params, RequestOptions.none())
 
@@ -107,7 +107,7 @@ interface SkillServiceAsync {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): CompletableFuture<Skill>
 
-    /** List Skills */
+    /** List all skills for the current project. */
     fun list(): CompletableFuture<SkillListPageAsync> = list(SkillListParams.none())
 
     /** @see list */
@@ -125,7 +125,7 @@ interface SkillServiceAsync {
     fun list(requestOptions: RequestOptions): CompletableFuture<SkillListPageAsync> =
         list(SkillListParams.none(), requestOptions)
 
-    /** Delete Skill */
+    /** Delete a skill by its ID. */
     fun delete(skillId: String): CompletableFuture<DeletedSkill> =
         delete(skillId, SkillDeleteParams.none())
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/async/UploadServiceAsync.kt b/openai-java-core/src/main/kotlin/com/openai/services/async/UploadServiceAsync.kt
index bc3b7290c..69f99bccb 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/async/UploadServiceAsync.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/async/UploadServiceAsync.kt
@@ -48,6 +48,8 @@ interface UploadServiceAsync {
      * For guidance on the proper filename extensions for each purpose, please follow the
      * documentation on
      * [creating a File](https://platform.openai.com/docs/api-reference/files/create).
+     *
+     * Returns the Upload object with status `pending`.
      */
     fun create(params: UploadCreateParams): CompletableFuture<Upload> =
         create(params, RequestOptions.none())
@@ -58,7 +60,11 @@ interface UploadServiceAsync {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): CompletableFuture<Upload>
 
-    /** Cancels the Upload. No Parts may be added after an Upload is cancelled. */
+    /**
+     * Cancels the Upload. No Parts may be added after an Upload is cancelled.
+     *
+     * Returns the Upload object with status `cancelled`.
+     */
     fun cancel(uploadId: String): CompletableFuture<Upload> =
         cancel(uploadId, UploadCancelParams.none())
 
@@ -101,7 +107,8 @@ interface UploadServiceAsync {
      *
      * The number of bytes uploaded upon completion must match the number of bytes initially
      * specified when creating the Upload object. No Parts may be added after an Upload is
-     * completed.
+     * completed. Returns the Upload object with status `completed`, including an additional `file`
+     * property containing the created usable File object.
      */
     fun complete(uploadId: String, params: UploadCompleteParams): CompletableFuture<Upload> =
         complete(uploadId, params, RequestOptions.none())
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/async/VideoServiceAsync.kt b/openai-java-core/src/main/kotlin/com/openai/services/async/VideoServiceAsync.kt
index a375c48fd..0f6ee6fe0 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/async/VideoServiceAsync.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/async/VideoServiceAsync.kt
@@ -32,7 +32,7 @@ interface VideoServiceAsync {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): VideoServiceAsync
 
-    /** Create a video */
+    /** Create a new video generation job from a prompt and optional reference assets. */
     fun create(params: VideoCreateParams): CompletableFuture<Video> =
         create(params, RequestOptions.none())
 
@@ -42,7 +42,7 @@ interface VideoServiceAsync {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): CompletableFuture<Video>
 
-    /** Retrieve a video */
+    /** Fetch the latest metadata for a generated video. */
     fun retrieve(videoId: String): CompletableFuture<Video> =
         retrieve(videoId, VideoRetrieveParams.none())
 
@@ -74,7 +74,7 @@ interface VideoServiceAsync {
     fun retrieve(videoId: String, requestOptions: RequestOptions): CompletableFuture<Video> =
         retrieve(videoId, VideoRetrieveParams.none(), requestOptions)
 
-    /** List videos */
+    /** List recently generated videos for the current project. */
     fun list(): CompletableFuture<VideoListPageAsync> = list(VideoListParams.none())
 
     /** @see list */
@@ -92,7 +92,7 @@ interface VideoServiceAsync {
     fun list(requestOptions: RequestOptions): CompletableFuture<VideoListPageAsync> =
         list(VideoListParams.none(), requestOptions)
 
-    /** Delete a video */
+    /** Permanently delete a completed or failed video and its stored assets. */
     fun delete(videoId: String): CompletableFuture<VideoDeleteResponse> =
         delete(videoId, VideoDeleteParams.none())
 
@@ -127,7 +127,11 @@ interface VideoServiceAsync {
     ): CompletableFuture<VideoDeleteResponse> =
         delete(videoId, VideoDeleteParams.none(), requestOptions)
 
-    /** Download video content */
+    /**
+     * Download the generated video bytes or a derived preview asset.
+     *
+     * Streams the rendered video content for the specified video job.
+     */
     fun downloadContent(videoId: String): CompletableFuture<HttpResponse> =
         downloadContent(videoId, VideoDownloadContentParams.none())
 
@@ -162,7 +166,7 @@ interface VideoServiceAsync {
     ): CompletableFuture<HttpResponse> =
         downloadContent(videoId, VideoDownloadContentParams.none(), requestOptions)
 
-    /** Create a video remix */
+    /** Create a remix of a completed video using a refreshed prompt. */
     fun remix(videoId: String, params: VideoRemixParams): CompletableFuture<Video> =
         remix(videoId, params, RequestOptions.none())
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/async/audio/SpeechServiceAsync.kt b/openai-java-core/src/main/kotlin/com/openai/services/async/audio/SpeechServiceAsync.kt
index f1bd68e46..494cb792e 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/async/audio/SpeechServiceAsync.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/async/audio/SpeechServiceAsync.kt
@@ -23,7 +23,11 @@ interface SpeechServiceAsync {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): SpeechServiceAsync
 
-    /** Generates audio from the input text. */
+    /**
+     * Generates audio from the input text.
+     *
+     * Returns the audio file content, or a stream of audio events.
+     */
     fun create(params: SpeechCreateParams): CompletableFuture<HttpResponse> =
         create(params, RequestOptions.none())
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/async/audio/TranscriptionServiceAsync.kt b/openai-java-core/src/main/kotlin/com/openai/services/async/audio/TranscriptionServiceAsync.kt
index 4de3a9961..b597ab75e 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/async/audio/TranscriptionServiceAsync.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/async/audio/TranscriptionServiceAsync.kt
@@ -28,7 +28,12 @@ interface TranscriptionServiceAsync {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): TranscriptionServiceAsync
 
-    /** Transcribes audio into the input language. */
+    /**
+     * Transcribes audio into the input language.
+     *
+     * Returns a transcription object in `json`, `diarized_json`, or `verbose_json` format, or a
+     * stream of transcript events.
+     */
     fun create(params: TranscriptionCreateParams): CompletableFuture<TranscriptionCreateResponse> =
         create(params, RequestOptions.none())
 
@@ -38,7 +43,12 @@ interface TranscriptionServiceAsync {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): CompletableFuture<TranscriptionCreateResponse>
 
-    /** Transcribes audio into the input language. */
+    /**
+     * Transcribes audio into the input language.
+     *
+     * Returns a transcription object in `json`, `diarized_json`, or `verbose_json` format, or a
+     * stream of transcript events.
+     */
     fun createStreaming(
         params: TranscriptionCreateParams
     ): AsyncStreamResponse<TranscriptionStreamEvent> =
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/async/beta/chatkit/SessionServiceAsync.kt b/openai-java-core/src/main/kotlin/com/openai/services/async/beta/chatkit/SessionServiceAsync.kt
index 628f2e913..c824c6134 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/async/beta/chatkit/SessionServiceAsync.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/async/beta/chatkit/SessionServiceAsync.kt
@@ -25,7 +25,7 @@ interface SessionServiceAsync {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): SessionServiceAsync
 
-    /** Create a ChatKit session */
+    /** Create a ChatKit session. */
     fun create(params: SessionCreateParams): CompletableFuture<ChatSession> =
         create(params, RequestOptions.none())
 
@@ -35,7 +35,11 @@ interface SessionServiceAsync {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): CompletableFuture<ChatSession>
 
-    /** Cancel a ChatKit session */
+    /**
+     * Cancel an active ChatKit session and return its most recent metadata.
+     *
+     * Cancelling prevents new requests from using the issued client secret.
+     */
     fun cancel(sessionId: String): CompletableFuture<ChatSession> =
         cancel(sessionId, SessionCancelParams.none())
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/async/beta/chatkit/ThreadServiceAsync.kt b/openai-java-core/src/main/kotlin/com/openai/services/async/beta/chatkit/ThreadServiceAsync.kt
index a4894ff6e..5d3235611 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/async/beta/chatkit/ThreadServiceAsync.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/async/beta/chatkit/ThreadServiceAsync.kt
@@ -30,7 +30,7 @@ interface ThreadServiceAsync {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): ThreadServiceAsync
 
-    /** Retrieve a ChatKit thread */
+    /** Retrieve a ChatKit thread by its identifier. */
     fun retrieve(threadId: String): CompletableFuture<ChatKitThread> =
         retrieve(threadId, ThreadRetrieveParams.none())
 
@@ -65,7 +65,7 @@ interface ThreadServiceAsync {
     ): CompletableFuture<ChatKitThread> =
         retrieve(threadId, ThreadRetrieveParams.none(), requestOptions)
 
-    /** List ChatKit threads */
+    /** List ChatKit threads with optional pagination and user filters. */
     fun list(): CompletableFuture<ThreadListPageAsync> = list(ThreadListParams.none())
 
     /** @see list */
@@ -83,7 +83,7 @@ interface ThreadServiceAsync {
     fun list(requestOptions: RequestOptions): CompletableFuture<ThreadListPageAsync> =
         list(ThreadListParams.none(), requestOptions)
 
-    /** Delete a ChatKit thread */
+    /** Delete a ChatKit thread along with its items and stored attachments. */
     fun delete(threadId: String): CompletableFuture<ThreadDeleteResponse> =
         delete(threadId, ThreadDeleteParams.none())
 
@@ -118,7 +118,7 @@ interface ThreadServiceAsync {
     ): CompletableFuture<ThreadDeleteResponse> =
         delete(threadId, ThreadDeleteParams.none(), requestOptions)
 
-    /** List ChatKit thread items */
+    /** List items that belong to a ChatKit thread. */
     fun listItems(threadId: String): CompletableFuture<ThreadListItemsPageAsync> =
         listItems(threadId, ThreadListItemsParams.none())
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/async/chat/ChatCompletionServiceAsync.kt b/openai-java-core/src/main/kotlin/com/openai/services/async/chat/ChatCompletionServiceAsync.kt
index 4004f22fc..60ec49465 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/async/chat/ChatCompletionServiceAsync.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/async/chat/ChatCompletionServiceAsync.kt
@@ -56,6 +56,9 @@ interface ChatCompletionServiceAsync {
      * particularly for newer reasoning models. Parameters that are only supported for reasoning
      * models are noted below. For the current state of unsupported parameters in reasoning models,
      * [refer to the reasoning guide](https://platform.openai.com/docs/guides/reasoning).
+     *
+     * Returns a chat completion object, or a streamed sequence of chat completion chunk objects if
+     * the request is streamed.
      */
     fun create(params: ChatCompletionCreateParams): CompletableFuture<ChatCompletion> =
         create(params, RequestOptions.none())
@@ -109,6 +112,9 @@ interface ChatCompletionServiceAsync {
      * particularly for newer reasoning models. Parameters that are only supported for reasoning
      * models are noted below. For the current state of unsupported parameters in reasoning models,
      * [refer to the reasoning guide](https://platform.openai.com/docs/guides/reasoning).
+     *
+     * Returns a chat completion object, or a streamed sequence of chat completion chunk objects if
+     * the request is streamed.
      */
     fun createStreaming(
         params: ChatCompletionCreateParams
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/async/realtime/ClientSecretServiceAsync.kt b/openai-java-core/src/main/kotlin/com/openai/services/async/realtime/ClientSecretServiceAsync.kt
index c07d6d764..b71a20abe 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/async/realtime/ClientSecretServiceAsync.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/async/realtime/ClientSecretServiceAsync.kt
@@ -24,7 +24,23 @@ interface ClientSecretServiceAsync {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): ClientSecretServiceAsync
 
-    /** Create a Realtime client secret with an associated session configuration. */
+    /**
+     * Create a Realtime client secret with an associated session configuration.
+     *
+     * Client secrets are short-lived tokens that can be passed to a client app, such as a web
+     * frontend or mobile client, which grants access to the Realtime API without leaking your main
+     * API key. You can configure a custom TTL for each client secret.
+     *
+     * You can also attach session configuration options to the client secret, which will be applied
+     * to any sessions created using that client secret, but these can also be overridden by the
+     * client connection.
+     *
+     * [Learn more about authentication with client secrets over
+     * WebRTC](https://platform.openai.com/docs/guides/realtime-webrtc).
+     *
+     * Returns the created client secret and the effective session object. The client secret is a
+     * string that looks like `ek_1234`.
+     */
     fun create(): CompletableFuture<ClientSecretCreateResponse> =
         create(ClientSecretCreateParams.none())
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/async/responses/InputTokenServiceAsync.kt b/openai-java-core/src/main/kotlin/com/openai/services/async/responses/InputTokenServiceAsync.kt
index 6fb202373..d507f5cf0 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/async/responses/InputTokenServiceAsync.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/async/responses/InputTokenServiceAsync.kt
@@ -24,7 +24,11 @@ interface InputTokenServiceAsync {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): InputTokenServiceAsync
 
-    /** Get input token counts */
+    /**
+     * Returns input token counts of the request.
+     *
+     * Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count.
+     */
     fun count(): CompletableFuture<InputTokenCountResponse> = count(InputTokenCountParams.none())
 
     /** @see count */
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/async/skills/ContentServiceAsync.kt b/openai-java-core/src/main/kotlin/com/openai/services/async/skills/ContentServiceAsync.kt
index 366098225..4f00f5566 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/async/skills/ContentServiceAsync.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/async/skills/ContentServiceAsync.kt
@@ -23,7 +23,7 @@ interface ContentServiceAsync {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): ContentServiceAsync
 
-    /** Get Skill Content */
+    /** Download a skill zip bundle by its ID. */
     fun retrieve(skillId: String): CompletableFuture<HttpResponse> =
         retrieve(skillId, ContentRetrieveParams.none())
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/async/skills/VersionServiceAsync.kt b/openai-java-core/src/main/kotlin/com/openai/services/async/skills/VersionServiceAsync.kt
index 84958d935..2ce054aab 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/async/skills/VersionServiceAsync.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/async/skills/VersionServiceAsync.kt
@@ -32,7 +32,7 @@ interface VersionServiceAsync {
 
     fun content(): ContentServiceAsync
 
-    /** Create Skill Version */
+    /** Create a new immutable skill version. */
     fun create(skillId: String): CompletableFuture<SkillVersion> =
         create(skillId, VersionCreateParams.none())
 
@@ -64,7 +64,7 @@ interface VersionServiceAsync {
     fun create(skillId: String, requestOptions: RequestOptions): CompletableFuture<SkillVersion> =
         create(skillId, VersionCreateParams.none(), requestOptions)
 
-    /** Get Skill Version */
+    /** Get a specific skill version. */
     fun retrieve(version: String, params: VersionRetrieveParams): CompletableFuture<SkillVersion> =
         retrieve(version, params, RequestOptions.none())
 
@@ -86,7 +86,7 @@ interface VersionServiceAsync {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): CompletableFuture<SkillVersion>
 
-    /** List Skill Versions */
+    /** List skill versions for a skill. */
     fun list(skillId: String): CompletableFuture<VersionListPageAsync> =
         list(skillId, VersionListParams.none())
 
@@ -121,7 +121,7 @@ interface VersionServiceAsync {
     ): CompletableFuture<VersionListPageAsync> =
         list(skillId, VersionListParams.none(), requestOptions)
 
-    /** Delete Skill Version */
+    /** Delete a skill version. */
     fun delete(
         version: String,
         params: VersionDeleteParams,
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/async/skills/versions/ContentServiceAsync.kt b/openai-java-core/src/main/kotlin/com/openai/services/async/skills/versions/ContentServiceAsync.kt
index 96c8cc806..2217ab056 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/async/skills/versions/ContentServiceAsync.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/async/skills/versions/ContentServiceAsync.kt
@@ -23,7 +23,7 @@ interface ContentServiceAsync {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): ContentServiceAsync
 
-    /** Get Skill Version Content */
+    /** Download a skill version zip bundle. */
     fun retrieve(version: String, params: ContentRetrieveParams): CompletableFuture<HttpResponse> =
         retrieve(version, params, RequestOptions.none())
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/blocking/CompletionService.kt b/openai-java-core/src/main/kotlin/com/openai/services/blocking/CompletionService.kt
index e18893f8d..46bd2b4a8 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/blocking/CompletionService.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/blocking/CompletionService.kt
@@ -25,7 +25,11 @@ interface CompletionService {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): CompletionService
 
-    /** Creates a completion for the provided prompt and parameters. */
+    /**
+     * Creates a completion for the provided prompt and parameters.
+     *
+     * Returns a completion object, or a sequence of completion objects if the request is streamed.
+     */
     fun create(params: CompletionCreateParams): Completion = create(params, RequestOptions.none())
 
     /** @see create */
@@ -34,7 +38,11 @@ interface CompletionService {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): Completion
 
-    /** Creates a completion for the provided prompt and parameters. */
+    /**
+     * Creates a completion for the provided prompt and parameters.
+     *
+     * Returns a completion object, or a sequence of completion objects if the request is streamed.
+     */
     @MustBeClosed
     fun createStreaming(params: CompletionCreateParams): StreamResponse<Completion> =
         createStreaming(params, RequestOptions.none())
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/blocking/ResponseService.kt b/openai-java-core/src/main/kotlin/com/openai/services/blocking/ResponseService.kt
index e96d50e24..85416d68c 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/blocking/ResponseService.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/blocking/ResponseService.kt
@@ -271,7 +271,14 @@ interface ResponseService {
     fun cancel(responseId: String, requestOptions: RequestOptions): Response =
         cancel(responseId, ResponseCancelParams.none(), requestOptions)
 
-    /** Compact conversation */
+    /**
+     * Compact a conversation. Returns a compacted response object.
+     *
+     * Learn when and how to compact long-running conversations in the
+     * [conversation state guide](https://platform.openai.com/docs/guides/conversation-state#managing-the-context-window).
+     * For ZDR-compatible compaction details, see
+     * [Compaction (advanced)](https://platform.openai.com/docs/guides/conversation-state#compaction-advanced).
+     */
     fun compact(params: ResponseCompactParams): CompactedResponse =
         compact(params, RequestOptions.none())
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/blocking/SkillService.kt b/openai-java-core/src/main/kotlin/com/openai/services/blocking/SkillService.kt
index ea62d8140..f26a7949b 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/blocking/SkillService.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/blocking/SkillService.kt
@@ -36,7 +36,7 @@ interface SkillService {
 
     fun versions(): VersionService
 
-    /** Create Skill */
+    /** Create a new skill. */
     fun create(): Skill = create(SkillCreateParams.none())
 
     /** @see create */
@@ -53,7 +53,7 @@ interface SkillService {
     fun create(requestOptions: RequestOptions): Skill =
         create(SkillCreateParams.none(), requestOptions)
 
-    /** Get Skill */
+    /** Get a skill by its ID. */
     fun retrieve(skillId: String): Skill = retrieve(skillId, SkillRetrieveParams.none())
 
     /** @see retrieve */
@@ -80,7 +80,7 @@ interface SkillService {
     fun retrieve(skillId: String, requestOptions: RequestOptions): Skill =
         retrieve(skillId, SkillRetrieveParams.none(), requestOptions)
 
-    /** Update Skill Default Version */
+    /** Update the default version pointer for a skill. */
     fun update(skillId: String, params: SkillUpdateParams): Skill =
         update(skillId, params, RequestOptions.none())
 
@@ -100,7 +100,7 @@ interface SkillService {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): Skill
 
-    /** List Skills */
+    /** List all skills for the current project. */
     fun list(): SkillListPage = list(SkillListParams.none())
 
     /** @see list */
@@ -117,7 +117,7 @@ interface SkillService {
     fun list(requestOptions: RequestOptions): SkillListPage =
         list(SkillListParams.none(), requestOptions)
 
-    /** Delete Skill */
+    /** Delete a skill by its ID. */
     fun delete(skillId: String): DeletedSkill = delete(skillId, SkillDeleteParams.none())
 
     /** @see delete */
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/blocking/UploadService.kt b/openai-java-core/src/main/kotlin/com/openai/services/blocking/UploadService.kt
index 0aa7109f3..730f26089 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/blocking/UploadService.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/blocking/UploadService.kt
@@ -48,6 +48,8 @@ interface UploadService {
      * For guidance on the proper filename extensions for each purpose, please follow the
      * documentation on
      * [creating a File](https://platform.openai.com/docs/api-reference/files/create).
+     *
+     * Returns the Upload object with status `pending`.
      */
     fun create(params: UploadCreateParams): Upload = create(params, RequestOptions.none())
 
@@ -57,7 +59,11 @@ interface UploadService {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): Upload
 
-    /** Cancels the Upload. No Parts may be added after an Upload is cancelled. */
+    /**
+     * Cancels the Upload. No Parts may be added after an Upload is cancelled.
+     *
+     * Returns the Upload object with status `cancelled`.
+     */
     fun cancel(uploadId: String): Upload = cancel(uploadId, UploadCancelParams.none())
 
     /** @see cancel */
@@ -95,7 +101,8 @@ interface UploadService {
      *
      * The number of bytes uploaded upon completion must match the number of bytes initially
      * specified when creating the Upload object. No Parts may be added after an Upload is
-     * completed.
+     * completed. Returns the Upload object with status `completed`, including an additional `file`
+     * property containing the created usable File object.
      */
     fun complete(uploadId: String, params: UploadCompleteParams): Upload =
         complete(uploadId, params, RequestOptions.none())
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/blocking/VideoService.kt b/openai-java-core/src/main/kotlin/com/openai/services/blocking/VideoService.kt
index 55e00848a..a193e48d5 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/blocking/VideoService.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/blocking/VideoService.kt
@@ -32,7 +32,7 @@ interface VideoService {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): VideoService
 
-    /** Create a video */
+    /** Create a new video generation job from a prompt and optional reference assets. */
     fun create(params: VideoCreateParams): Video = create(params, RequestOptions.none())
 
     /** @see create */
@@ -41,7 +41,7 @@ interface VideoService {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): Video
 
-    /** Retrieve a video */
+    /** Fetch the latest metadata for a generated video. */
     fun retrieve(videoId: String): Video = retrieve(videoId, VideoRetrieveParams.none())
 
     /** @see retrieve */
@@ -68,7 +68,7 @@ interface VideoService {
     fun retrieve(videoId: String, requestOptions: RequestOptions): Video =
         retrieve(videoId, VideoRetrieveParams.none(), requestOptions)
 
-    /** List videos */
+    /** List recently generated videos for the current project. */
     fun list(): VideoListPage = list(VideoListParams.none())
 
     /** @see list */
@@ -85,7 +85,7 @@ interface VideoService {
     fun list(requestOptions: RequestOptions): VideoListPage =
         list(VideoListParams.none(), requestOptions)
 
-    /** Delete a video */
+    /** Permanently delete a completed or failed video and its stored assets. */
     fun delete(videoId: String): VideoDeleteResponse = delete(videoId, VideoDeleteParams.none())
 
     /** @see delete */
@@ -115,7 +115,11 @@ interface VideoService {
     fun delete(videoId: String, requestOptions: RequestOptions): VideoDeleteResponse =
         delete(videoId, VideoDeleteParams.none(), requestOptions)
 
-    /** Download video content */
+    /**
+     * Download the generated video bytes or a derived preview asset.
+     *
+     * Streams the rendered video content for the specified video job.
+     */
     @MustBeClosed
     fun downloadContent(videoId: String): HttpResponse =
         downloadContent(videoId, VideoDownloadContentParams.none())
@@ -152,7 +156,7 @@ interface VideoService {
     fun downloadContent(videoId: String, requestOptions: RequestOptions): HttpResponse =
         downloadContent(videoId, VideoDownloadContentParams.none(), requestOptions)
 
-    /** Create a video remix */
+    /** Create a remix of a completed video using a refreshed prompt. */
     fun remix(videoId: String, params: VideoRemixParams): Video =
         remix(videoId, params, RequestOptions.none())
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/blocking/audio/SpeechService.kt b/openai-java-core/src/main/kotlin/com/openai/services/blocking/audio/SpeechService.kt
index 0a14ac368..7c1048dbb 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/blocking/audio/SpeechService.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/blocking/audio/SpeechService.kt
@@ -23,7 +23,11 @@ interface SpeechService {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): SpeechService
 
-    /** Generates audio from the input text. */
+    /**
+     * Generates audio from the input text.
+     *
+     * Returns the audio file content, or a stream of audio events.
+     */
     @MustBeClosed
     fun create(params: SpeechCreateParams): HttpResponse = create(params, RequestOptions.none())
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/blocking/audio/TranscriptionService.kt b/openai-java-core/src/main/kotlin/com/openai/services/blocking/audio/TranscriptionService.kt
index 07b5b250a..4578e75e2 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/blocking/audio/TranscriptionService.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/blocking/audio/TranscriptionService.kt
@@ -26,7 +26,12 @@ interface TranscriptionService {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): TranscriptionService
 
-    /** Transcribes audio into the input language. */
+    /**
+     * Transcribes audio into the input language.
+     *
+     * Returns a transcription object in `json`, `diarized_json`, or `verbose_json` format, or a
+     * stream of transcript events.
+     */
     fun create(params: TranscriptionCreateParams): TranscriptionCreateResponse =
         create(params, RequestOptions.none())
 
@@ -36,7 +41,12 @@ interface TranscriptionService {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): TranscriptionCreateResponse
 
-    /** Transcribes audio into the input language. */
+    /**
+     * Transcribes audio into the input language.
+     *
+     * Returns a transcription object in `json`, `diarized_json`, or `verbose_json` format, or a
+     * stream of transcript events.
+     */
     @MustBeClosed
     fun createStreaming(
         params: TranscriptionCreateParams
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/blocking/beta/chatkit/SessionService.kt b/openai-java-core/src/main/kotlin/com/openai/services/blocking/beta/chatkit/SessionService.kt
index 9d3217616..9fd879f65 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/blocking/beta/chatkit/SessionService.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/blocking/beta/chatkit/SessionService.kt
@@ -25,7 +25,7 @@ interface SessionService {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): SessionService
 
-    /** Create a ChatKit session */
+    /** Create a ChatKit session. */
     fun create(params: SessionCreateParams): ChatSession = create(params, RequestOptions.none())
 
     /** @see create */
@@ -34,7 +34,11 @@ interface SessionService {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): ChatSession
 
-    /** Cancel a ChatKit session */
+    /**
+     * Cancel an active ChatKit session and return its most recent metadata.
+     *
+     * Cancelling prevents new requests from using the issued client secret.
+     */
     fun cancel(sessionId: String): ChatSession = cancel(sessionId, SessionCancelParams.none())
 
     /** @see cancel */
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/blocking/beta/chatkit/ThreadService.kt b/openai-java-core/src/main/kotlin/com/openai/services/blocking/beta/chatkit/ThreadService.kt
index f5d4fd57f..23d01cb0b 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/blocking/beta/chatkit/ThreadService.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/blocking/beta/chatkit/ThreadService.kt
@@ -30,7 +30,7 @@ interface ThreadService {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): ThreadService
 
-    /** Retrieve a ChatKit thread */
+    /** Retrieve a ChatKit thread by its identifier. */
     fun retrieve(threadId: String): ChatKitThread = retrieve(threadId, ThreadRetrieveParams.none())
 
     /** @see retrieve */
@@ -60,7 +60,7 @@ interface ThreadService {
     fun retrieve(threadId: String, requestOptions: RequestOptions): ChatKitThread =
         retrieve(threadId, ThreadRetrieveParams.none(), requestOptions)
 
-    /** List ChatKit threads */
+    /** List ChatKit threads with optional pagination and user filters. */
     fun list(): ThreadListPage = list(ThreadListParams.none())
 
     /** @see list */
@@ -77,7 +77,7 @@ interface ThreadService {
     fun list(requestOptions: RequestOptions): ThreadListPage =
         list(ThreadListParams.none(), requestOptions)
 
-    /** Delete a ChatKit thread */
+    /** Delete a ChatKit thread along with its items and stored attachments. */
     fun delete(threadId: String): ThreadDeleteResponse = delete(threadId, ThreadDeleteParams.none())
 
     /** @see delete */
@@ -107,7 +107,7 @@ interface ThreadService {
     fun delete(threadId: String, requestOptions: RequestOptions): ThreadDeleteResponse =
         delete(threadId, ThreadDeleteParams.none(), requestOptions)
 
-    /** List ChatKit thread items */
+    /** List items that belong to a ChatKit thread. */
     fun listItems(threadId: String): ThreadListItemsPage =
         listItems(threadId, ThreadListItemsParams.none())
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/blocking/chat/ChatCompletionService.kt b/openai-java-core/src/main/kotlin/com/openai/services/blocking/chat/ChatCompletionService.kt
index 176b3a2fc..491b62892 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/blocking/chat/ChatCompletionService.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/blocking/chat/ChatCompletionService.kt
@@ -54,6 +54,9 @@ interface ChatCompletionService {
      * particularly for newer reasoning models. Parameters that are only supported for reasoning
      * models are noted below. For the current state of unsupported parameters in reasoning models,
      * [refer to the reasoning guide](https://platform.openai.com/docs/guides/reasoning).
+     *
+     * Returns a chat completion object, or a streamed sequence of chat completion chunk objects if
+     * the request is streamed.
      */
     fun create(params: ChatCompletionCreateParams): ChatCompletion =
         create(params, RequestOptions.none())
@@ -105,6 +108,9 @@ interface ChatCompletionService {
      * particularly for newer reasoning models. Parameters that are only supported for reasoning
      * models are noted below. For the current state of unsupported parameters in reasoning models,
      * [refer to the reasoning guide](https://platform.openai.com/docs/guides/reasoning).
+     *
+     * Returns a chat completion object, or a streamed sequence of chat completion chunk objects if
+     * the request is streamed.
      */
     @MustBeClosed
     fun createStreaming(params: ChatCompletionCreateParams): StreamResponse<ChatCompletionChunk> =
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/blocking/realtime/ClientSecretService.kt b/openai-java-core/src/main/kotlin/com/openai/services/blocking/realtime/ClientSecretService.kt
index 63aa983ad..6527d67d7 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/blocking/realtime/ClientSecretService.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/blocking/realtime/ClientSecretService.kt
@@ -24,7 +24,23 @@ interface ClientSecretService {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): ClientSecretService
 
-    /** Create a Realtime client secret with an associated session configuration. */
+    /**
+     * Create a Realtime client secret with an associated session configuration.
+     *
+     * Client secrets are short-lived tokens that can be passed to a client app, such as a web
+     * frontend or mobile client, which grants access to the Realtime API without leaking your main
+     * API key. You can configure a custom TTL for each client secret.
+     *
+     * You can also attach session configuration options to the client secret, which will be applied
+     * to any sessions created using that client secret, but these can also be overridden by the
+     * client connection.
+     *
+     * [Learn more about authentication with client secrets over
+     * WebRTC](https://platform.openai.com/docs/guides/realtime-webrtc).
+     *
+     * Returns the created client secret and the effective session object. The client secret is a
+     * string that looks like `ek_1234`.
+     */
     fun create(): ClientSecretCreateResponse = create(ClientSecretCreateParams.none())
 
     /** @see create */
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/blocking/responses/InputTokenService.kt b/openai-java-core/src/main/kotlin/com/openai/services/blocking/responses/InputTokenService.kt
index 85584da4d..a09d1628c 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/blocking/responses/InputTokenService.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/blocking/responses/InputTokenService.kt
@@ -24,7 +24,11 @@ interface InputTokenService {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): InputTokenService
 
-    /** Get input token counts */
+    /**
+     * Returns input token counts of the request.
+     *
+     * Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count.
+     */
     fun count(): InputTokenCountResponse = count(InputTokenCountParams.none())
 
     /** @see count */
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/blocking/skills/ContentService.kt b/openai-java-core/src/main/kotlin/com/openai/services/blocking/skills/ContentService.kt
index 89c1df96d..bd6b3f0e4 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/blocking/skills/ContentService.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/blocking/skills/ContentService.kt
@@ -23,7 +23,7 @@ interface ContentService {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): ContentService
 
-    /** Get Skill Content */
+    /** Download a skill zip bundle by its ID. */
     @MustBeClosed
     fun retrieve(skillId: String): HttpResponse = retrieve(skillId, ContentRetrieveParams.none())
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/blocking/skills/VersionService.kt b/openai-java-core/src/main/kotlin/com/openai/services/blocking/skills/VersionService.kt
index 89d7d8e10..27ef342c1 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/blocking/skills/VersionService.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/blocking/skills/VersionService.kt
@@ -32,7 +32,7 @@ interface VersionService {
 
     fun content(): ContentService
 
-    /** Create Skill Version */
+    /** Create a new immutable skill version. */
     fun create(skillId: String): SkillVersion = create(skillId, VersionCreateParams.none())
 
     /** @see create */
@@ -61,7 +61,7 @@ interface VersionService {
     fun create(skillId: String, requestOptions: RequestOptions): SkillVersion =
         create(skillId, VersionCreateParams.none(), requestOptions)
 
-    /** Get Skill Version */
+    /** Get a specific skill version. */
     fun retrieve(version: String, params: VersionRetrieveParams): SkillVersion =
         retrieve(version, params, RequestOptions.none())
 
@@ -82,7 +82,7 @@ interface VersionService {
         requestOptions: RequestOptions = RequestOptions.none(),
     ): SkillVersion
 
-    /** List Skill Versions */
+    /** List skill versions for a skill. */
     fun list(skillId: String): VersionListPage = list(skillId, VersionListParams.none())
 
     /** @see list */
@@ -111,7 +111,7 @@ interface VersionService {
     fun list(skillId: String, requestOptions: RequestOptions): VersionListPage =
         list(skillId, VersionListParams.none(), requestOptions)
 
-    /** Delete Skill Version */
+    /** Delete a skill version. */
     fun delete(version: String, params: VersionDeleteParams): DeletedSkillVersion =
         delete(version, params, RequestOptions.none())
 
diff --git a/openai-java-core/src/main/kotlin/com/openai/services/blocking/skills/versions/ContentService.kt b/openai-java-core/src/main/kotlin/com/openai/services/blocking/skills/versions/ContentService.kt
index 7880fb3d8..2040a0889 100644
--- a/openai-java-core/src/main/kotlin/com/openai/services/blocking/skills/versions/ContentService.kt
+++ b/openai-java-core/src/main/kotlin/com/openai/services/blocking/skills/versions/ContentService.kt
@@ -23,7 +23,7 @@ interface ContentService {
      */
     fun withOptions(modifier: Consumer<ClientOptions.Builder>): ContentService
 
-    /** Get Skill Version Content */
+    /** Download a skill version zip bundle. */
     @MustBeClosed
     fun retrieve(version: String, params: ContentRetrieveParams): HttpResponse =
         retrieve(version, params, RequestOptions.none())

From ccc29673ad46a10e0ec990734c43cec5a51cb8a6 Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Wed, 18 Feb 2026 02:54:04 +0000
Subject: [PATCH 4/8] codegen metadata

---
 .stats.yml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/.stats.yml b/.stats.yml
index 0568092aa..fe36e289f 100644
--- a/.stats.yml
+++ b/.stats.yml
@@ -1,4 +1,4 @@
 configured_endpoints: 147
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-c20486f46004d6be2d280d7792c64d47fcea3e5b7fbbb50d3ffc6241aba653df.yml
-openapi_spec_hash: bf1dbabc5a923d897309273183525c02
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-a6dd5f8d7318fb1c5370d5ccb7148bacdfb3f3a665c4b85b7666e6188d9bd909.yml
+openapi_spec_hash: c4824e385a81b9021428304ccc96538f
 config_hash: 948733484caf41e71093c6582dbc319c

From eeb51c61925e9e49ce1b2994f069d89068028e00 Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Wed, 18 Feb 2026 03:03:11 +0000
Subject: [PATCH 5/8] chore(internal): update CI step name

---
 .github/workflows/create-releases.yml  | 2 +-
 .github/workflows/publish-sonatype.yml | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/create-releases.yml b/.github/workflows/create-releases.yml
index 471d34466..31b64faec 100644
--- a/.github/workflows/create-releases.yml
+++ b/.github/workflows/create-releases.yml
@@ -40,7 +40,7 @@ jobs:
         run: |
           ./gradlew :openai-java-core:compileJava :openai-java-core:compileTestJava -x test
 
-      - name: Run the Prism server
+      - name: Run the mock server
         run: |
           ./scripts/mock --daemon
 
diff --git a/.github/workflows/publish-sonatype.yml b/.github/workflows/publish-sonatype.yml
index 4f3bc29d6..23eccddc0 100644
--- a/.github/workflows/publish-sonatype.yml
+++ b/.github/workflows/publish-sonatype.yml
@@ -28,7 +28,7 @@ jobs:
         run: |
           ./gradlew :openai-java-core:compileJava :openai-java-core:compileTestJava -x test
 
-      - name: Run the Prism server
+      - name: Run the mock server
         run: |
           ./scripts/mock --daemon
 

From a1e3ca67621046ae0e2abe41e4a3f17c573c7ac1 Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Wed, 18 Feb 2026 20:50:39 +0000
Subject: [PATCH 6/8] chore(internal): make `OkHttp` constructor internal

---
 .../src/main/kotlin/com/openai/client/okhttp/OkHttpClient.kt    | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OkHttpClient.kt b/openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OkHttpClient.kt
index bd23593f9..ecd1f28ac 100644
--- a/openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OkHttpClient.kt
+++ b/openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OkHttpClient.kt
@@ -33,7 +33,7 @@ import okhttp3.logging.HttpLoggingInterceptor
 import okio.BufferedSink
 
 class OkHttpClient
-private constructor(@JvmSynthetic internal val okHttpClient: okhttp3.OkHttpClient) : HttpClient {
+internal constructor(@JvmSynthetic internal val okHttpClient: okhttp3.OkHttpClient) : HttpClient {
 
     override fun execute(request: HttpRequest, requestOptions: RequestOptions): HttpResponse {
         val call = newCall(request, requestOptions)

From 6b5fd77b364bd494b5630805f0cd62d5a381eceb Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Wed, 18 Feb 2026 23:06:42 +0000
Subject: [PATCH 7/8] feat(client): add connection pooling option

---
 README.md                                     | 19 ++++++++
 .../com/openai/client/okhttp/OkHttpClient.kt  | 42 ++++++++++++++++++
 .../client/okhttp/OpenAIOkHttpClient.kt       | 44 +++++++++++++++++++
 .../client/okhttp/OpenAIOkHttpClientAsync.kt  | 44 +++++++++++++++++++
 4 files changed, 149 insertions(+)

diff --git a/README.md b/README.md
index 8782bd66f..ce9b1be3e 100644
--- a/README.md
+++ b/README.md
@@ -1516,6 +1516,25 @@ OpenAIClient client = OpenAIOkHttpClient.builder()
     .build();
 ```
 
+### Connection pooling
+
+To customize the underlying OkHttp connection pool, configure the client using the `maxIdleConnections` and `keepAliveDuration` methods:
+
+```java
+import com.openai.client.OpenAIClient;
+import com.openai.client.okhttp.OpenAIOkHttpClient;
+import java.time.Duration;
+
+OpenAIClient client = OpenAIOkHttpClient.builder()
+    .fromEnv()
+    // If `maxIdleConnections` is set, then `keepAliveDuration` must be set, and vice versa.
+    .maxIdleConnections(10)
+    .keepAliveDuration(Duration.ofMinutes(2))
+    .build();
+```
+
+If both options are unset, OkHttp's default connection pool settings are used.
+
 ### HTTPS
 
 > [!NOTE]
diff --git a/openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OkHttpClient.kt b/openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OkHttpClient.kt
index ecd1f28ac..51c32b0c2 100644
--- a/openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OkHttpClient.kt
+++ b/openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OkHttpClient.kt
@@ -16,11 +16,13 @@ import java.time.Duration
 import java.util.concurrent.CancellationException
 import java.util.concurrent.CompletableFuture
 import java.util.concurrent.ExecutorService
+import java.util.concurrent.TimeUnit
 import javax.net.ssl.HostnameVerifier
 import javax.net.ssl.SSLSocketFactory
 import javax.net.ssl.X509TrustManager
 import okhttp3.Call
 import okhttp3.Callback
+import okhttp3.ConnectionPool
 import okhttp3.Dispatcher
 import okhttp3.HttpUrl.Companion.toHttpUrl
 import okhttp3.MediaType
@@ -200,6 +202,8 @@ internal constructor(@JvmSynthetic internal val okHttpClient: okhttp3.OkHttpClie
 
         private var timeout: Timeout = Timeout.default()
         private var proxy: Proxy? = null
+        private var maxIdleConnections: Int? = null
+        private var keepAliveDuration: Duration? = null
         private var dispatcherExecutorService: ExecutorService? = null
         private var sslSocketFactory: SSLSocketFactory? = null
         private var trustManager: X509TrustManager? = null
@@ -211,6 +215,28 @@ internal constructor(@JvmSynthetic internal val okHttpClient: okhttp3.OkHttpClie
 
         fun proxy(proxy: Proxy?) = apply { this.proxy = proxy }
 
+        /**
+         * Sets the maximum number of idle connections kept by the underlying [ConnectionPool].
+         *
+         * If this is set, then [keepAliveDuration] must also be set.
+         *
+         * If unset, then OkHttp's default is used.
+         */
+        fun maxIdleConnections(maxIdleConnections: Int?) = apply {
+            this.maxIdleConnections = maxIdleConnections
+        }
+
+        /**
+         * Sets the keep-alive duration for idle connections in the underlying [ConnectionPool].
+         *
+         * If this is set, then [maxIdleConnections] must also be set.
+         *
+         * If unset, then OkHttp's default is used.
+         */
+        fun keepAliveDuration(keepAliveDuration: Duration?) = apply {
+            this.keepAliveDuration = keepAliveDuration
+        }
+
         fun dispatcherExecutorService(dispatcherExecutorService: ExecutorService?) = apply {
             this.dispatcherExecutorService = dispatcherExecutorService
         }
@@ -240,6 +266,22 @@ internal constructor(@JvmSynthetic internal val okHttpClient: okhttp3.OkHttpClie
                     .apply {
                         dispatcherExecutorService?.let { dispatcher(Dispatcher(it)) }
 
+                        val maxIdleConnections = maxIdleConnections
+                        val keepAliveDuration = keepAliveDuration
+                        if (maxIdleConnections != null && keepAliveDuration != null) {
+                            connectionPool(
+                                ConnectionPool(
+                                    maxIdleConnections,
+                                    keepAliveDuration.toNanos(),
+                                    TimeUnit.NANOSECONDS,
+                                )
+                            )
+                        } else {
+                            check((maxIdleConnections != null) == (keepAliveDuration != null)) {
+                                "Both or none of `maxIdleConnections` and `keepAliveDuration` must be set, but only one was set"
+                            }
+                        }
+
                         val sslSocketFactory = sslSocketFactory
                         val trustManager = trustManager
                         if (sslSocketFactory != null && trustManager != null) {
diff --git a/openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OpenAIOkHttpClient.kt b/openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OpenAIOkHttpClient.kt
index 717fa06ab..49f635d05 100644
--- a/openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OpenAIOkHttpClient.kt
+++ b/openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OpenAIOkHttpClient.kt
@@ -51,6 +51,8 @@ class OpenAIOkHttpClient private constructor() {
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
         private var dispatcherExecutorService: ExecutorService? = null
         private var proxy: Proxy? = null
+        private var maxIdleConnections: Int? = null
+        private var keepAliveDuration: Duration? = null
         private var sslSocketFactory: SSLSocketFactory? = null
         private var trustManager: X509TrustManager? = null
         private var hostnameVerifier: HostnameVerifier? = null
@@ -79,6 +81,46 @@ class OpenAIOkHttpClient private constructor() {
         /** Alias for calling [Builder.proxy] with `proxy.orElse(null)`. */
         fun proxy(proxy: Optional<Proxy>) = proxy(proxy.getOrNull())
 
+        /**
+         * The maximum number of idle connections kept by the underlying OkHttp connection pool.
+         *
+         * If this is set, then [keepAliveDuration] must also be set.
+         *
+         * If unset, then OkHttp's default is used.
+         */
+        fun maxIdleConnections(maxIdleConnections: Int?) = apply {
+            this.maxIdleConnections = maxIdleConnections
+        }
+
+        /**
+         * Alias for [Builder.maxIdleConnections].
+         *
+         * This unboxed primitive overload exists for backwards compatibility.
+         */
+        fun maxIdleConnections(maxIdleConnections: Int) =
+            maxIdleConnections(maxIdleConnections as Int?)
+
+        /**
+         * Alias for calling [Builder.maxIdleConnections] with `maxIdleConnections.orElse(null)`.
+         */
+        fun maxIdleConnections(maxIdleConnections: Optional<Int>) =
+            maxIdleConnections(maxIdleConnections.getOrNull())
+
+        /**
+         * The keep-alive duration for idle connections in the underlying OkHttp connection pool.
+         *
+         * If this is set, then [maxIdleConnections] must also be set.
+         *
+         * If unset, then OkHttp's default is used.
+         */
+        fun keepAliveDuration(keepAliveDuration: Duration?) = apply {
+            this.keepAliveDuration = keepAliveDuration
+        }
+
+        /** Alias for calling [Builder.keepAliveDuration] with `keepAliveDuration.orElse(null)`. */
+        fun keepAliveDuration(keepAliveDuration: Optional<Duration>) =
+            keepAliveDuration(keepAliveDuration.getOrNull())
+
         /**
          * The socket factory used to secure HTTPS connections.
          *
@@ -360,6 +402,8 @@ class OpenAIOkHttpClient private constructor() {
                         OkHttpClient.builder()
                             .timeout(clientOptions.timeout())
                             .proxy(proxy)
+                            .maxIdleConnections(maxIdleConnections)
+                            .keepAliveDuration(keepAliveDuration)
                             .dispatcherExecutorService(dispatcherExecutorService)
                             .sslSocketFactory(sslSocketFactory)
                             .trustManager(trustManager)
diff --git a/openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OpenAIOkHttpClientAsync.kt b/openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OpenAIOkHttpClientAsync.kt
index 5ece67a8a..bbb1080f5 100644
--- a/openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OpenAIOkHttpClientAsync.kt
+++ b/openai-java-client-okhttp/src/main/kotlin/com/openai/client/okhttp/OpenAIOkHttpClientAsync.kt
@@ -51,6 +51,8 @@ class OpenAIOkHttpClientAsync private constructor() {
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
         private var dispatcherExecutorService: ExecutorService? = null
         private var proxy: Proxy? = null
+        private var maxIdleConnections: Int? = null
+        private var keepAliveDuration: Duration? = null
         private var sslSocketFactory: SSLSocketFactory? = null
         private var trustManager: X509TrustManager? = null
         private var hostnameVerifier: HostnameVerifier? = null
@@ -79,6 +81,46 @@ class OpenAIOkHttpClientAsync private constructor() {
         /** Alias for calling [Builder.proxy] with `proxy.orElse(null)`. */
         fun proxy(proxy: Optional<Proxy>) = proxy(proxy.getOrNull())
 
+        /**
+         * The maximum number of idle connections kept by the underlying OkHttp connection pool.
+         *
+         * If this is set, then [keepAliveDuration] must also be set.
+         *
+         * If unset, then OkHttp's default is used.
+         */
+        fun maxIdleConnections(maxIdleConnections: Int?) = apply {
+            this.maxIdleConnections = maxIdleConnections
+        }
+
+        /**
+         * Alias for [Builder.maxIdleConnections].
+         *
+         * This unboxed primitive overload exists for backwards compatibility.
+         */
+        fun maxIdleConnections(maxIdleConnections: Int) =
+            maxIdleConnections(maxIdleConnections as Int?)
+
+        /**
+         * Alias for calling [Builder.maxIdleConnections] with `maxIdleConnections.orElse(null)`.
+         */
+        fun maxIdleConnections(maxIdleConnections: Optional<Int>) =
+            maxIdleConnections(maxIdleConnections.getOrNull())
+
+        /**
+         * The keep-alive duration for idle connections in the underlying OkHttp connection pool.
+         *
+         * If this is set, then [maxIdleConnections] must also be set.
+         *
+         * If unset, then OkHttp's default is used.
+         */
+        fun keepAliveDuration(keepAliveDuration: Duration?) = apply {
+            this.keepAliveDuration = keepAliveDuration
+        }
+
+        /** Alias for calling [Builder.keepAliveDuration] with `keepAliveDuration.orElse(null)`. */
+        fun keepAliveDuration(keepAliveDuration: Optional<Duration>) =
+            keepAliveDuration(keepAliveDuration.getOrNull())
+
         /**
          * The socket factory used to secure HTTPS connections.
          *
@@ -360,6 +402,8 @@ class OpenAIOkHttpClientAsync private constructor() {
                         OkHttpClient.builder()
                             .timeout(clientOptions.timeout())
                             .proxy(proxy)
+                            .maxIdleConnections(maxIdleConnections)
+                            .keepAliveDuration(keepAliveDuration)
                             .dispatcherExecutorService(dispatcherExecutorService)
                             .sslSocketFactory(sslSocketFactory)
                             .trustManager(trustManager)

From 2bb435b8e37f5c6bcf8721171c9320351c007bad Mon Sep 17 00:00:00 2001
From: "stainless-app[bot]"
 <142633134+stainless-app[bot]@users.noreply.github.com>
Date: Thu, 19 Feb 2026 05:30:17 +0000
Subject: [PATCH 8/8] release: 4.22.0

---
 .release-please-manifest.json |  2 +-
 CHANGELOG.md                  | 21 +++++++++++++++++++++
 README.md                     | 14 +++++++-------
 build.gradle.kts              |  2 +-
 4 files changed, 30 insertions(+), 9 deletions(-)

diff --git a/.release-please-manifest.json b/.release-please-manifest.json
index b9e06599f..c032d3110 100644
--- a/.release-please-manifest.json
+++ b/.release-please-manifest.json
@@ -1,3 +1,3 @@
 {
-  ".": "4.21.0"
+  ".": "4.22.0"
 }
\ No newline at end of file
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6af0d9c9d..7f0c2344d 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,5 +1,26 @@
 # Changelog
 
+## 4.22.0 (2026-02-19)
+
+Full Changelog: [v4.21.0...v4.22.0](https://github.com/openai/openai-java/compare/v4.21.0...v4.22.0)
+
+### Features
+
+* **client:** add connection pooling option ([6b5fd77](https://github.com/openai/openai-java/commit/6b5fd77b364bd494b5630805f0cd62d5a381eceb))
+
+
+### Chores
+
+* **internal:** make `OkHttp` constructor internal ([a1e3ca6](https://github.com/openai/openai-java/commit/a1e3ca67621046ae0e2abe41e4a3f17c573c7ac1))
+* **internal:** remove unnecessary base URL ([360edde](https://github.com/openai/openai-java/commit/360edde0e5ea5d0ee30c926905a950db3e14b6fa))
+* **internal:** update `TestServerExtension` comment ([41182d1](https://github.com/openai/openai-java/commit/41182d164e3739af338ad8f6d17955792c3a48a5))
+* **internal:** update CI step name ([eeb51c6](https://github.com/openai/openai-java/commit/eeb51c61925e9e49ce1b2994f069d89068028e00))
+
+
+### Documentation
+
+* **api:** update docstrings across audio, chatkit, skills, videos, and other endpoints ([f5018f5](https://github.com/openai/openai-java/commit/f5018f5bfc839b22397d184c18fc5a359fabd430))
+
 ## 4.21.0 (2026-02-13)
 
 Full Changelog: [v4.20.0...v4.21.0](https://github.com/openai/openai-java/compare/v4.20.0...v4.21.0)
diff --git a/README.md b/README.md
index ce9b1be3e..9ac179bea 100644
--- a/README.md
+++ b/README.md
@@ -2,8 +2,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/4.21.0)
-[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/4.21.0/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/4.21.0)
+[![Maven Central](https://img.shields.io/maven-central/v/com.openai/openai-java)](https://central.sonatype.com/artifact/com.openai/openai-java/4.22.0)
+[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/4.22.0/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/4.22.0)
 
 <!-- x-release-please-end -->
 
@@ -11,7 +11,7 @@ The OpenAI Java SDK provides convenient access to the [OpenAI REST API](https://
 
 <!-- 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/4.21.0).
+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/4.22.0).
 
 <!-- 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:4.21.0")
+implementation("com.openai:openai-java:4.22.0")
 ```
 
 ### Maven
@@ -33,7 +33,7 @@ implementation("com.openai:openai-java:4.21.0")
 <dependency>
   <groupId>com.openai</groupId>
   <artifactId>openai-java</artifactId>
-  <version>4.21.0</version>
+  <version>4.22.0</version>
 </dependency>
 ```
 
@@ -1342,7 +1342,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:4.21.0")
+implementation("com.openai:openai-java-spring-boot-starter:4.22.0")
 ```
 
 #### Maven
@@ -1351,7 +1351,7 @@ implementation("com.openai:openai-java-spring-boot-starter:4.21.0")
 <dependency>
   <groupId>com.openai</groupId>
   <artifactId>openai-java-spring-boot-starter</artifactId>
-  <version>4.21.0</version>
+  <version>4.22.0</version>
 </dependency>
 ```
 
diff --git a/build.gradle.kts b/build.gradle.kts
index a025fa594..2918ba8ac 100644
--- a/build.gradle.kts
+++ b/build.gradle.kts
@@ -8,7 +8,7 @@ repositories {
 
 allprojects {
     group = "com.openai"
-    version = "4.21.0" // x-release-please-version
+    version = "4.22.0" // x-release-please-version
 }
 
 subprojects {