release: 2.19.0 (#553)

* docs: fix missing readme comment

* feat(client): support base64 embeddings and use as default (#519)

* Add EmbeddingValue union type and Base64 support for embeddings

This implementation adds support for Base64-encoded embeddings as the default response format, while maintaining complete backward compatibility with existing `List<Float>` usage.

### 1. Default Behavior Change

- **New Default**: Embedding requests now default to Base64 encoding format
- **Backward Compatibility**: Existing code using `embedding()` method continues to work unchanged
- **Performance**: Base64 encoding reduces network payload size significantly

Introduces the EmbeddingValue class to support both float list and base64-encoded embedding data, enabling efficient handling and backward compatibility. Embedding, EmbeddingCreateParams, and related classes are updated to use EmbeddingValue, with automatic decoding and encoding between formats. Adds EmbeddingDefaults for global default encoding configuration, and comprehensive tests for new behaviors and compatibility.

* Deleted invalid EmbeddingDefaults.kt

Deleted invalid EmbeddingDefaults.kt

* fix: actually add system properties

* Modified the field name for floats and base64

Modified the field name for floats and base64

* Deleted DebutTest

Deleted DebutTest

* Modified validate method and refactored apply scope function

* validate() methods validate anything the "shape" of the data being correct

* The code has been refactored to use Kotlin's apply scope function for improved conciseness and consistency.

* Modified default encoding

Modified default encoding

* Modified the implementation of default encoding

Modified the implementation of default encoding

* Modified format

Modified format

* Delete plan2.md

Delete plan2.md

* fix: set the default correctly

* fix: rename some things

* chore: EmbeddingValue refactor

* refactor: embedding data model

* chore: delete test with no asserts

* chore: test changes

* fix: little-endian

---------

Co-authored-by: Yoshio Terada <[email protected]>
Co-authored-by: Tomer Aberbach <[email protected]>

* release: 2.19.0

---------

Co-authored-by: stainless-app[bot] <142633134+stainless-app[bot]@users.noreply.github.com>
Co-authored-by: Yoshio Terada <[email protected]>
Co-authored-by: Yoshio Terada <[email protected]>
Co-authored-by: Tomer Aberbach <[email protected]>

Author: 4 people

.release-please-manifest.json

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

CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 2.19.0 (2025-07-23)
+
+Full Changelog: [v2.18.2...v2.19.0](https://github.com/openai/openai-java/compare/v2.18.2...v2.19.0)
+
+### Features
+
+* **client:** support base64 embeddings and use as default ([#519](https://github.com/openai/openai-java/issues/519)) ([12b0ff7](https://github.com/openai/openai-java/commit/12b0ff75cf2a3bc93cf5c41adbbf2b5097a8e941))
+
+
+### Documentation
+
+* fix missing readme comment ([720ed2c](https://github.com/openai/openai-java/commit/720ed2cff555977efa00043b3f424920811ce339))
+
 ## 2.18.2 (2025-07-22)
 
 Full Changelog: [v2.18.1...v2.18.2](https://github.com/openai/openai-java/compare/v2.18.1...v2.18.2)

README.md

@@ -2,16 +2,16 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.openai/openai-java)](https://central.sonatype.com/artifact/com.openai/openai-java/2.18.2)
-[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/2.18.2/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/2.18.2)
+[![Maven Central](https://img.shields.io/maven-central/v/com.openai/openai-java)](https://central.sonatype.com/artifact/com.openai/openai-java/2.19.0)
+[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/2.19.0/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/2.19.0)
 
 <!-- x-release-please-end -->
 
 The OpenAI Java SDK provides convenient access to the [OpenAI REST API](https://platform.openai.com/docs) from applications written in Java.
 
 <!-- x-release-please-start-version -->
 
-The REST API documentation can be found on [platform.openai.com](https://platform.openai.com/docs). Javadocs are available on [javadoc.io](https://javadoc.io/doc/com.openai/openai-java/2.18.2).
+The REST API documentation can be found on [platform.openai.com](https://platform.openai.com/docs). Javadocs are available on [javadoc.io](https://javadoc.io/doc/com.openai/openai-java/2.19.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:2.18.2")
+implementation("com.openai:openai-java:2.19.0")
 ```
 
 ### Maven
@@ -33,7 +33,7 @@ implementation("com.openai:openai-java:2.18.2")
 <dependency>
   <groupId>com.openai</groupId>
   <artifactId>openai-java</artifactId>
-  <version>2.18.2</version>
+  <version>2.19.0</version>
 </dependency>
 ```
 
@@ -118,7 +118,7 @@ import com.openai.client.okhttp.OpenAIOkHttpClient;
 
 OpenAIClient client = OpenAIOkHttpClient.builder()
     // Configures using the `openai.apiKey`, `openai.orgId`, `openai.projectId`, `openai.webhookSecret` and `openai.baseUrl` system properties
-    Or configures using the `OPENAI_API_KEY`, `OPENAI_ORG_ID`, `OPENAI_PROJECT_ID`, `OPENAI_WEBHOOK_SECRET` and `OPENAI_BASE_URL` environment variables
+    // Or configures using the `OPENAI_API_KEY`, `OPENAI_ORG_ID`, `OPENAI_PROJECT_ID`, `OPENAI_WEBHOOK_SECRET` and `OPENAI_BASE_URL` environment variables
     .fromEnv()
     .apiKey("My API Key")
     .build();
@@ -1321,7 +1321,7 @@ If you're using Spring Boot, then you can use the SDK's [Spring Boot starter](ht
 #### Gradle
 
 ```kotlin
-implementation("com.openai:openai-java-spring-boot-starter:2.18.2")
+implementation("com.openai:openai-java-spring-boot-starter:2.19.0")
 ```
 
 #### Maven
@@ -1330,7 +1330,7 @@ implementation("com.openai:openai-java-spring-boot-starter:2.18.2")
 <dependency>
   <groupId>com.openai</groupId>
   <artifactId>openai-java-spring-boot-starter</artifactId>
-  <version>2.18.2</version>
+  <version>2.19.0</version>
 </dependency>
 ```
 

build.gradle.kts

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

openai-java-core/src/main/kotlin/com/openai/models/embeddings/Embedding.kt

@@ -12,7 +12,6 @@ import com.openai.core.JsonMissing
 import com.openai.core.JsonValue
 import com.openai.core.checkKnown
 import com.openai.core.checkRequired
-import com.openai.core.toImmutable
 import com.openai.errors.OpenAIInvalidDataException
 import java.util.Collections
 import java.util.Objects
@@ -21,7 +20,7 @@ import kotlin.jvm.optionals.getOrNull
 /** Represents an embedding vector returned by embedding endpoint. */
 class Embedding
 private constructor(
-    private val embedding: JsonField<List<Float>>,
+    private val embedding: JsonField<EmbeddingValue>,
     private val index: JsonField<Long>,
     private val object_: JsonValue,
     private val additionalProperties: MutableMap<String, JsonValue>,
@@ -31,7 +30,7 @@ private constructor(
     private constructor(
         @JsonProperty("embedding")
         @ExcludeMissing
-        embedding: JsonField<List<Float>> = JsonMissing.of(),
+        embedding: JsonField<EmbeddingValue> = JsonMissing.of(),
         @JsonProperty("index") @ExcludeMissing index: JsonField<Long> = JsonMissing.of(),
         @JsonProperty("object") @ExcludeMissing object_: JsonValue = JsonMissing.of(),
     ) : this(embedding, index, object_, mutableMapOf())
@@ -43,7 +42,16 @@ private constructor(
      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type or is
      *   unexpectedly missing or null (e.g. if the server responded with an unexpected value).
      */
-    fun embedding(): List<Float> = embedding.getRequired("embedding")
+    fun embedding(): List<Float> = embeddingValue().asFloats()
+
+    /**
+     * The embedding data in its original format (either float list or base64 string). This method
+     * provides efficient access to the embedding data without unnecessary conversions.
+     *
+     * @throws OpenAIInvalidDataException if the JSON field has an unexpected type or is
+     *   unexpectedly missing or null (e.g. if the server responded with an unexpected value).
+     */
+    fun embeddingValue(): EmbeddingValue = embedding.getRequired("embedding")
 
     /**
      * The index of the embedding in the list of embeddings.
@@ -71,7 +79,16 @@ private constructor(
      *
      * Unlike [embedding], this method doesn't throw if the JSON field has an unexpected type.
      */
-    @JsonProperty("embedding") @ExcludeMissing fun _embedding(): JsonField<List<Float>> = embedding
+    fun _embedding(): JsonField<List<Float>> = embedding.map { it.asFloats() }
+
+    /**
+     * Returns the raw JSON value of [embedding].
+     *
+     * Unlike [embeddingValue], this method doesn't throw if the JSON field has an unexpected type.
+     */
+    @JsonProperty("embedding")
+    @ExcludeMissing
+    fun _embeddingValue(): JsonField<EmbeddingValue> = embedding
 
     /**
      * Returns the raw JSON value of [index].
@@ -109,25 +126,38 @@ private constructor(
     /** A builder for [Embedding]. */
     class Builder internal constructor() {
 
-        private var embedding: JsonField<MutableList<Float>>? = null
+        private var embeddingFloats: MutableList<Float>? = null
+        private var embedding: JsonField<EmbeddingValue>? = null
         private var index: JsonField<Long>? = null
         private var object_: JsonValue = JsonValue.from("embedding")
         private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()
 
         @JvmSynthetic
         internal fun from(embedding: Embedding) = apply {
-            this.embedding = embedding.embedding.map { it.toMutableList() }
+            this.embedding = embedding.embedding
             index = embedding.index
             object_ = embedding.object_
             additionalProperties = embedding.additionalProperties.toMutableMap()
         }
 
+        /**
+         * The embedding vector. The length of vector depends on the model as listed in the
+         * [embedding guide](https://platform.openai.com/docs/guides/embeddings).
+         */
+        fun embedding(embedding: EmbeddingValue) = embedding(JsonField.of(embedding))
+
         /**
          * The embedding vector, which is a list of floats. The length of vector depends on the
          * model as listed in the
          * [embedding guide](https://platform.openai.com/docs/guides/embeddings).
          */
-        fun embedding(embedding: List<Float>) = embedding(JsonField.of(embedding))
+        fun embedding(floats: List<Float>) = embedding(EmbeddingValue.ofFloats(floats))
+
+        /**
+         * The embedding vector, which is a base64 string. The length of vector depends on the model
+         * as listed in the [embedding guide](https://platform.openai.com/docs/guides/embeddings).
+         */
+        fun embedding(base64: String) = embedding(EmbeddingValue.ofBase64(base64))
 
         /**
          * Sets [Builder.embedding] to an arbitrary JSON value.
@@ -136,8 +166,9 @@ private constructor(
          * instead. This method is primarily for setting the field to an undocumented or not yet
          * supported value.
          */
-        fun embedding(embedding: JsonField<List<Float>>) = apply {
-            this.embedding = embedding.map { it.toMutableList() }
+        fun embedding(embedding: JsonField<EmbeddingValue>) = apply {
+            embeddingFloats = null
+            this.embedding = embedding
         }
 
         /**
@@ -146,10 +177,12 @@ private constructor(
          * @throws IllegalStateException if the field was previously set to a non-list.
          */
         fun addEmbedding(embedding: Float) = apply {
-            this.embedding =
-                (this.embedding ?: JsonField.of(mutableListOf())).also {
-                    checkKnown("embedding", it).add(embedding)
-                }
+            embeddingFloats =
+                (this.embedding?.let { checkKnown("embedding", it) }?.asFloats()?.toMutableList()
+                        ?: embeddingFloats
+                        ?: mutableListOf())
+                    .apply { add(embedding) }
+            this.embedding = null
         }
 
         /** The index of the embedding in the list of embeddings. */
@@ -211,7 +244,10 @@ private constructor(
          */
         fun build(): Embedding =
             Embedding(
-                checkRequired("embedding", embedding).map { it.toImmutable() },
+                checkRequired(
+                    "embedding",
+                    embedding ?: embeddingFloats?.let { JsonField.of(EmbeddingValue.ofFloats(it)) },
+                ),
                 checkRequired("index", index),
                 object_,
                 additionalProperties.toMutableMap(),
@@ -225,7 +261,7 @@ private constructor(
             return@apply
         }
 
-        embedding()
+        embeddingValue().validate()
         index()
         _object_().let {
             if (it != JsonValue.from("embedding")) {
@@ -250,7 +286,7 @@ private constructor(
      */
     @JvmSynthetic
     internal fun validity(): Int =
-        (embedding.asKnown().getOrNull()?.size ?: 0) +
+        (embedding.asKnown().getOrNull()?.validity() ?: 0) +
             (if (index.asKnown().isPresent) 1 else 0) +
             object_.let { if (it == JsonValue.from("embedding")) 1 else 0 }
 

openai-java-core/src/main/kotlin/com/openai/models/embeddings/EmbeddingCreateParams.kt

@@ -581,7 +581,8 @@ private constructor(
             private var input: JsonField<Input>? = null
             private var model: JsonField<EmbeddingModel>? = null
             private var dimensions: JsonField<Long> = JsonMissing.of()
-            private var encodingFormat: JsonField<EncodingFormat> = JsonMissing.of()
+            private var encodingFormat: JsonField<EncodingFormat> =
+                JsonField.of(EncodingFormat.BASE64)
             private var user: JsonField<String> = JsonMissing.of()
             private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()