make a public preview annotation for Imagen

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/FirebaseVertexAI.kt

@@ -27,6 +27,7 @@ import com.google.firebase.vertexai.type.GenerationConfig
 import com.google.firebase.vertexai.type.ImagenGenerationConfig
 import com.google.firebase.vertexai.type.ImagenSafetySettings
 import com.google.firebase.vertexai.type.InvalidLocationException
+import com.google.firebase.vertexai.type.PublicPreviewAPI
 import com.google.firebase.vertexai.type.RequestOptions
 import com.google.firebase.vertexai.type.SafetySetting
 import com.google.firebase.vertexai.type.Tool
@@ -91,6 +92,7 @@ internal constructor(
    * @return The initialized [ImagenModel] instance.
    */
   @JvmOverloads
+  @PublicPreviewAPI
   public fun imagenModel(
     modelName: String,
     generationConfig: ImagenGenerationConfig? = null,

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/ImagenModel.kt

@@ -28,12 +28,14 @@ import com.google.firebase.vertexai.type.ImagenGenerationConfig
 import com.google.firebase.vertexai.type.ImagenGenerationResponse
 import com.google.firebase.vertexai.type.ImagenInlineImage
 import com.google.firebase.vertexai.type.ImagenSafetySettings
+import com.google.firebase.vertexai.type.PublicPreviewAPI
 import com.google.firebase.vertexai.type.RequestOptions
 
 /**
  * Represents a generative model (like Imagen), capable of generating images based on various input
  * types.
  */
+@PublicPreviewAPI
 public class ImagenModel
 internal constructor(
   private val modelName: String,
@@ -126,6 +128,7 @@ internal constructor(
   }
 }
 
+@OptIn(PublicPreviewAPI::class)
 private fun ImagenGenerationResponse.Internal.validate(): ImagenGenerationResponse.Internal {
   if (predictions.none { it.mimeType != null }) {
     throw ContentBlockedException(

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/common/APIController.kt

@@ -26,6 +26,7 @@ import com.google.firebase.vertexai.type.FinishReason
 import com.google.firebase.vertexai.type.GRpcErrorResponse
 import com.google.firebase.vertexai.type.GenerateContentResponse
 import com.google.firebase.vertexai.type.ImagenGenerationResponse
+import com.google.firebase.vertexai.type.PublicPreviewAPI
 import com.google.firebase.vertexai.type.RequestOptions
 import com.google.firebase.vertexai.type.Response
 import io.ktor.client.HttpClient
@@ -82,6 +83,7 @@ internal val JSON = Json {
  * @property apiClient The value to pass in the `x-goog-api-client` header.
  * @property headerProvider A provider that generates extra headers to include in all HTTP requests.
  */
+@OptIn(PublicPreviewAPI::class)
 internal class APIController
 internal constructor(
   private val key: String,

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/common/Request.kt

@@ -20,6 +20,7 @@ import com.google.firebase.vertexai.common.util.fullModelName
 import com.google.firebase.vertexai.type.Content
 import com.google.firebase.vertexai.type.GenerationConfig
 import com.google.firebase.vertexai.type.ImagenImageFormat
+import com.google.firebase.vertexai.type.PublicPreviewAPI
 import com.google.firebase.vertexai.type.SafetySetting
 import com.google.firebase.vertexai.type.Tool
 import com.google.firebase.vertexai.type.ToolConfig
@@ -74,6 +75,7 @@ internal data class GenerateImageRequest(
 ) : Request {
   @Serializable internal data class ImagenPrompt(val prompt: String)
 
+  @OptIn(PublicPreviewAPI::class)
   @Serializable
   internal data class ImagenParameters(
     val sampleCount: Int = 1,

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/java/ImagenModelFutures.kt

@@ -22,12 +22,14 @@ import com.google.firebase.vertexai.ImagenModel
 import com.google.firebase.vertexai.type.ImagenGCSImage
 import com.google.firebase.vertexai.type.ImagenGenerationResponse
 import com.google.firebase.vertexai.type.ImagenInlineImage
+import com.google.firebase.vertexai.type.PublicPreviewAPI
 
 /**
  * Wrapper class providing Java compatible methods for [ImagenModel].
  *
  * @see [ImagenModel]
  */
+@PublicPreviewAPI
 public abstract class ImagenModelFutures internal constructor() {
   /**
    * Generates an image, returning the result directly to the caller.

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/type/ImagenAspectRatio.kt

@@ -17,6 +17,7 @@
 package com.google.firebase.vertexai.type
 
 /** Represents the aspect ratio that the generated image should conform to. */
+@PublicPreviewAPI
 public class ImagenAspectRatio private constructor(internal val internalVal: String) {
   public companion object {
     /** A square image, useful for icons, profile pictures, etc. */

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/type/ImagenGCSImage.kt

@@ -22,5 +22,6 @@ package com.google.firebase.vertexai.type
  * @param gcsUri Contains the `gs://` URI for the image.
  * @param mimeType Contains the MIME type of the image (for example, `"image/png"`).
  */
+@PublicPreviewAPI
 public class ImagenGCSImage
 internal constructor(public val gcsUri: String, public val mimeType: String) {}

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/type/ImagenGenerationConfig.kt

@@ -26,6 +26,7 @@ package com.google.firebase.vertexai.type
  * @param imageFormat The file format/compression of the generated images.
  * @param addWatermark Adds an invisible watermark to mark the image as AI generated.
  */
+@PublicPreviewAPI
 public class ImagenGenerationConfig(
   public val negativePrompt: String? = null,
   public val numberOfImages: Int? = 1,
@@ -88,6 +89,7 @@ public class ImagenGenerationConfig(
  * }
  * ```
  */
+@PublicPreviewAPI
 public fun imagenGenerationConfig(
   init: ImagenGenerationConfig.Builder.() -> Unit
 ): ImagenGenerationConfig {

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/type/ImagenGenerationResponse.kt

@@ -25,6 +25,7 @@ import kotlinx.serialization.Serializable
  * @param filteredReason if fewer images were generated than were requested, this field will contain
  * the reason they were filtered out.
  */
+@PublicPreviewAPI
 public class ImagenGenerationResponse<T>
 internal constructor(public val images: List<T>, public val filteredReason: String?) {
 

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/type/ImagenImageFormat.kt

@@ -26,6 +26,7 @@ import kotlinx.serialization.Serializable
  * means the image is permitted to be lower quality to reduce size. This parameter is not relevant
  * for every MIME type.
  */
+@PublicPreviewAPI
 public class ImagenImageFormat
 private constructor(public val mimeType: String, public val compressionQuality: Int?) {
 

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/type/ImagenInlineImage.kt

@@ -26,6 +26,7 @@ import android.util.Base64
  * @param data Contains the raw bytes of the image
  * @param mimeType Contains the MIME type of the image (for example, `"image/png"`)
  */
+@PublicPreviewAPI
 public class ImagenInlineImage
 internal constructor(public val data: ByteArray, public val mimeType: String) {
 

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/type/ImagenPersonFilterLevel.kt

@@ -17,6 +17,7 @@
 package com.google.firebase.vertexai.type
 
 /** A filter used to prevent images from containing depictions of children or people. */
+@PublicPreviewAPI
 public class ImagenPersonFilterLevel private constructor(internal val internalVal: String) {
   public companion object {
     /** No filters applied. */

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/type/ImagenSafetyFilterLevel.kt

@@ -17,6 +17,7 @@
 package com.google.firebase.vertexai.type
 
 /** Used for safety filtering. */
+@PublicPreviewAPI
 public class ImagenSafetyFilterLevel private constructor(internal val internalVal: String) {
   public companion object {
     /** Strongest filtering level, most strict blocking. */

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/type/ImagenSafetySettings.kt

@@ -22,6 +22,7 @@ package com.google.firebase.vertexai.type
  * @param safetyFilterLevel Used to filter unsafe content.
  * @param personFilterLevel Used to filter images containing people.
  */
+@PublicPreviewAPI
 public class ImagenSafetySettings(
   internal val safetyFilterLevel: ImagenSafetyFilterLevel,
   internal val personFilterLevel: ImagenPersonFilterLevel,

firebase-vertexai/src/main/kotlin/com/google/firebase/vertexai/type/PublicPreviewAPI.kt

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2025 Google LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package com.google.firebase.vertexai.type
+
+@Retention(AnnotationRetention.BINARY)
+@RequiresOptIn(
+  level = RequiresOptIn.Level.ERROR,
+  message =
+    "This API is currently experimental and in public preview and may change in behavior in " +
+      "backwards-incompatible ways without notice.",
+)
+public annotation class PublicPreviewAPI()

firebase-vertexai/src/test/java/com/google/firebase/vertexai/UnarySnapshotTests.kt

@@ -25,6 +25,7 @@ import com.google.firebase.vertexai.type.HarmProbability
 import com.google.firebase.vertexai.type.HarmSeverity
 import com.google.firebase.vertexai.type.InvalidAPIKeyException
 import com.google.firebase.vertexai.type.PromptBlockedException
+import com.google.firebase.vertexai.type.PublicPreviewAPI
 import com.google.firebase.vertexai.type.ResponseStoppedException
 import com.google.firebase.vertexai.type.SerializationException
 import com.google.firebase.vertexai.type.ServerException
@@ -35,7 +36,6 @@ import com.google.firebase.vertexai.util.goldenUnaryFile
 import com.google.firebase.vertexai.util.shouldNotBeNullOrEmpty
 import io.kotest.assertions.throwables.shouldThrow
 import io.kotest.inspectors.forAtLeastOne
-import io.kotest.matchers.collections.shouldContain
 import io.kotest.matchers.collections.shouldNotBeEmpty
 import io.kotest.matchers.nulls.shouldNotBeNull
 import io.kotest.matchers.should
@@ -54,6 +54,7 @@ import kotlinx.serialization.json.jsonPrimitive
 import org.json.JSONArray
 import org.junit.Test
 
+@OptIn(PublicPreviewAPI::class)
 internal class UnarySnapshotTests {
   private val testTimeout = 5.seconds
 

firebase-vertexai/src/test/java/com/google/firebase/vertexai/util/tests.kt

@@ -14,11 +14,14 @@
  * limitations under the License.
  */
 
+@file:OptIn(PublicPreviewAPI::class)
+
 package com.google.firebase.vertexai.util
 
 import com.google.firebase.vertexai.GenerativeModel
 import com.google.firebase.vertexai.ImagenModel
 import com.google.firebase.vertexai.common.APIController
+import com.google.firebase.vertexai.type.PublicPreviewAPI
 import com.google.firebase.vertexai.type.RequestOptions
 import io.kotest.matchers.collections.shouldNotBeEmpty
 import io.kotest.matchers.nulls.shouldNotBeNull