{"record":{"id":"3b6d4cb056f3b037","repo":"CherryHQ/cherry-studio","slug":"gemini-image-models-do-not-support-mask-based-imag","errorCode":null,"errorMessage":"Gemini image models do not support mask-based image editing.","messagePattern":"Gemini image models do not support mask-based image editing\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/main/ai/provider/custom/gateway/gatewayImageModel.ts","lineNumber":53,"sourceCode":"/**\n * Wrap a gateway `LanguageModelV3` as an `ImageModelV3` that drives image\n * generation through the language API with `responseModalities: ['IMAGE']`.\n */\nexport function createGatewayGeminiImageModel(languageModel: LanguageModelV3, modelId: string): ImageModelV3 {\n  return {\n    specificationVersion: 'v3',\n    provider: GATEWAY_GOOGLE_IMAGE_PROVIDER,\n    modelId,\n    // Gemini returns a single image per generateContent call.\n    maxImagesPerCall: 1,\n    async doGenerate(options: ImageModelV3CallOptions) {\n      const { prompt, n, size, aspectRatio, seed, files, mask, providerOptions, headers, abortSignal } = options\n      const warnings: Awaited<ReturnType<ImageModelV3['doGenerate']>>['warnings'] = []\n\n      if (mask != null) {\n        // Gemini edits via full-image prompts, not masks. Match @ai-sdk/google,\n        // which rejects mask-based editing outright rather than ignoring it.\n        throw new Error('Gemini image models do not support mask-based image editing.')\n      }\n      if (n != null && n > 1) {\n        warnings.push({\n          type: 'unsupported',\n          feature: 'n',\n          details: 'Gemini image models generate a single image per call. Extra images were not requested.'\n        })\n      }\n      if (size != null) {\n        warnings.push({\n          type: 'unsupported',\n          feature: 'size',\n          details: 'This model does not support `size`. Use `aspectRatio` instead.'\n        })\n      }\n\n      // Build the user turn: prompt text + any input images (editing support).\n      const userContent: Array<","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/CherryHQ/cherry-studio/blob/726446b54cd69ffe51a276638672f6d95ca0768c/src/main/ai/provider/custom/gateway/gatewayImageModel.ts#L35-L71","documentation":"Thrown by the gateway Gemini image adapter's `doGenerate` when `options.mask` is non-null. Gemini image models (e.g. `gemini-3-pro-image`) perform edits through full-image natural-language prompts, not mask-based inpainting; passing a mask would be silently ignored, so the adapter rejects it outright to match `@ai-sdk/google`'s behavior.","triggerScenarios":"Calling image generation on a Gemini image model via the gateway with a mask supplied — e.g. an inpainting/edit flow that passes `options.mask`.","commonSituations":"A generic image-edit UI that always sends a mask regardless of model; switching an edit workflow from a mask-capable model (e.g. wanx imageedit) to Gemini without dropping the mask; assuming all edit-capable models accept masks.","solutions":["Do not send a mask for Gemini image models — express the edit as a text prompt over the full input image instead.","Route mask-based editing to a model that supports it (e.g. a DashScope wanx2.1-imageedit model).","In the UI, disable/hide the mask tool when a Gemini image model is selected."],"exampleFix":"// before\ngatewayImageModel.doGenerate({ prompt, files, mask, ... })\n// after — Gemini edits by prompt over the whole image\ngatewayImageModel.doGenerate({ prompt: 'remove the background', files, /* mask omitted */ })","handlingStrategy":"validation","validationCode":"if (isGatewayGeminiImageModel(modelId) && options.mask != null) {\n  throw new Error('Gemini image models cannot use a mask — use prompt-based editing instead')\n}","typeGuard":"const supportsMask = (modelId: string): boolean =>\n  !isGatewayGeminiImageModel(modelId)","tryCatchPattern":"try {\n  await model.doGenerate(opts)\n} catch (e) {\n  if (e instanceof Error && /mask-based image editing/.test(e.message)) {\n    // drop the mask and retry with prompt-only editing\n  }\n  throw e\n}","preventionTips":["Disable the mask tool in the UI when a Gemini image model is selected","Route mask-based edits to a mask-capable model","Check the model's capabilities before sending mask data"],"tags":["unsupported-feature","gemini","mask","image-editing","gateway"],"backgroundTag":null,"analyzedSha":"726446b54cd69ffe51a276638672f6d95ca0768c","analyzedAt":"2026-08-12T17:30:37.448Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}