Add Image Iterate: nested multi-prompt still families.

Iterate runs a series of prompts as generate (no still), edit (still A), or compose (A+B), saves each output under one library collection like video extensions, and defaults to iterating from the original still.

server/api/v2/generate.post.ts

@@ -131,7 +131,7 @@ export default defineEventHandler(async (event) => {
 
   const mode = parseImageV2Mode(fields.mode)
   if (!mode) {
-    throw createError({ statusCode: 400, statusMessage: 'mode must be edit, compose, refine, or generate' })
+    throw createError({ statusCode: 400, statusMessage: 'mode must be edit, compose, refine, generate, or iterate' })
   }
   const task = parseImageV2Task(
     fields.task,
@@ -145,13 +145,19 @@ export default defineEventHandler(async (event) => {
   const extraPasses = parsePasses(fields.passes)
   const passMode = parseImagePassMode(fields.passMode)
   const aspect = parseImageAspect(fields.aspect)
-  if (!promptMid && (mode === 'generate' || aspect === 'auto')) {
+  if (!promptMid && (mode === 'generate' || mode === 'iterate' || aspect === 'auto')) {
     throw createError({ statusCode: 400, statusMessage: 'A prompt is required' })
   }
   if (extraPasses.length && (mode === 'refine' || mode === 'generate')) {
     throw createError({
       statusCode: 400,
-      statusMessage: 'Extra passes are only for Edit and Compose. Refine and Generate stay a single run.'
+      statusMessage: 'Extra passes are only for Edit, Compose, and Iterate. Refine and Generate stay a single run.'
+    })
+  }
+  if (mode === 'iterate' && !extraPasses.length) {
+    throw createError({
+      statusCode: 400,
+      statusMessage: 'Iterate needs at least two prompts. Add more iterations, or use Generate / Edit for a single run.'
     })
   }
   if (extraPasses.some(item => !item.prompt)) {
@@ -172,13 +178,24 @@ export default defineEventHandler(async (event) => {
   }
 
   const ownerKey = libraryOwnerKey(event)
-  const imageA = mode === 'generate' ? null : await resolveImageRef(ownerKey, fields.image_a, uploadedA)
-  const imageB = mode === 'refine' || mode === 'generate' ? null : await resolveImageRef(ownerKey, fields.image_b, uploadedB)
-  const mask = mode === 'refine' ? await resolveImageRef(ownerKey, fields.mask, uploadedMask) : null
-
-  if (mode !== 'generate' && !imageA) {
+  const imageA = mode === 'generate'
+    ? null
+    : await resolveImageRef(ownerKey, fields.image_a || fields.stillId, uploadedA).catch(() => null)
+  // Iterate with no still A is text-only generate iterations.
+  if (mode !== 'generate' && mode !== 'iterate' && !imageA) {
     throw createError({ statusCode: 400, statusMessage: 'image_a is required' })
   }
+  if (mode === 'iterate' && !imageA && (uploadedA || String(fields.image_a || fields.stillId || '').trim())) {
+    throw createError({ statusCode: 400, statusMessage: 'Could not load still A for iterate' })
+  }
+  const imageB = mode === 'refine' || mode === 'generate' || (mode === 'iterate' && !imageA)
+    ? null
+    : await resolveImageRef(ownerKey, fields.image_b, uploadedB).catch(() => null)
+  const mask = mode === 'refine' ? await resolveImageRef(ownerKey, fields.mask, uploadedMask) : null
+  const graphMode = mode === 'iterate'
+    ? (imageA ? (imageB ? 'compose' as const : 'edit' as const) : 'generate' as const)
+    : mode
+
   if (mode === 'refine' && !mask) {
     throw createError({
       statusCode: 400,
@@ -220,7 +237,7 @@ export default defineEventHandler(async (event) => {
   const cfg = engine === 'krea'
     ? clampImageCfg(fields.cfg, IMAGE_V2_KREA_CFG)
     : turbo ? IMAGE_V2_TURBO_CFG : clampImageCfg(fields.cfg, IMAGE_V2_CFG_DEFAULT)
-  const megapixels = mode === 'generate'
+  const megapixels = graphMode === 'generate'
     ? 0
     : fields.scaleToTotalPixels == null
       ? clampImageScaleMegapixels(fields.megapixels ?? fields.scaleMegapixels, 1)
@@ -230,31 +247,31 @@ export default defineEventHandler(async (event) => {
   const seed = fields.seed && String(fields.seed) !== 'random'
     ? Number(fields.seed)
     : Math.floor(Math.random() * 2_147_483_647)
-  const generateSize = mode === 'generate'
+  const generateSize = graphMode === 'generate'
     ? generateSizeForAspect(aspect)
     : clampImageV2Size(fields.width, fields.height, fields.aspect)
-  const size = mode === 'generate'
+  const size = graphMode === 'generate'
     ? { width: generateSize.width, height: generateSize.height }
     : imageDimensions(imageA!.data)
   const v2Mode = mode as ImageV2Mode
   const v2Task = (
-    mode === 'generate' ? 't2i' : mode === 'refine' ? 'refine' : mode === 'edit' ? 'scene' : task
+    graphMode === 'generate' ? 't2i' : graphMode === 'refine' ? 'refine' : graphMode === 'edit' ? 'scene' : task
   ) as ImageV2Task
-  const refineStrength = mode === 'generate'
+  const refineStrength = graphMode === 'generate'
     ? undefined
-    : engine === 'krea' || mode === 'refine'
+    : engine === 'krea' || graphMode === 'refine'
       ? clampImageV2Denoise(
         fields.strength,
-        mode === 'compose' ? IMAGE_V2_KREA_COMPOSE_DENOISE : mode === 'edit' ? IMAGE_V2_KREA_EDIT_DENOISE : IMAGE_V2_DENOISE_DEFAULT
+        graphMode === 'compose' ? IMAGE_V2_KREA_COMPOSE_DENOISE : graphMode === 'edit' ? IMAGE_V2_KREA_EDIT_DENOISE : IMAGE_V2_DENOISE_DEFAULT
       )
       : undefined
   const generateConsistencyModel = clampImageV2Strength(
     fields.consistency_model,
-    mode === 'generate' || engine === 'krea' ? 0 : IMAGE_V2_CONSISTENCY_MODEL
+    graphMode === 'generate' || engine === 'krea' ? 0 : IMAGE_V2_CONSISTENCY_MODEL
   )
   const generateConsistencyClip = clampImageV2Strength(
     fields.consistency_clip,
-    mode === 'generate' || engine === 'krea' ? 0 : IMAGE_V2_CONSISTENCY_CLIP
+    graphMode === 'generate' || engine === 'krea' ? 0 : IMAGE_V2_CONSISTENCY_CLIP
   )
   const conceptAllowed = isXaigenStudio()
   const generateSnofsFallback = 0
@@ -325,7 +342,7 @@ export default defineEventHandler(async (event) => {
       promptPost: promptPost || undefined,
       name: clipName,
       folderId,
-      aspect: mode === 'generate' ? generateSize.aspect : aspect,
+      aspect: graphMode === 'generate' ? generateSize.aspect : aspect,
       width: size?.width || 0,
       height: size?.height || 0,
       steps,
@@ -349,10 +366,10 @@ export default defineEventHandler(async (event) => {
       queueAutoRun: false,
       negative: String(fields.negative || '').trim(),
       passes: extraPasses,
-      passMode,
+      passMode: mode === 'iterate' && graphMode === 'generate' ? 'batch' : passMode,
       referenceStillId: savedRef?.id,
       referenceStillFilename: savedRef?.filename,
-      scaleToTotalPixels: mode !== 'generate' && megapixels > 0,
+      scaleToTotalPixels: graphMode !== 'generate' && megapixels > 0,
       scaleMegapixels: megapixels,
       imagePipeline: 'v2',
       v2Mode,
@@ -386,7 +403,7 @@ export default defineEventHandler(async (event) => {
     mode: v2Mode,
     task: v2Task,
     engine,
-    workflow: imageV2WorkflowFile(v2Mode, engine),
+    workflow: imageV2WorkflowFile(v2Mode, engine, { hasImage: Boolean(imageA), hasReference: Boolean(imageB) }),
     width: size?.width || 0,
     height: size?.height || 0,
     strength: refineStrength,