[Vertex AI] Add APIConfig to support switching to the Developer API (#14521)

Author: andrewheard

FirebaseVertexAI/Sources/APIVersion.swift

@@ -16,9 +16,6 @@ import Foundation
 
 /// Constants associated with the Vertex AI for Firebase SDK.
 enum Constants {
-  /// The Vertex AI backend endpoint URL.
-  static let baseURL = "https://firebasevertexai.googleapis.com"
-
   /// The base reverse-DNS name for `NSError` or `CustomNSError` error domains.
   ///
   /// - Important: A suffix must be appended to produce an error domain (e.g.,

FirebaseVertexAI/Sources/Constants.swift

@@ -23,6 +23,7 @@ struct CountTokensRequest {
   let tools: [Tool]?
   let generationConfig: GenerationConfig?
 
+  let apiConfig: APIConfig
   let options: RequestOptions
 }
 
@@ -31,7 +32,8 @@ extension CountTokensRequest: GenerativeAIRequest {
   typealias Response = CountTokensResponse
 
   var url: URL {
-    URL(string: "\(Constants.baseURL)/\(options.apiVersion)/\(model):countTokens")!
+    URL(string:
+      "\(apiConfig.service.endpoint.rawValue)/\(apiConfig.version.rawValue)/\(model):countTokens")!
   }
 }
 

FirebaseVertexAI/Sources/CountTokensRequest.swift

@@ -24,7 +24,8 @@ struct GenerateContentRequest: Sendable {
   let tools: [Tool]?
   let toolConfig: ToolConfig?
   let systemInstruction: ModelContent?
-  let isStreaming: Bool
+  let apiConfig: APIConfig
+  let apiMethod: APIMethod
   let options: RequestOptions
 }
 
@@ -40,16 +41,28 @@ extension GenerateContentRequest: Encodable {
   }
 }
 
+@available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
+extension GenerateContentRequest {
+  enum APIMethod: String {
+    case generateContent
+    case streamGenerateContent
+    case countTokens
+  }
+}
+
 @available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
 extension GenerateContentRequest: GenerativeAIRequest {
   typealias Response = GenerateContentResponse
 
   var url: URL {
-    let modelURL = "\(Constants.baseURL)/\(options.apiVersion)/\(model)"
-    if isStreaming {
-      return URL(string: "\(modelURL):streamGenerateContent?alt=sse")!
-    } else {
-      return URL(string: "\(modelURL):generateContent")!
+    let modelURL = "\(apiConfig.service.endpoint.rawValue)/\(apiConfig.version.rawValue)/\(model)"
+    switch apiMethod {
+    case .generateContent:
+      return URL(string: "\(modelURL):\(apiMethod.rawValue)")!
+    case .streamGenerateContent:
+      return URL(string: "\(modelURL):\(apiMethod.rawValue)?alt=sse")!
+    case .countTokens:
+      fatalError("\(Self.self) should be a property of \(CountTokensRequest.self).")
     }
   }
 }

FirebaseVertexAI/Sources/GenerateContentRequest.swift

@@ -25,31 +25,17 @@ protocol GenerativeAIRequest: Sendable, Encodable {
 
 /// Configuration parameters for sending requests to the backend.
 @available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
-// TODO(#14405): Make the `apiVersion` constructor public in Firebase 12 with a default of `.v1`.
 public struct RequestOptions: Sendable {
   /// The request’s timeout interval in seconds; if not specified uses the default value for a
   /// `URLRequest`.
   let timeout: TimeInterval
 
-  /// The API version to use in requests to the backend.
-  let apiVersion: String
-
-  /// Initializes a request options object.
-  ///
-  /// - Parameters:
-  ///   - timeout: The request’s timeout interval in seconds; defaults to 180 seconds.
-  ///   - apiVersion: The API version to use in requests to the backend.
-  init(timeout: TimeInterval = 180.0, apiVersion: APIVersion) {
-    self.timeout = timeout
-    self.apiVersion = apiVersion.versionIdentifier
-  }
-
   /// Initializes a request options object.
   ///
   /// - Parameters:
   ///   - timeout: The request’s timeout interval in seconds; defaults to 180 seconds.
   public init(timeout: TimeInterval = 180.0) {
-    self.init(timeout: timeout, apiVersion: .v1beta)
+    self.timeout = timeout
   }
 }
 

FirebaseVertexAI/Sources/GenerativeAIRequest.swift

@@ -23,6 +23,9 @@ public final class GenerativeModel: Sendable {
   /// The resource name of the model in the backend; has the format "models/model-name".
   let modelResourceName: String
 
+  /// Configuration for the backend API used by this model.
+  let apiConfig: APIConfig
+
   /// The backing service responsible for sending and receiving model requests to the backend.
   let generativeAIService: GenerativeAIService
 
@@ -48,8 +51,8 @@ public final class GenerativeModel: Sendable {
   ///
   /// - Parameters:
   ///   - name: The name of the model to use, for example `"gemini-1.0-pro"`.
-  ///   - projectID: The project ID from the Firebase console.
-  ///   - apiKey: The API key for your project.
+  ///   - firebaseInfo: Firebase data used by the SDK, including project ID and API key.
+  ///   - apiConfig: Configuration for the backend API used by this model.
   ///   - generationConfig: The content generation parameters your model should use.
   ///   - safetySettings: A value describing what types of harmful content your model should allow.
   ///   - tools: A list of ``Tool`` objects that the model may use to generate the next response.
@@ -60,6 +63,7 @@ public final class GenerativeModel: Sendable {
   ///   - urlSession: The `URLSession` to use for requests; defaults to `URLSession.shared`.
   init(name: String,
        firebaseInfo: FirebaseInfo,
+       apiConfig: APIConfig,
        generationConfig: GenerationConfig? = nil,
        safetySettings: [SafetySetting]? = nil,
        tools: [Tool]?,
@@ -68,6 +72,7 @@ public final class GenerativeModel: Sendable {
        requestOptions: RequestOptions,
        urlSession: URLSession = .shared) {
     modelResourceName = name
+    self.apiConfig = apiConfig
     generativeAIService = GenerativeAIService(
       firebaseInfo: firebaseInfo,
       urlSession: urlSession
@@ -118,15 +123,18 @@ public final class GenerativeModel: Sendable {
     -> GenerateContentResponse {
     try content.throwIfError()
     let response: GenerateContentResponse
-    let generateContentRequest = GenerateContentRequest(model: modelResourceName,
-                                                        contents: content,
-                                                        generationConfig: generationConfig,
-                                                        safetySettings: safetySettings,
-                                                        tools: tools,
-                                                        toolConfig: toolConfig,
-                                                        systemInstruction: systemInstruction,
-                                                        isStreaming: false,
-                                                        options: requestOptions)
+    let generateContentRequest = GenerateContentRequest(
+      model: modelResourceName,
+      contents: content,
+      generationConfig: generationConfig,
+      safetySettings: safetySettings,
+      tools: tools,
+      toolConfig: toolConfig,
+      systemInstruction: systemInstruction,
+      apiConfig: apiConfig,
+      apiMethod: .generateContent,
+      options: requestOptions
+    )
     do {
       response = try await generativeAIService.loadRequest(request: generateContentRequest)
     } catch {
@@ -175,15 +183,18 @@ public final class GenerativeModel: Sendable {
   public func generateContentStream(_ content: [ModelContent]) throws
     -> AsyncThrowingStream<GenerateContentResponse, Error> {
     try content.throwIfError()
-    let generateContentRequest = GenerateContentRequest(model: modelResourceName,
-                                                        contents: content,
-                                                        generationConfig: generationConfig,
-                                                        safetySettings: safetySettings,
-                                                        tools: tools,
-                                                        toolConfig: toolConfig,
-                                                        systemInstruction: systemInstruction,
-                                                        isStreaming: true,
-                                                        options: requestOptions)
+    let generateContentRequest = GenerateContentRequest(
+      model: modelResourceName,
+      contents: content,
+      generationConfig: generationConfig,
+      safetySettings: safetySettings,
+      tools: tools,
+      toolConfig: toolConfig,
+      systemInstruction: systemInstruction,
+      apiConfig: apiConfig,
+      apiMethod: .streamGenerateContent,
+      options: requestOptions
+    )
 
     return AsyncThrowingStream { continuation in
       let responseStream = generativeAIService.loadRequestStream(request: generateContentRequest)
@@ -249,6 +260,7 @@ public final class GenerativeModel: Sendable {
       systemInstruction: systemInstruction,
       tools: tools,
       generationConfig: generationConfig,
+      apiConfig: apiConfig,
       options: requestOptions
     )
     return try await generativeAIService.loadRequest(request: countTokensRequest)

FirebaseVertexAI/Sources/GenerativeModel.swift

@@ -0,0 +1,92 @@
+// 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.
+
+/// Configuration for the generative AI backend API used by this SDK.
+struct APIConfig: Sendable, Hashable {
+  /// The service to use for generative AI.
+  ///
+  /// This controls which backend API is used by the SDK.
+  let service: Service
+
+  /// The version of the selected API to use, e.g., "v1".
+  let version: Version
+
+  /// Initializes an API configuration.
+  ///
+  /// - Parameters:
+  ///   - service: The API service to use for generative AI.
+  ///   - version: The version of the API to use.
+  init(service: Service, version: Version) {
+    self.service = service
+    self.version = version
+  }
+}
+
+extension APIConfig {
+  /// API services providing generative AI functionality.
+  ///
+  /// See [Vertex AI and Google AI
+  /// differences](https://cloud.google.com/vertex-ai/generative-ai/docs/overview#how-gemini-vertex-different-gemini-aistudio)
+  /// for a comparison of the two [API services](https://google.aip.dev/9#api-service).
+  enum Service: Hashable {
+    /// The Gemini Enterprise API provided by Vertex AI.
+    ///
+    /// See the [Cloud
+    /// docs](https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/inference) for
+    /// more details.
+    case vertexAI
+
+    /// The Gemini Developer API provided by Google AI.
+    ///
+    /// See the [Google AI docs](https://ai.google.dev/gemini-api/docs) for more details.
+    case developer(endpoint: Endpoint)
+
+    /// The specific network address to use for API requests.
+    ///
+    /// This must correspond with the API set in `service`.
+    var endpoint: Endpoint {
+      switch self {
+      case .vertexAI:
+        return .firebaseVertexAIProd
+      case let .developer(endpoint: endpoint):
+        return endpoint
+      }
+    }
+  }
+}
+
+extension APIConfig.Service {
+  /// Network addresses for generative AI API services.
+  enum Endpoint: String {
+    /// The Vertex AI in Firebase production endpoint.
+    case firebaseVertexAIProd = "https://firebasevertexai.googleapis.com"
+
+    /// The Vertex AI in Firebase staging endpoint; for SDK development and testing only.
+    case firebaseVertexAIStaging = "https://staging-firebasevertexai.sandbox.googleapis.com"
+
+    /// The Gemini Developer API production endpoint; for SDK development and testing only.
+    case generativeLanguage = "https://generativelanguage.googleapis.com"
+  }
+}
+
+extension APIConfig {
+  /// Versions of the configured API service (`APIConfig.Service`).
+  enum Version: String {
+    /// The stable channel for version 1 of the API.
+    case v1
+
+    /// The beta channel for version 1 of the API.
+    case v1beta
+  }
+}

FirebaseVertexAI/Sources/Types/Internal/APIConfig.swift

@@ -17,13 +17,18 @@ import Foundation
 @available(iOS 15.0, macOS 12.0, macCatalyst 15.0, tvOS 15.0, watchOS 8.0, *)
 struct ImagenGenerationRequest<ImageType: ImagenImageRepresentable>: Sendable {
   let model: String
+  let apiConfig: APIConfig
   let options: RequestOptions
   let instances: [ImageGenerationInstance]
   let parameters: ImageGenerationParameters
 
-  init(model: String, options: RequestOptions, instances: [ImageGenerationInstance],
+  init(model: String,
+       apiConfig: APIConfig,
+       options: RequestOptions,
+       instances: [ImageGenerationInstance],
        parameters: ImageGenerationParameters) {
     self.model = model
+    self.apiConfig = apiConfig
     self.options = options
     self.instances = instances
     self.parameters = parameters
@@ -35,7 +40,8 @@ extension ImagenGenerationRequest: GenerativeAIRequest where ImageType: Decodabl
   typealias Response = ImagenGenerationResponse<ImageType>
 
   var url: URL {
-    return URL(string: "\(Constants.baseURL)/\(options.apiVersion)/\(model):predict")!
+    return URL(string:
+      "\(apiConfig.service.endpoint.rawValue)/\(apiConfig.version.rawValue)/\(model):predict")!
   }
 }
 

FirebaseVertexAI/Sources/Types/Internal/Imagen/ImagenGenerationRequest.swift

@@ -30,6 +30,9 @@ public final class ImagenModel {
   /// The resource name of the model in the backend; has the format "models/model-name".
   let modelResourceName: String
 
+  /// Configuration for the backend API used by this model.
+  let apiConfig: APIConfig
+
   /// The backing service responsible for sending and receiving model requests to the backend.
   let generativeAIService: GenerativeAIService
 
@@ -42,11 +45,13 @@ public final class ImagenModel {
 
   init(name: String,
        firebaseInfo: FirebaseInfo,
+       apiConfig: APIConfig,
        generationConfig: ImagenGenerationConfig?,
        safetySettings: ImagenSafetySettings?,
        requestOptions: RequestOptions,
        urlSession: URLSession = .shared) {
     modelResourceName = name
+    self.apiConfig = apiConfig
     generativeAIService = GenerativeAIService(
       firebaseInfo: firebaseInfo,
       urlSession: urlSession
@@ -123,6 +128,7 @@ public final class ImagenModel {
     -> ImagenGenerationResponse<T> where T: Decodable, T: ImagenImageRepresentable {
     let request = ImagenGenerationRequest<T>(
       model: modelResourceName,
+      apiConfig: apiConfig,
       options: requestOptions,
       instances: [ImageGenerationInstance(prompt: prompt)],
       parameters: parameters