Add Image v2 Refine for on-device regional edits.

Mask painter and denoise strength sit beside Edit and Compose. The canned hand/chest prompt helper is gone so that text stays yours.

Co-authored-by: Cursor <cursoragent@cursor.com>

server/api/v2/generate.post.ts

@@ -11,6 +11,8 @@ import {
   IMAGE_V2_STEPS_DEFAULT,
   IMAGE_V2_TURBO_CFG,
   IMAGE_V2_TURBO_STEPS,
+  IMAGE_V2_DENOISE_DEFAULT,
+  clampImageV2Denoise,
   clampImageV2Strength,
   parseImageV2Mode,
   parseImageV2Task,
@@ -37,7 +39,7 @@ async function fileFromUrl(url: string): Promise<ImageFile> {
   }
   const mime = String(res.headers.get('content-type') || 'image/png').split(';')[0]
   if (!/^image\//i.test(mime)) {
-    throw createError({ statusCode: 400, statusMessage: 'image_a / image_b URL must be an image' })
+    throw createError({ statusCode: 400, statusMessage: 'image_a / image_b / mask URL must be an image' })
   }
   const data = Buffer.from(await res.arrayBuffer())
   if (data.length > 40 * 1024 * 1024) {
@@ -72,16 +74,19 @@ function readMultipart(parts: Array<{ name?: string; filename?: string; type?: s
   const fields: Record<string, string> = {}
   let imageA: ImageFile | null = null
   let imageB: ImageFile | null = null
+  let mask: ImageFile | null = null
   for (const part of parts || []) {
     if ((part.name === 'image_a' || part.name === 'image') && part.filename && part.data?.length) {
       imageA = { filename: part.filename, data: part.data, type: part.type }
     } else if ((part.name === 'image_b' || part.name === 'image2') && part.filename && part.data?.length) {
       imageB = { filename: part.filename, data: part.data, type: part.type }
+    } else if (part.name === 'mask' && part.filename && part.data?.length) {
+      mask = { filename: part.filename, data: part.data, type: part.type }
     } else if (part.name && part.data) {
       fields[part.name] = part.data.toString('utf8')
     }
   }
-  return { fields, imageA, imageB }
+  return { fields, imageA, imageB, mask }
 }
 
 export default defineEventHandler(async (event) => {
@@ -89,6 +94,7 @@ export default defineEventHandler(async (event) => {
   let fields: Record<string, unknown> = {}
   let uploadedA: ImageFile | null = null
   let uploadedB: ImageFile | null = null
+  let uploadedMask: ImageFile | null = null
 
   if (contentType.includes('multipart/form-data')) {
     const form = await readMultipartFormData(event).catch(() => null)
@@ -96,15 +102,16 @@ export default defineEventHandler(async (event) => {
     fields = parsed.fields
     uploadedA = parsed.imageA
     uploadedB = parsed.imageB
+    uploadedMask = parsed.mask
   } else {
     fields = await readBody<Record<string, unknown>>(event).catch(() => ({}))
   }
 
   const mode = parseImageV2Mode(fields.mode)
   if (!mode) {
-    throw createError({ statusCode: 400, statusMessage: 'mode must be edit or compose' })
+    throw createError({ statusCode: 400, statusMessage: 'mode must be edit, compose, or refine' })
   }
-  const task = parseImageV2Task(fields.task, 'scene')
+  const task = parseImageV2Task(fields.task, mode === 'refine' ? 'refine' : 'scene')
   const prompt = String(fields.prompt || '').trim()
   if (!prompt) {
     throw createError({ statusCode: 400, statusMessage: 'A prompt is required' })
@@ -125,11 +132,18 @@ export default defineEventHandler(async (event) => {
 
   const ownerKey = libraryOwnerKey(event)
   const imageA = await resolveImageRef(ownerKey, fields.image_a, uploadedA)
-  const imageB = await resolveImageRef(ownerKey, fields.image_b, uploadedB)
+  const imageB = mode === 'refine' ? null : await resolveImageRef(ownerKey, fields.image_b, uploadedB)
+  const mask = mode === 'refine' ? await resolveImageRef(ownerKey, fields.mask, uploadedMask) : null
 
   if (!imageA) {
     throw createError({ statusCode: 400, statusMessage: 'image_a is required' })
   }
+  if (mode === 'refine' && !mask) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Refine requires a mask. Refusing to fall back to Edit.'
+    })
+  }
   if (mode === 'edit' && imageB) {
     throw createError({
       statusCode: 400,
@@ -166,7 +180,8 @@ export default defineEventHandler(async (event) => {
   const size = imageDimensions(imageA.data)
   const clipName = String(fields.name || '').trim().slice(0, 80)
   const v2Mode = mode as ImageV2Mode
-  const v2Task = (mode === 'edit' ? 'scene' : task) as ImageV2Task
+  const v2Task = (mode === 'refine' ? 'refine' : mode === 'edit' ? 'scene' : task) as ImageV2Task
+  const refineStrength = mode === 'refine' ? clampImageV2Denoise(fields.strength, IMAGE_V2_DENOISE_DEFAULT) : undefined
 
   const still = await rememberInputStill({
     ownerKey,
@@ -186,6 +201,15 @@ export default defineEventHandler(async (event) => {
       hideInput
     })
     : null
+  const savedMask = mask
+    ? await rememberInputStill({
+      ownerKey,
+      folderId,
+      filename: mask.filename || 'refine-mask.png',
+      data: mask.data,
+      hideInput
+    })
+    : null
 
   const studio = await addStudioJob({
     ownerKey,
@@ -228,7 +252,10 @@ export default defineEventHandler(async (event) => {
       snofsModel: clampImageV2Strength(fields.snofs_model, IMAGE_V2_SNOFS_MODEL),
       snofsClip: clampImageV2Strength(fields.snofs_clip, IMAGE_V2_SNOFS_CLIP),
       consistencyModel: clampImageV2Strength(fields.consistency_model, IMAGE_V2_CONSISTENCY_MODEL),
-      consistencyClip: clampImageV2Strength(fields.consistency_clip, IMAGE_V2_CONSISTENCY_CLIP)
+      consistencyClip: clampImageV2Strength(fields.consistency_clip, IMAGE_V2_CONSISTENCY_CLIP),
+      maskStillId: savedMask?.id,
+      maskStillFilename: savedMask?.filename,
+      refineStrength
     }
   })
   await kickStudioQueue()
@@ -248,7 +275,8 @@ export default defineEventHandler(async (event) => {
     cfg,
     mode: v2Mode,
     task: v2Task,
-    workflow: v2Mode === 'compose' ? 'klein_v2_compose.json' : 'klein_v2_edit.json',
+    workflow: v2Mode === 'refine' ? 'klein_v2_refine.json' : v2Mode === 'compose' ? 'klein_v2_compose.json' : 'klein_v2_edit.json',
+    strength: refineStrength,
     hideThumbnail,
     folderLocked
   }

server/assets/klein_v2_refine.json

@@ -0,0 +1,204 @@
+{
+  "1": {
+    "inputs": { "image": "" },
+    "class_type": "LoadImage",
+    "_meta": { "title": "Load Canvas" }
+  },
+  "30": {
+    "inputs": { "image": "" },
+    "class_type": "LoadImage",
+    "_meta": { "title": "Load Mask" }
+  },
+  "2": {
+    "inputs": {
+      "upscale_method": "lanczos",
+      "megapixels": 1,
+      "resolution_steps": 1,
+      "image": ["1", 0]
+    },
+    "class_type": "ImageScaleToTotalPixels",
+    "_meta": { "title": "Scale Canvas" }
+  },
+  "3": {
+    "inputs": { "image": ["2", 0] },
+    "class_type": "GetImageSize",
+    "_meta": { "title": "Get Canvas Size" }
+  },
+  "31": {
+    "inputs": {
+      "upscale_method": "lanczos",
+      "width": ["3", 0],
+      "height": ["3", 1],
+      "crop": "disabled",
+      "image": ["30", 0]
+    },
+    "class_type": "ImageScale",
+    "_meta": { "title": "Resize Mask to Canvas" }
+  },
+  "32": {
+    "inputs": {
+      "channel": "red",
+      "image": ["31", 0]
+    },
+    "class_type": "ImageToMask",
+    "_meta": { "title": "Mask Channel" }
+  },
+  "34": {
+    "inputs": {
+      "expand": 6,
+      "tapered_corners": true,
+      "mask": ["32", 0]
+    },
+    "class_type": "GrowMask",
+    "_meta": { "title": "Grow Mask" }
+  },
+  "4": {
+    "inputs": {
+      "unet_name": "flux-2-klein-base-9b-fp8.safetensors",
+      "weight_dtype": "default"
+    },
+    "class_type": "UNETLoader",
+    "_meta": { "title": "Load Flux.2 Klein 9B Base" }
+  },
+  "5": {
+    "inputs": {
+      "clip_name": "qwen_3_8b_fp8mixed.safetensors",
+      "type": "flux2",
+      "device": "default"
+    },
+    "class_type": "CLIPLoader",
+    "_meta": { "title": "Load Qwen 3 8B CLIP" }
+  },
+  "6": {
+    "inputs": { "vae_name": "full_encoder_small_decoder.safetensors" },
+    "class_type": "VAELoader",
+    "_meta": { "title": "Load Klein VAE" }
+  },
+  "7": {
+    "inputs": {
+      "lora_name": "klein_snofs_v1_4.safetensors",
+      "strength_model": 0.65,
+      "strength_clip": 0.3,
+      "model": ["4", 0],
+      "clip": ["5", 0]
+    },
+    "class_type": "LoraLoader",
+    "_meta": { "title": "SNOFS" }
+  },
+  "8": {
+    "inputs": {
+      "lora_name": "Flux2-Klein-9B-consistency-V2.safetensors",
+      "strength_model": 0.7,
+      "strength_clip": 0.7,
+      "model": ["7", 0],
+      "clip": ["7", 1]
+    },
+    "class_type": "LoraLoader",
+    "_meta": { "title": "Consistency" }
+  },
+  "9": {
+    "inputs": {
+      "text": "",
+      "clip": ["8", 1]
+    },
+    "class_type": "CLIPTextEncode",
+    "_meta": { "title": "Positive Prompt" }
+  },
+  "10": {
+    "inputs": {
+      "text": "",
+      "clip": ["8", 1]
+    },
+    "class_type": "CLIPTextEncode",
+    "_meta": { "title": "Negative Prompt" }
+  },
+  "11": {
+    "inputs": {
+      "pixels": ["2", 0],
+      "vae": ["6", 0]
+    },
+    "class_type": "VAEEncode",
+    "_meta": { "title": "VAE Encode Canvas" }
+  },
+  "12": {
+    "inputs": {
+      "conditioning": ["9", 0],
+      "latent": ["11", 0]
+    },
+    "class_type": "ReferenceLatent",
+    "_meta": { "title": "Reference Latent +" }
+  },
+  "13": {
+    "inputs": {
+      "conditioning": ["10", 0],
+      "latent": ["11", 0]
+    },
+    "class_type": "ReferenceLatent",
+    "_meta": { "title": "Reference Latent -" }
+  },
+  "33": {
+    "inputs": {
+      "samples": ["11", 0],
+      "mask": ["34", 0]
+    },
+    "class_type": "SetLatentNoiseMask",
+    "_meta": { "title": "Mask Latent Noise" }
+  },
+  "15": {
+    "inputs": { "noise_seed": 1 },
+    "class_type": "RandomNoise",
+    "_meta": { "title": "RandomNoise" }
+  },
+  "16": {
+    "inputs": { "sampler_name": "euler" },
+    "class_type": "KSamplerSelect",
+    "_meta": { "title": "KSamplerSelect" }
+  },
+  "17": {
+    "inputs": {
+      "scheduler": "simple",
+      "steps": 24,
+      "denoise": 0.35,
+      "model": ["8", 0]
+    },
+    "class_type": "BasicScheduler",
+    "_meta": { "title": "BasicScheduler" }
+  },
+  "18": {
+    "inputs": {
+      "cfg": 4,
+      "model": ["8", 0],
+      "positive": ["12", 0],
+      "negative": ["13", 0]
+    },
+    "class_type": "CFGGuider",
+    "_meta": { "title": "CFG Guider" }
+  },
+  "19": {
+    "inputs": {
+      "noise": ["15", 0],
+      "guider": ["18", 0],
+      "sampler": ["16", 0],
+      "sigmas": ["17", 0],
+      "latent_image": ["33", 0]
+    },
+    "class_type": "SamplerCustomAdvanced",
+    "_meta": { "title": "SamplerCustomAdvanced" }
+  },
+  "20": {
+    "inputs": {
+      "samples": ["19", 0],
+      "vae": ["6", 0]
+    },
+    "class_type": "VAEDecode",
+    "_meta": { "title": "VAE Decode" }
+  },
+  "21": {
+    "inputs": {
+      "filename_prefix": "aigen-v2-refine",
+      "images": ["20", 0]
+    },
+    "class_type": "SaveImage",
+    "_meta": { "title": "Save Image" }
+  }
+}

server/utils/generationPresets.ts

@@ -21,6 +21,8 @@ import {
   IMAGE_V2_SNOFS_CLIP,
   IMAGE_V2_SNOFS_MODEL,
   IMAGE_V2_STEPS_DEFAULT,
+  IMAGE_V2_DENOISE_DEFAULT,
+  clampImageV2Denoise,
   clampImageV2Strength,
   parseImageV2Mode,
   parseImageV2Task,
@@ -114,7 +116,7 @@ function sanitizeImageV2Settings(raw: unknown): ImageV2PresetSettings {
   const turbo = rec.turbo === true
   return {
     mode,
-    task: mode === 'compose' ? parseImageV2Task(rec.task, 'scene') : 'scene',
+    task: mode === 'compose' ? parseImageV2Task(rec.task, 'scene') : mode === 'refine' ? 'refine' : 'scene',
     negative: String(rec.negative || '').slice(0, 2000),
     snofsModel: clampImageV2Strength(rec.snofsModel ?? rec.snofs_model, IMAGE_V2_SNOFS_MODEL),
     snofsClip: clampImageV2Strength(rec.snofsClip ?? rec.snofs_clip, IMAGE_V2_SNOFS_CLIP),
@@ -123,7 +125,8 @@ function sanitizeImageV2Settings(raw: unknown): ImageV2PresetSettings {
     steps: turbo ? 8 : clampImageSteps(rec.steps, IMAGE_V2_STEPS_DEFAULT),
     cfg: turbo ? 1 : clampImageCfg(rec.cfg, IMAGE_V2_CFG_DEFAULT),
     megapixels: clampImageScaleMegapixels(rec.megapixels ?? rec.scaleMegapixels, 1),
-    turbo
+    turbo,
+    strength: mode === 'refine' ? clampImageV2Denoise(rec.strength, IMAGE_V2_DENOISE_DEFAULT) : undefined
   }
 }
 

server/utils/imageChainV2.ts

@@ -15,6 +15,7 @@ export type EditV2RunParams = {
   task: ImageV2Task
   image: EditImageFile
   reference: EditImageFile | null
+  mask?: EditImageFile | null
   prompt: string
   negative: string
   steps: number
@@ -25,11 +26,15 @@ export type EditV2RunParams = {
   consistencyModel: number
   consistencyClip: number
   megapixels: number
+  strength?: number
 }
 
 export async function runEditV2(job: Job, params: EditV2RunParams) {
   const library = job.library
   if (!library) throw new Error('Edit job is missing library metadata')
+  if (params.mode === 'refine' && !params.mask) {
+    throw new Error('Refine requires a mask. Refusing to fall back to Edit.')
+  }
   if (params.mode === 'compose' && !params.reference) {
     throw new Error('Compose requires image B. Refusing to fall back to one-image generation.')
   }
@@ -52,23 +57,35 @@ export async function runEditV2(job: Job, params: EditV2RunParams) {
     await withImageComfyHost(job.imageComfyHost, async () => {
       emitChainJob(job, {
         type: 'status',
-        message: params.mode === 'compose' ? 'Uploading stills A and B to Beast...' : 'Uploading still A to Beast...',
+        message: params.mode === 'refine'
+          ? 'Uploading canvas and mask to Beast...'
+          : params.mode === 'compose' ? 'Uploading stills A and B to Beast...' : 'Uploading still A to Beast...',
         progress: 8
       })
       const uploaded = await uploadImage(params.image, job.id)
-      const uploadedRef = params.reference
+      const uploadedRef = params.mode === 'refine'
+        ? null
+        : params.reference
+          ? await uploadImage({
+            ...params.reference,
+            filename: `ref_${params.reference.filename || 'image_b.png'}`
+          }, job.id)
+          : null
+      const uploadedMask = params.mode === 'refine' && params.mask
         ? await uploadImage({
-          ...params.reference,
-          filename: `ref_${params.reference.filename || 'image_b.png'}`
+          ...params.mask,
+          filename: `mask_${params.mask.filename || 'refine-mask.png'}`
         }, job.id)
         : null
       if (job.status === 'cancelled') throw new Error('Job interrupted.')
 
       emitChainJob(job, {
         type: 'status',
-        message: params.mode === 'compose'
-          ? `Queueing Klein v2 compose (${params.task}) on Beast...`
-          : 'Queueing Klein v2 edit on Beast...',
+        message: params.mode === 'refine'
+          ? 'Queueing Klein v2 refine on Beast...'
+          : params.mode === 'compose'
+            ? `Queueing Klein v2 compose (${params.task}) on Beast...`
+            : 'Queueing Klein v2 edit on Beast...',
         progress: 12
       })
       await ensureComfyLoraNames('image')
@@ -80,6 +97,8 @@ export async function runEditV2(job: Job, params: EditV2RunParams) {
         negative: params.negative,
         imageAName: uploaded.name,
         imageBName: uploadedRef?.name,
+        maskName: uploadedMask?.name,
+        strength: params.strength,
         snofsModel: params.snofsModel,
         snofsClip: params.snofsClip,
         consistencyModel: params.consistencyModel,
@@ -137,7 +156,7 @@ export async function runEditV2(job: Job, params: EditV2RunParams) {
         video: { filename: output.filename, subfolder: output.subfolder, type: output.type },
         imageName: uploaded.name,
         imageSubfolder: uploaded.subfolder,
-        extraImageNames: uploadedRef?.name ? [uploadedRef.name] : [],
+        extraImageNames: [uploadedRef?.name, uploadedMask?.name].filter((name): name is string => Boolean(name)),
         promptId: job.promptId
       })
 

server/utils/imageWorkflowV2.ts

@@ -1,5 +1,6 @@
 import editTemplate from '../assets/klein_v2_edit.json'
 import composeTemplate from '../assets/klein_v2_compose.json'
+import refineTemplate from '../assets/klein_v2_refine.json'
 import { IMAGE_SCALE_TO_TOTAL_PIXELS } from '~/server/utils/comfy'
 import { cachedComfyLoraNames } from '~/server/utils/loras'
 import { resolveComfyLoraName, loraIdentityKey } from '~/utils/loras'
@@ -11,6 +12,8 @@ import {
   IMAGE_V2_SNOFS_CLIP,
   IMAGE_V2_SNOFS_LORA,
   IMAGE_V2_SNOFS_MODEL,
+  IMAGE_V2_DENOISE_DEFAULT,
+  clampImageV2Denoise,
   clampImageV2Strength,
   composeImageV2Prompt,
   type ImageV2Mode,
@@ -22,6 +25,8 @@ type WorkflowGraph = Record<string, WorkflowNode>
 
 const LOAD_A = '1'
 const LOAD_B = '22'
+const LOAD_MASK = '30'
+const SCHEDULER_DENOISE = '17'
 const SCALE_A = '2'
 const SCALE_B = '23'
 const PROMPT = '9'
@@ -35,6 +40,7 @@ const CONSISTENCY = '8'
 
 export const IMAGE_V2_EDIT_WORKFLOW = 'klein_v2_edit.json'
 export const IMAGE_V2_COMPOSE_WORKFLOW = 'klein_v2_compose.json'
+export const IMAGE_V2_REFINE_WORKFLOW = 'klein_v2_refine.json'
 
 export interface ImageV2BuildParams {
   mode: ImageV2Mode
@@ -43,6 +49,8 @@ export interface ImageV2BuildParams {
   negative?: string
   imageAName: string
   imageBName?: string
+  maskName?: string
+  strength?: number
   snofsModel?: number
   snofsClip?: number
   consistencyModel?: number
@@ -87,8 +95,36 @@ function patchScaleMegapixels(graph: WorkflowGraph, megapixels: number) {
   }
 }
 
+function graphHasMaskInput(graph: WorkflowGraph) {
+  return Object.values(graph).some((node) => {
+    const mask = node.inputs?.mask
+    return mask !== undefined && mask !== null && mask !== ''
+  })
+}
+
 export function assertImageV2Graph(graph: WorkflowGraph, mode: ImageV2Mode, imageBName?: string) {
   const loaders = loadImageNames(graph)
+  if (mode === 'refine') {
+    const mask = graph[LOAD_MASK]
+    if (!mask || mask.class_type !== 'LoadImage' || !String(mask.inputs.image || '').trim()) {
+      throw createError({
+        statusCode: 500,
+        statusMessage: 'Refine job is missing the mask image. Refusing to run.'
+      })
+    }
+    if (!graphHasMaskInput(graph)) {
+      throw createError({
+        statusCode: 500,
+        statusMessage: 'Refine graph has no mask input. Refusing to run.'
+      })
+    }
+    if (!('denoise' in (graph[SCHEDULER]?.inputs || {}))) {
+      throw createError({
+        statusCode: 500,
+        statusMessage: 'Refine graph has no denoise on the sampler. Refusing to run.'
+      })
+    }
+  }
   if (mode === 'compose') {
     if (loaders.length < 2) {
       throw createError({
@@ -104,7 +140,7 @@ export function assertImageV2Graph(graph: WorkflowGraph, mode: ImageV2Mode, imag
       })
     }
   }
-  if (imageBName && loaders.length < 2) {
+  if (mode !== 'refine' && imageBName && loaders.length < 2) {
     throw createError({
       statusCode: 500,
       statusMessage: 'image_b was sent but the executed graph has no second image input.'
@@ -124,7 +160,11 @@ export function assertImageV2Graph(graph: WorkflowGraph, mode: ImageV2Mode, imag
 
 export function buildImageV2Workflow(params: ImageV2BuildParams) {
   const compose = params.mode === 'compose'
-  const graph = structuredClone(compose ? composeTemplate : editTemplate) as WorkflowGraph
+  const refine = params.mode === 'refine'
+  if (refine && !String(params.maskName || '').trim()) {
+    throw createError({ statusCode: 400, statusMessage: 'Refine requires a mask. Refusing to fall back to Edit.' })
+  }
+  const graph = structuredClone(refine ? refineTemplate : compose ? composeTemplate : editTemplate) as WorkflowGraph
   const prompt = composeImageV2Prompt(params.mode, params.task, params.prompt)
   const negative = String(params.negative || '')
   const snofsModel = clampImageV2Strength(params.snofsModel, IMAGE_V2_SNOFS_MODEL)
@@ -133,10 +173,15 @@ export function buildImageV2Workflow(params: ImageV2BuildParams) {
   const consistencyClip = clampImageV2Strength(params.consistencyClip, IMAGE_V2_CONSISTENCY_CLIP)
   const steps = clampImageSteps(params.steps, 24)
   const cfg = clampImageCfg(params.cfg, 4)
-  const workflowFile = compose ? IMAGE_V2_COMPOSE_WORKFLOW : IMAGE_V2_EDIT_WORKFLOW
+  const strength = refine ? clampImageV2Denoise(params.strength, IMAGE_V2_DENOISE_DEFAULT) : undefined
+  const workflowFile = refine ? IMAGE_V2_REFINE_WORKFLOW : compose ? IMAGE_V2_COMPOSE_WORKFLOW : IMAGE_V2_EDIT_WORKFLOW
 
   setInput(graph, LOAD_A, 'image', params.imageAName)
   if (compose) setInput(graph, LOAD_B, 'image', params.imageBName || '')
+  if (refine) {
+    setInput(graph, LOAD_MASK, 'image', params.maskName || '')
+    setInput(graph, SCHEDULER_DENOISE, 'denoise', strength)
+  }
   setInput(graph, PROMPT, 'text', prompt)
   setInput(graph, NEGATIVE, 'text', negative)
   setInput(graph, NOISE, 'noise_seed', params.seed)
@@ -152,7 +197,7 @@ export function buildImageV2Workflow(params: ImageV2BuildParams) {
   setInput(graph, CONSISTENCY, 'strength_model', consistencyModel)
   setInput(graph, CONSISTENCY, 'strength_clip', consistencyClip)
 
-  assertImageV2Graph(graph, params.mode, params.imageBName)
+  assertImageV2Graph(graph, params.mode, refine ? undefined : params.imageBName)
 
   const loaders = loadImageNames(graph)
   console.log(JSON.stringify({
@@ -160,6 +205,9 @@ export function buildImageV2Workflow(params: ImageV2BuildParams) {
     workflow: workflowFile,
     mode: params.mode,
     task: params.task,
+    canvas: { id: LOAD_A, file: graph[LOAD_A]?.inputs.image },
+    mask: refine ? { id: LOAD_MASK, file: graph[LOAD_MASK]?.inputs.image } : undefined,
+    strength,
     loadImage: Object.fromEntries(loaders.map(item => [item.id, { title: item.title, file: item.image }])),
     loras: {
       snofs: { name: graph[SNOFS]?.inputs.lora_name, model: snofsModel, clip: snofsClip },
@@ -171,14 +219,16 @@ export function buildImageV2Workflow(params: ImageV2BuildParams) {
     megapixels: clampImageScaleMegapixels(params.megapixels ?? 1)
   }))
 
-  return { graph, workflowFile, loaders, prompt }
+  return { graph, workflowFile, loaders, prompt, strength }
 }
 
 export const IMAGE_V2_NODE_LABELS: Record<string, string> = {
   '1': 'Loading image A',
   '22': 'Loading image B',
+  '30': 'Loading mask',
   '2': 'Scaling image A',
   '23': 'Scaling image B',
+  '31': 'Resizing mask',
   '4': 'Loading Flux.2 Klein 9B',
   '5': 'Loading CLIP',
   '6': 'Loading VAE',
@@ -187,6 +237,7 @@ export const IMAGE_V2_NODE_LABELS: Record<string, string> = {
   '9': 'Encoding prompt',
   '11': 'Encoding image A',
   '24': 'Encoding image B',
+  '33': 'Applying mask',
   '19': 'Sampling Klein v2',
   '20': 'Decoding still',
   '21': 'Saving still'

server/utils/studioQueue.ts

@@ -52,12 +52,15 @@ export interface StudioJobPayload {
   scaleToTotalPixels?: boolean
   scaleMegapixels?: number
   imagePipeline?: 'v1' | 'v2'
-  v2Mode?: 'edit' | 'compose'
-  v2Task?: 'scene' | 'identity' | 'outfit' | 'face_lock'
+  v2Mode?: 'edit' | 'compose' | 'refine'
+  v2Task?: 'scene' | 'identity' | 'outfit' | 'face_lock' | 'refine'
   snofsModel?: number
   snofsClip?: number
   consistencyModel?: number
   consistencyClip?: number
+  maskStillId?: string
+  maskStillFilename?: string
+  refineStrength?: number
 }
 
 export interface StudioJob {
@@ -694,7 +697,18 @@ async function startStudioEditJob(item: StudioJob) {
       : null
 
     if (payload.imagePipeline === 'v2') {
-      const mode = payload.v2Mode === 'compose' ? 'compose' : 'edit'
+      const mode = payload.v2Mode === 'compose' ? 'compose' : payload.v2Mode === 'refine' ? 'refine' : 'edit'
+      const maskId = payload.maskStillId
+      const mask = mode === 'refine' && maskId && existsSync(stillPath(item.ownerKey, maskId))
+        ? {
+          filename: payload.maskStillFilename || 'refine-mask.png',
+          data: readFileSync(stillPath(item.ownerKey, maskId)),
+          type: 'image/png'
+        }
+        : null
+      if (mode === 'refine' && !mask) {
+        throw new Error('Refine requires a mask. Refusing to fall back to Edit.')
+      }
       if (mode === 'compose' && !reference) {
         throw new Error('Compose requires image B. Refusing to fall back to one-image generation.')
       }
@@ -732,7 +746,8 @@ async function startStudioEditJob(item: StudioJob) {
         mode,
         task: payload.v2Task || 'scene',
         image,
-        reference,
+        reference: mode === 'refine' ? null : reference,
+        mask,
         prompt: payload.prompt,
         negative: payload.negative || '',
         steps: payload.steps,
@@ -742,7 +757,8 @@ async function startStudioEditJob(item: StudioJob) {
         snofsClip: payload.snofsClip ?? 0.35,
         consistencyModel: payload.consistencyModel ?? 0.7,
         consistencyClip: payload.consistencyClip ?? 0.7,
-        megapixels: payload.scaleMegapixels ?? 1
+        megapixels: payload.scaleMegapixels ?? 1,
+        strength: payload.refineStrength
       }).catch((error) => {
         const message = error instanceof Error ? error.message : String(error)
         if (live && live.status !== 'error' && live.status !== 'cancelled' && live.status !== 'deferred') {