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
   }