---
phase: 05-image-url-server
plan: 02
type: execute
---

<objective>
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.
</objective>

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

<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.
</context>

<tasks>

<task type="auto">
  <name>Task 1: Update generateWithReplicate to pass image input</name>
  <files>src/app/api/generate/route.ts</files>
  <action>
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).
  </action>
  <verify>TypeScript compiles: `npx tsc --noEmit`</verify>
  <done>generateWithReplicate passes image parameter to prediction input when images provided</done>
</task>

<task type="auto">
  <name>Task 2: Update generateWithFal to pass image_url parameter</name>
  <files>src/app/api/generate/route.ts</files>
  <action>
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.
  </action>
  <verify>TypeScript compiles: `npx tsc --noEmit`</verify>
  <done>generateWithFal passes image_url parameter when images provided</done>
</task>

<task type="auto">
  <name>Task 3: Upload images to URL server with cleanup</name>
  <files>src/app/api/generate/route.ts</files>
  <action>
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:
```typescript
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)
  </action>
  <verify>Build succeeds: `npm run build`</verify>
  <done>Large images converted to URLs and cleaned up after provider call completes</done>
</task>

</tasks>

<verification>
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
</verification>

<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>

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