[AI] Add ImageConfig support for generateContent

FirebaseAI/CHANGELOG.md

@@ -1,3 +1,8 @@
+# Unreleased
+- [feature] Adds support for configuring image generation properties,
+  such as aspect ratio and image size, through the new `ImageConfig` struct
+  and its integration with `GenerationConfig`.
+
 # 12.11.0
 - [feature] **Public Preview**: Introduces `GenerativeModelSession` providing
   APIs for generating structured data from Gemini via the same `@Generable` and

FirebaseAI/Sources/GenerationConfig.swift

@@ -59,6 +59,9 @@ public struct GenerationConfig: Sendable {
   /// Configuration for controlling the "thinking" behavior of compatible Gemini models.
   var thinkingConfig: ThinkingConfig?
 
+  /// Configuration for the aspect ratio and size of generated images.
+  var imageConfig: ImageConfig?
+
   /// Creates a new `GenerationConfig` value.
   ///
   /// See the
@@ -162,12 +165,13 @@ public struct GenerationConfig: Sendable {
   ///     > backwards-incompatible ways.
   ///   - thinkingConfig: Configuration for controlling the "thinking" behavior of compatible Gemini
   ///     models; see ``ThinkingConfig`` for more details.
+  ///   - imageConfig: Configure the aspect ratio and size of generated images.
   public init(temperature: Float? = nil, topP: Float? = nil, topK: Int? = nil,
               candidateCount: Int? = nil, maxOutputTokens: Int? = nil,
               presencePenalty: Float? = nil, frequencyPenalty: Float? = nil,
               stopSequences: [String]? = nil, responseMIMEType: String? = nil,
               responseSchema: Schema? = nil, responseModalities: [ResponseModality]? = nil,
-              thinkingConfig: ThinkingConfig? = nil) {
+              thinkingConfig: ThinkingConfig? = nil, imageConfig: ImageConfig? = nil) {
     // Explicit init because otherwise if we re-arrange the above variables it changes the API
     // surface.
     self.temperature = temperature
@@ -183,12 +187,14 @@ public struct GenerationConfig: Sendable {
     responseJSONSchema = nil
     self.responseModalities = responseModalities
     self.thinkingConfig = thinkingConfig
+    self.imageConfig = imageConfig
   }
 
   init(temperature: Float? = nil, topP: Float? = nil, topK: Int? = nil, candidateCount: Int? = nil,
        maxOutputTokens: Int? = nil, presencePenalty: Float? = nil, frequencyPenalty: Float? = nil,
        stopSequences: [String]? = nil, responseMIMEType: String, responseJSONSchema: JSONObject,
-       responseModalities: [ResponseModality]? = nil, thinkingConfig: ThinkingConfig? = nil) {
+       responseModalities: [ResponseModality]? = nil, thinkingConfig: ThinkingConfig? = nil,
+       imageConfig: ImageConfig? = nil) {
     self.temperature = temperature
     self.topP = topP
     self.topK = topK
@@ -202,6 +208,7 @@ public struct GenerationConfig: Sendable {
     self.responseJSONSchema = responseJSONSchema
     self.responseModalities = responseModalities
     self.thinkingConfig = thinkingConfig
+    self.imageConfig = imageConfig
   }
 
   /// Merges two configurations, giving precedence to values found in the `overrides` parameter.
@@ -239,6 +246,7 @@ public struct GenerationConfig: Sendable {
     config.responseMIMEType = overrideConfig.responseMIMEType ?? config.responseMIMEType
     config.responseModalities = overrideConfig.responseModalities ?? config.responseModalities
     config.thinkingConfig = overrideConfig.thinkingConfig ?? config.thinkingConfig
+    config.imageConfig = overrideConfig.imageConfig ?? config.imageConfig
 
     // 5. Handle Schema mutual exclusivity with precedence for `responseJSONSchema`.
     if let responseJSONSchema = overrideConfig.responseJSONSchema {
@@ -271,5 +279,6 @@ extension GenerationConfig: Encodable {
     case responseJSONSchema = "responseJsonSchema"
     case responseModalities
     case thinkingConfig
+    case imageConfig
   }
 }

FirebaseAI/Sources/Types/Internal/Imagen/ImageGenerationParameters.swift

@@ -18,6 +18,7 @@ struct ImageGenerationParameters {
   let storageURI: String?
   let negativePrompt: String?
   let aspectRatio: String?
+  let sampleImageSize: String?
   let safetyFilterLevel: String?
   let personGeneration: String?
   let outputOptions: ImageGenerationOutputOptions?
@@ -38,6 +39,7 @@ extension ImageGenerationParameters: Encodable {
     case storageURI = "storageUri"
     case negativePrompt
     case aspectRatio
+    case sampleImageSize
     case safetyFilterLevel = "safetySetting"
     case personGeneration
     case outputOptions
@@ -52,6 +54,7 @@ extension ImageGenerationParameters: Encodable {
     try container.encodeIfPresent(storageURI, forKey: .storageURI)
     try container.encodeIfPresent(negativePrompt, forKey: .negativePrompt)
     try container.encodeIfPresent(aspectRatio, forKey: .aspectRatio)
+    try container.encodeIfPresent(sampleImageSize, forKey: .sampleImageSize)
     try container.encodeIfPresent(safetyFilterLevel, forKey: .safetyFilterLevel)
     try container.encodeIfPresent(personGeneration, forKey: .personGeneration)
     try container.encodeIfPresent(outputOptions, forKey: .outputOptions)

FirebaseAI/Sources/Types/Public/AGENTS.md

@@ -14,6 +14,7 @@ Any changes to these types must be done carefully to avoid breaking changes for
 ### Files
 
 - **`Backend.swift`**: Defines the `Backend` struct, which is used to configure the backend API for the Firebase AI SDK. It provides static methods `vertexAI(location:)` and `googleAI()` to create instances for the respective backends.
+- **`ImageConfig.swift`**: Defines the `ImageConfig` struct, used for configuring generated image properties like aspect ratio and size.
 - **`Part.swift`**: Defines the `Part` protocol and several conforming structs: `TextPart`, `InlineDataPart`, `FileDataPart`, `FunctionCallPart`, `FunctionResponsePart`, `ExecutableCodePart`, and `CodeExecutionResultPart`. A `Part` represents a discrete piece of data in a media format that can be interpreted by the model.
 - **`ResponseModality.swift`**: Defines the `ResponseModality` struct, which represents the different types of data that a model can produce as output (e.g., `text`, `image`, `audio`).
 - **`Schema.swift`**: Defines the `Schema` class, which allows the definition of input and output data types for function calling. It supports various data types like string, number, integer, boolean, array, and object.

FirebaseAI/Sources/Types/Public/ImageConfig.swift

@@ -0,0 +1,188 @@
+// Copyright 2026 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.
+
+/// Configuration options for generating images with Gemini models.
+///
+/// See the [documentation](https://ai.google.dev/gemini-api/docs/image-generation#aspect_ratios_and_image_size)
+/// to learn about parameters available for use with Gemini image models.
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+public struct ImageConfig: Sendable {
+  /// The aspect ratio of generated images.
+  public let aspectRatio: AspectRatio?
+
+  /// The size of the generated images.
+  public let imageSize: ImageSize?
+
+  /// Initializes configuration options for generating images with Gemini.
+  ///
+  /// - Parameters:
+  ///   - aspectRatio: The aspect ratio of generated images.
+  ///   - imageSize: The size of the generated images.
+  public init(aspectRatio: AspectRatio? = nil, imageSize: ImageSize? = nil) {
+    self.aspectRatio = aspectRatio
+    self.imageSize = imageSize
+  }
+}
+
+/// An aspect ratio for generated images.
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+public extension ImageConfig {
+  struct AspectRatio: Sendable {
+    /// Square (1:1) aspect ratio.
+    ///
+    /// Common uses for this aspect ratio include social media posts.
+    public static let square1x1 = AspectRatio(kind: .square1x1)
+
+    /// Portrait widescreen (9:16) aspect ratio.
+    ///
+    /// This is the ``landscape16x9`` aspect ratio rotated 90 degrees. This a relatively new aspect
+    /// ratio that has been popularized by short form video apps (for example, YouTube shorts). Use
+    /// this for tall objects with strong vertical orientations such as buildings, trees,
+    /// waterfalls, or other similar objects.
+    public static let portrait9x16 = AspectRatio(kind: .portrait9x16)
+
+    /// Widescreen (16:9) aspect ratio.
+    ///
+    /// This ratio has replaced ``landscape4x3`` as the most common aspect ratio for TVs, monitors,
+    /// and mobile phone screens (landscape). Use this aspect ratio when you want to capture more of
+    /// the background (for example, scenic landscapes).
+    public static let landscape16x9 = AspectRatio(kind: .landscape16x9)
+
+    /// Portrait full screen (3:4) aspect ratio.
+    ///
+    /// This is the ``landscape4x3`` aspect ratio rotated 90 degrees. This lets to capture more of
+    /// the scene vertically compared to the ``square1x1`` aspect ratio.
+    public static let portrait3x4 = AspectRatio(kind: .portrait3x4)
+
+    /// Fullscreen (4:3) aspect ratio.
+    ///
+    /// This aspect ratio is commonly used in media or film. It is also the dimensions of most old
+    /// (non-widescreen) TVs and medium format cameras. It captures more of the scene horizontally
+    /// (compared to ``square1x1``), making it a preferred aspect ratio for photography.
+    public static let landscape4x3 = AspectRatio(kind: .landscape4x3)
+
+    /// Portrait (2:3) aspect ratio.
+    public static let portrait2x3 = AspectRatio(kind: .portrait2x3)
+
+    /// Landscape (3:2) aspect ratio.
+    public static let landscape3x2 = AspectRatio(kind: .landscape3x2)
+
+    /// Portrait (4:5) aspect ratio.
+    public static let portrait4x5 = AspectRatio(kind: .portrait4x5)
+
+    /// Landscape (5:4) aspect ratio.
+    public static let landscape5x4 = AspectRatio(kind: .landscape5x4)
+
+    /// Portrait (1:4) aspect ratio.
+    public static let portrait1x4 = AspectRatio(kind: .portrait1x4)
+
+    /// Landscape (4:1) aspect ratio.
+    public static let landscape4x1 = AspectRatio(kind: .landscape4x1)
+
+    /// Portrait (1:8) aspect ratio.
+    public static let portrait1x8 = AspectRatio(kind: .portrait1x8)
+
+    /// Landscape (8:1) aspect ratio.
+    public static let landscape8x1 = AspectRatio(kind: .landscape8x1)
+
+    /// Ultrawide (21:9) aspect ratio.
+    public static let ultrawide21x9 = AspectRatio(kind: .ultrawide21x9)
+
+    let rawValue: String
+  }
+
+  /// The size of images to generate.
+  struct ImageSize: Sendable {
+    /// 512px (0.5K) image size.
+    ///
+    /// This corresponds to 512x512 pixel images in a ``ImageConfig/AspectRatio/square1x1`` aspect
+    /// ratio. See the [documentation](https://ai.google.dev/gemini-api/docs/image-generation#aspect_ratios_and_image_size)
+    /// for specific sizes in other aspect ratios.
+    public static let size512 = ImageSize(kind: .size512)
+
+    /// 1K image size.
+    ///
+    /// This corresponds to 1024x1024 pixel images in a ``ImageConfig/AspectRatio/square1x1`` aspect
+    /// ratio. See the [documentation](https://ai.google.dev/gemini-api/docs/image-generation#aspect_ratios_and_image_size)
+    /// for specific sizes in other aspect ratios.
+    public static let size1K = ImageSize(kind: .size1K)
+
+    /// 2K image size.
+    ///
+    /// This corresponds to 2048x2048 pixel images in a ``ImageConfig/AspectRatio/square1x1`` aspect
+    /// ratio. See the [documentation](https://ai.google.dev/gemini-api/docs/image-generation#aspect_ratios_and_image_size)
+    /// for specific sizes in other aspect ratios.
+    public static let size2K = ImageSize(kind: .size2K)
+
+    /// 4K image size.
+    ///
+    /// This corresponds to 4096x4096 pixel images in a ``ImageConfig/AspectRatio/square1x1`` aspect
+    /// ratio. See the [documentation](https://ai.google.dev/gemini-api/docs/image-generation#aspect_ratios_and_image_size)
+    /// for specific sizes in other aspect ratios.
+    public static let size4K = ImageSize(kind: .size4K)
+
+    let rawValue: String
+  }
+}
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+extension ImageConfig.AspectRatio: ProtoEnum {
+  enum Kind: String {
+    case square1x1 = "1:1"
+    case portrait9x16 = "9:16"
+    case landscape16x9 = "16:9"
+    case portrait3x4 = "3:4"
+    case landscape4x3 = "4:3"
+    case portrait2x3 = "2:3"
+    case landscape3x2 = "3:2"
+    case portrait4x5 = "4:5"
+    case landscape5x4 = "5:4"
+    case portrait1x4 = "1:4"
+    case landscape4x1 = "4:1"
+    case portrait1x8 = "1:8"
+    case landscape8x1 = "8:1"
+    case ultrawide21x9 = "21:9"
+  }
+}
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+extension ImageConfig.ImageSize: ProtoEnum {
+  enum Kind: String {
+    case size512 = "512"
+    case size1K = "1K"
+    case size2K = "2K"
+    case size4K = "4K"
+  }
+}
+
+// MARK: - Codable Conformances
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+extension ImageConfig: Encodable {}
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+extension ImageConfig.AspectRatio: Encodable {
+  public func encode(to encoder: any Encoder) throws {
+    var container = encoder.singleValueContainer()
+    try container.encode(rawValue)
+  }
+}
+
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+extension ImageConfig.ImageSize: Encodable {
+  public func encode(to encoder: any Encoder) throws {
+    var container = encoder.singleValueContainer()
+    try container.encode(rawValue)
+  }
+}

FirebaseAI/Sources/Types/Public/Imagen/AGENTS.md

@@ -15,6 +15,8 @@ These types are part of the public API and are used by developers to interact wi
 
 - **`ImagenImagesBlockedError.swift`**: Defines the `ImagenImagesBlockedError` error, which occurs when image generation fails due to all generated images being blocked.
 
+- **`ImagenImageSize.swift`**: Defines the `ImagenImageSize` struct, which represents the size of images generated by Imagen. It provides static properties for common image sizes like `size1K`, `size2K`, etc.
+
 - **`ImagenInlineImage.swift`**: Defines the `ImagenInlineImage` struct, which represents an image generated by Imagen as inline data. It contains the `mimeType` and the image `data`.
 
 - **`ImagenModel.swift`**: Defines the `ImagenModel` class, which is the main entry point for generating images. It has methods like `generateImages(prompt:)` to generate images from a text prompt.

FirebaseAI/Sources/Types/Public/Imagen/ImagenAspectRatio.swift

@@ -12,59 +12,11 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import Foundation
-
-/// An aspect ratio for images generated by Imagen.
+/// The aspect ratio of images generated by Imagen.
 ///
 /// To specify an aspect ratio for generated images, set ``ImagenGenerationConfig/aspectRatio`` in
 /// your ``ImagenGenerationConfig``. See the [Cloud
 /// documentation](https://cloud.google.com/vertex-ai/generative-ai/docs/image/generate-images#aspect-ratio)
 /// for more details and examples of the supported aspect ratios.
 @available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
-public struct ImagenAspectRatio: Sendable {
-  /// Square (1:1) aspect ratio.
-  ///
-  /// Common uses for this aspect ratio include social media posts.
-  public static let square1x1 = ImagenAspectRatio(kind: .square1x1)
-
-  /// Portrait widescreen (9:16) aspect ratio.
-  ///
-  /// This is the ``landscape16x9`` aspect ratio rotated 90 degrees. This a relatively new aspect
-  /// ratio that has been popularized by short form video apps (for example, YouTube shorts). Use
-  /// this for tall objects with strong vertical orientations such as buildings, trees, waterfalls,
-  /// or other similar objects.
-  public static let portrait9x16 = ImagenAspectRatio(kind: .portrait9x16)
-
-  /// Widescreen (16:9) aspect ratio.
-  ///
-  /// This ratio has replaced ``landscape4x3`` as the most common aspect ratio for TVs, monitors,
-  /// and mobile phone screens (landscape). Use this aspect ratio when you want to capture more of
-  /// the background (for example, scenic landscapes).
-  public static let landscape16x9 = ImagenAspectRatio(kind: .landscape16x9)
-
-  /// Portrait full screen (3:4) aspect ratio.
-  ///
-  /// This is the ``landscape4x3`` aspect ratio rotated 90 degrees. This lets to capture more of
-  /// the scene vertically compared to the ``square1x1`` aspect ratio.
-  public static let portrait3x4 = ImagenAspectRatio(kind: .portrait3x4)
-
-  /// Fullscreen (4:3) aspect ratio.
-  ///
-  /// This aspect ratio is commonly used in media or film. It is also the dimensions of most old
-  /// (non-widescreen) TVs and medium format cameras. It captures more of the scene horizontally
-  /// (compared to ``square1x1``), making it a preferred aspect ratio for photography.
-  public static let landscape4x3 = ImagenAspectRatio(kind: .landscape4x3)
-
-  let rawValue: String
-}
-
-@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
-extension ImagenAspectRatio: ProtoEnum {
-  enum Kind: String {
-    case square1x1 = "1:1"
-    case portrait9x16 = "9:16"
-    case landscape16x9 = "16:9"
-    case portrait3x4 = "3:4"
-    case landscape4x3 = "4:3"
-  }
-}
+public typealias ImagenAspectRatio = ImageConfig.AspectRatio