docs(ai-gateway): document image endpoints and GenerateImage reference images

src/modules/ai-gateway.types.ts

@@ -36,7 +36,7 @@ export interface AiGatewayModuleConfig {
  * `connection()` hands you a `baseURL` and `token` that authenticate as your
  * Base44 app. An OpenAI-compatible client is any library, such as the `openai`
  * SDK or the Vercel AI SDK, that has the same request and response format
- * as OpenAI's Chat Completions API and lets you point it at a custom `baseURL`
+ * as OpenAI's API and lets you point it at a custom `baseURL`
  * instead of OpenAI's own servers. Pass `connection()`'s values to one of
  * these clients and it works against Base44's gateway exactly as it would
  * against the provider directly, no separate account, API key, or billing
@@ -58,6 +58,15 @@ export interface AiGatewayModuleConfig {
  * Pass `'automatic'` to let Base44 choose one, or pin a specific model such
  * as `'claude_sonnet_4_6'`, `'gpt_5_5'`, or `'gemini_3_1_pro'`.
  *
+ * ## Images
+ *
+ * The gateway also serves OpenAI's image endpoints, `/images/generations`
+ * and `/images/edits`, so you can generate images and edit them using
+ * reference images. Image requests use their own set of models: pass
+ * `'automatic'` to let Base44 choose one, or pin a model such as
+ * `'gemini_3_1_flash_image'` or `'gpt_image_2'`. For request options, the
+ * full model list, and limits, see [Generate images with the AI Gateway](/developers/references/sdk/getting-started/ai-gateway-images).
+ *
  * ## Authentication Modes
  *
  * There's no permission difference between modes. Both just determine which
@@ -148,6 +157,29 @@ export interface AiGatewayModule {
    *
    * await agent.generate({ prompt: `Review this return request: ${JSON.stringify(returnRequest)}` });
    * ```
+   *
+   * @example
+   * ```typescript
+   * // Generate an image
+   * import { createClientFromRequest } from "@base44/sdk";
+   * import { generateImage } from "ai";
+   * import { createOpenAICompatible } from "@ai-sdk/openai-compatible";
+   *
+   * // Runs inside a backend function
+   * const base44 = createClientFromRequest(request);
+   * const { baseURL, token } = base44.aiGateway.connection();
+   * const models = createOpenAICompatible({ name: "base44", baseURL, apiKey: token });
+   *
+   * const { image } = await generateImage({
+   *   model: models.imageModel("automatic"),
+   *   prompt: "A watercolor illustration of a lighthouse at dawn",
+   *   // Base44 options go under the provider name you passed above
+   *   providerOptions: { base44: { aspect_ratio: "16:9" } },
+   * });
+   *
+   * const file = new File([image.uint8Array], "lighthouse.png", { type: image.mediaType });
+   * const { file_url } = await base44.integrations.Core.UploadFile({ file });
+   * ```
    */
   connection(options?: AiGatewayConnectionOptions): AiGatewayConnection;
 }

src/modules/integrations.types.ts

@@ -65,8 +65,17 @@ export interface InvokeLLMParams {
  * Parameters for the GenerateImage function.
  */
 export interface GenerateImageParams {
-  /** Description of the image to generate. */
+  /**
+   * Description of the image to generate. When you pass `existing_image_urls`,
+   * describe what to do with the reference images instead.
+   */
   prompt: string;
+  /**
+   * URLs of images to use as references, for example to edit an existing
+   * image, match a style, or add visual context. Images that can't be read are
+   * skipped. If none of them can be read, the request fails.
+   */
+  existing_image_urls?: string[];
 }
 
 export interface GenerateImageResult {
@@ -192,12 +201,17 @@ export interface CoreIntegrations {
   InvokeLLM(params: InvokeLLMParams): Promise<string | object>;
 
   /**
-   * Create AI-generated images from text prompts.
+   * Create AI-generated images from text prompts, optionally guided by reference images.
    *
    * Images are generated as PNG files at approximately 1024px on the shorter side. The
-   * exact dimensions vary by aspect ratio. 
-   * 
-   * Prompts that violate the AI provider's content policy will be refused.
+   * exact dimensions vary by aspect ratio.
+   *
+   * Pass `existing_image_urls` to edit an existing image or to guide the result
+   * with reference images. To choose the model, aspect ratio, resolution, or
+   * quality, use the [AI Gateway image endpoints](/developers/references/sdk/getting-started/ai-gateway-images)
+   * instead.
+   *
+   * Prompts that violate the AI provider's content policy are refused.
    *
    * @param params - Parameters for image generation
    * @returns Promise resolving to an object containing the URL of the generated PNG image.
@@ -210,6 +224,15 @@ export interface CoreIntegrations {
    * });
    * console.log(url); // https://...generated_image.png
    * ```
+   *
+   * @example
+   * ```typescript
+   * // Edit an existing image
+   * const {url} = await base44.integrations.Core.GenerateImage({
+   *   prompt: "Replace the background with a sunset beach",
+   *   existing_image_urls: [productPhotoUrl]
+   * });
+   * ```
    */
   GenerateImage(params: GenerateImageParams): Promise<GenerateImageResult>;