popiart-node-canvas/.planning/phases/05-image-url-server/05-02-PLAN.md

phase	plan	type
05-image-url-server	2	execute

Integrate image URL serving with Replicate and fal.ai providers.

Purpose: Enable img2img workflows by passing input images to providers as URLs, completing the multi-provider image generation pipeline. Output: Working img2img support for Replicate and fal.ai models.

<execution_context> ~/.claude/get-shit-done/workflows/execute-phase.md ~/.claude/get-shit-done/templates/summary.md </execution_context>

@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md

Prior plan in this phase:

@.planning/phases/05-image-url-server/05-01-SUMMARY.md

Relevant source files:

@src/app/api/generate/route.ts @src/lib/images/index.ts @src/store/workflowStore.ts

Tech stack available: Image URL utilities from 05-01, provider dispatch pattern in generate route Established patterns: Header-based API key passing, server-side provider execution

Provider image parameter requirements:

• Replicate: Parameter name varies by model (commonly image, input_image). Format: URI (URL or data URI).
• fal.ai: Parameter is image_url. Format: URL string or data URI.

Task 1: Update generateWithReplicate to pass image input src/app/api/generate/route.ts Modify generateWithReplicate() to include image input in prediction: - Accept images array in GenerationInput (already present) - If images array has items, add first image to predictionInput as `image` parameter - Use the image URL directly (caller will provide URL or data URI) - Log image input presence for debugging

Note: Different Replicate models use different parameter names (image, input_image, image_prompt). Start with image as it's most common for img2img models. Future enhancement could detect from model schema.

Do NOT convert base64 to URL here - that happens at the call site (workflow execution). TypeScript compiles: npx tsc --noEmit generateWithReplicate passes image parameter to prediction input when images provided

Task 2: Update generateWithFal to pass image_url parameter src/app/api/generate/route.ts Modify generateWithFal() to include image_url in request: - Accept images array in GenerationInput (already present) - If images array has items, add first image as `image_url` in requestBody - fal.ai accepts both URLs and data URIs in this field - Log image input presence for debugging

fal.ai is consistent: always use image_url parameter name. TypeScript compiles: npx tsc --noEmit generateWithFal passes image_url parameter when images provided

Task 3: Upload images to URL server with cleanup src/app/api/generate/route.ts Update the POST handler to convert large images to URLs and clean up after use: - Import uploadImageForUrl, shouldUseImageUrl, deleteImages from @/lib/images - Get base URL from request: `new URL(request.url).origin` - For Replicate and fal providers, process images array: - Track uploaded image IDs in an array for cleanup - If shouldUseImageUrl(image) returns true, call uploadImageForUrl(image, baseUrl), store ID - Otherwise, pass the base64 data URI directly (small images work fine as data URIs) - Pass processed images array to generateWithReplicate/generateWithFal - In finally block: call deleteImages(uploadedIds) to clean up stored images

Pattern:

const uploadedImageIds: string[] = [];
try {
  // Process images, track IDs
  // Call provider
} finally {
  deleteImages(uploadedImageIds);
}

This ensures:

• Small images (<256KB) use efficient data URIs
• Large images use temporary URLs served by /api/images/[id]
• Images cleaned up immediately after provider fetches them (success or failure)
• No memory accumulation
• Gemini path unchanged (it handles base64 directly) Build succeeds: npm run build Large images converted to URLs and cleaned up after provider call completes

Before declaring plan complete: - [ ] `npm run build` succeeds without errors - [ ] `npx tsc --noEmit` passes - [ ] generateWithReplicate includes image in prediction input - [ ] generateWithFal includes image_url in request body - [ ] Large images converted to URLs before provider calls

<success_criteria>

• All tasks completed
• All verification checks pass
• No TypeScript errors
• Replicate and fal.ai can receive image inputs for img2img workflows
• Phase 5 complete </success_criteria>

After completion, create `.planning/phases/05-image-url-server/05-02-SUMMARY.md`