diff --git a/.changeset/image-and-video-inputs.md b/.changeset/image-and-video-inputs.md
new file mode 100644
index 000000000..e6a324899
--- /dev/null
+++ b/.changeset/image-and-video-inputs.md
@@ -0,0 +1,30 @@
+---
+'@tanstack/ai': minor
+'@tanstack/ai-openai': minor
+'@tanstack/ai-gemini': minor
+'@tanstack/ai-fal': minor
+'@tanstack/ai-grok': minor
+'@tanstack/ai-openrouter': minor
+'@tanstack/ai-client': minor
+'@tanstack/ai-event-client': patch
+---
+
+`generateImage()` and `generateVideo()` now accept a multimodal `prompt`: a plain string, or an ordered array of content parts (`TextPart` / `ImagePart` / `VideoPart` / `AudioPart`) for image-conditioned generation, image-to-image, multi-reference, image-to-video, and edit / inpaint flows. Part order is meaningful — "not like this _(image)_, more like this _(image)_" — and each media part may carry a `metadata.role` hint (`'reference' | 'mask' | 'control' | 'start_frame' | 'end_frame' | 'character'`) that adapters use to route to the provider-specific field, plus an informational `metadata.tag` label for your own bookkeeping. The accepted part types are narrowed per model at compile time via each adapter's input-modality map, so passing an image part to a text-only model is a type error (with a clear runtime throw as backstop).
+
+Prompt text is always sent **verbatim** — the SDK never injects or rewrites in-prompt referencing markers. To reference inputs from your prompt, write the provider's own convention (fal Kling / Seedance `@Image1`, OpenAI / FLUX.2 `"image 1"` prose, Gemini content descriptions); see the image-generation docs for the per-provider table.
+
+Provider behavior in this release:
+
+- **OpenAI image** — Prompts with image parts route `gpt-image-2` / `gpt-image-1` / `gpt-image-1-mini` to `images.edit()` (up to 16 source images plus optional mask); `dall-e-2` routes to `images.edit()` with one source image; `dall-e-3` rejects image parts at compile time and at runtime.
+- **OpenAI video** — Sora-2 / Sora-2-Pro accept a single image part as `input_reference`; passing more than one throws.
+- **Gemini image** — Native models (`gemini-*-flash-image`, "nano-banana") map prompt parts 1:1 onto multimodal `contents`, preserving interleaved order. Imagen is text-only (compile-time + runtime rejection).
+- **fal.ai** — Field names resolve per endpoint from a map generated from the fal SDK's endpoint types (362 endpoints with nonstandard fields, e.g. nano-banana edit → `image_urls`, Kling i2v start frame → `image_url`, Veo first-last-frame → `first_frame_url` / `last_frame_url`). Defaults for endpoints not in the map: single → `image_url`, multiple → `image_urls`; `role: 'mask'` → `mask_url`; `role: 'control'` → `control_image_url`; `role: 'reference'` / `'character'` → `reference_image_urls`; video `role: 'start_frame'` / `'end_frame'` → `start_image_url` / `end_image_url`. Per-model prompt modalities are derived at the type level from the SDK's endpoint input types. Regenerate the map after a fal SDK bump with `pnpm generate:fal-image-fields` (a unit test fails when it goes stale). In `FalImageProviderOptions` / `FalVideoProviderOptions`, media-conditioning fields the mappers can populate (`image_url`, `start_image_url`, `video_url`, `audio_url`, …) are demoted from required to optional — supply them as prompt parts, or keep passing them explicitly via `modelOptions`.
+- **Grok** — New `grok-imagine-image` / `grok-imagine-image-quality` models. Prompts with image parts route to xAI's JSON `/v1/images/edits` endpoint (up to 3 source images, addressed by xAI in request order; the prompt is sent verbatim). `role: 'mask'` / `'control'` throw. Their `size` uses an `aspectRatio_resolution` template (`'16:9_2k'`, suffix optional) mirroring Gemini's native image models. `grok-2-image-1212` remains text-to-image only.
+- **OpenRouter** — Prompt parts map 1:1 onto multimodal `text` / `image_url` chat content parts, preserving interleaved order, and are forwarded to the underlying image model. URL sources pass through verbatim (no fetching or re-encoding in your process); `data` sources become data URIs.
+- **Anthropic** — Unchanged (no image generation API).
+
+A new `resolveMediaPrompt()` utility (exported from `@tanstack/ai`) is the single downrev point from the canonical interleaved prompt shape to flattened text + per-modality part buckets, for adapter authors.
+
+On the client side, `ImageGenerateInput.prompt` and `VideoGenerateInput.prompt` (`@tanstack/ai-client`, and the `useGenerateImage` / `useGenerateVideo` hooks built on them) are widened from `string` to the same `MediaPrompt` shape, so prompt parts can be sent from the browser through your server route to `generateImage()` / `generateVideo()`.
+
+Closes #618.
diff --git a/.gitignore b/.gitignore
index 6678fb779..b261f62d1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -78,3 +78,4 @@ solo.yml
 # Agent scratch output (gap-analysis reports, triage notes — generated locally)
 .agent/gap-analysis/
 .agent/triage/
+.agent/research/
diff --git a/.prettierignore b/.prettierignore
index c72af168a..a4770926f 100644
--- a/.prettierignore
+++ b/.prettierignore
@@ -5,6 +5,7 @@
 **/coverage
 **/dist
 **/docs
+packages/ai-fal/src/image/generated/
 pnpm-lock.yaml
 
 .angular
diff --git a/docs/adapters/grok.md b/docs/adapters/grok.md
index 528226903..7103895b4 100644
--- a/docs/adapters/grok.md
+++ b/docs/adapters/grok.md
@@ -160,6 +160,51 @@ const result = await generateImage({
 console.log(result.images);
 ```
 
+The grok-imagine models (`grok-imagine-image`, `grok-imagine-image-quality`)
+are aspect-ratio sized — `size` takes an `aspectRatio_resolution` template
+like `"16:9_2k"` (the `_2k` suffix is optional):
+
+```typescript
+const result = await generateImage({
+  adapter: grokImage("grok-imagine-image"),
+  prompt: "A futuristic cityscape at sunset",
+  size: "16:9_2k",
+});
+```
+
+### Image Editing (image-to-image)
+
+The grok-imagine models accept image prompt parts for image-conditioned
+generation via xAI's `/v1/images/edits` endpoint — up to 3 source images,
+addressed by xAI in the order they appear in the prompt. Per xAI's docs
+there is no in-prompt referencing syntax; write the prompt naturally and
+your text is sent verbatim:
+
+```typescript
+const result = await generateImage({
+  adapter: grokImage("grok-imagine-image"),
+  prompt: [
+    {
+      type: "text",
+      content: "Render the product in the style of the second image",
+    },
+    {
+      type: "image",
+      source: { type: "url", value: "https://example.com/product.png" },
+    },
+    {
+      type: "image",
+      source: { type: "url", value: "https://example.com/style.png" },
+    },
+  ],
+});
+```
+
+URL sources are fetched by xAI's servers, so they must be publicly
+reachable; use a `data` source for private images. `grok-2-image-1212` is
+text-to-image only — image prompt parts are a compile-time type error and
+throw at runtime.
+
 ## Text-to-Speech
 
 Generate speech with Grok TTS:
diff --git a/docs/media/image-generation.md b/docs/media/image-generation.md
index d8af2e816..9f5d1fbba 100644
--- a/docs/media/image-generation.md
+++ b/docs/media/image-generation.md
@@ -22,7 +22,7 @@ TanStack AI provides support for image generation through dedicated image adapte
 
 Image generation is handled by image adapters that follow the same tree-shakeable architecture as other adapters in TanStack AI. The image adapters support:
 
-- **OpenAI**: DALL-E 2, DALL-E 3, GPT-Image-1, and GPT-Image-1-Mini models
+- **OpenAI**: DALL-E 2, DALL-E 3, GPT-Image-1, GPT-Image-1-Mini, and GPT-Image-2 models
 - **Gemini**: Gemini native image models (NanoBanana) and Imagen 3/4 models
 - **fal.ai**: 600+ models including Nano Banana Pro, FLUX, and more
 
@@ -76,7 +76,7 @@ All image adapters support these common options:
 | Option | Type | Description |
 |--------|------|-------------|
 | `adapter` | `ImageAdapter` | Image adapter instance with model (required) |
-| `prompt` | `string` | Text description of the image to generate (required) |
+| `prompt` | `string \| MediaPromptPart[]` | Description of the image to generate (required). A plain string, or — on models that support image-conditioned generation — an ordered array of content parts interleaving text with image inputs. See [Image-Conditioned Generation](#image-conditioned-generation) below. |
 | `numberOfImages` | `number` | Number of images to generate |
 | `size` | `string` | Size of the generated image in WIDTHxHEIGHT format |
 | `modelOptions?` | `object` | Model-specific options (renamed from `providerOptions`) |
@@ -130,6 +130,169 @@ const result = await generateImage({
 })
 ```
 
+## Image-Conditioned Generation
+
+For image-to-image, reference-guided, multi-reference, and edit / inpaint
+flows, pass the `prompt` as an ordered array of content parts — the same
+`TextPart` / `ImagePart` shapes used elsewhere for multimodal content:
+
+```typescript
+import { generateImage } from '@tanstack/ai'
+import { openaiImage } from '@tanstack/ai-openai'
+
+await generateImage({
+  adapter: openaiImage('gpt-image-2'),
+  prompt: [
+    { type: 'text', content: 'Turn this into a cinematic product photo' },
+    {
+      type: 'image',
+      source: { type: 'url', value: 'https://example.com/product.png' },
+    },
+  ],
+})
+```
+
+Part order is meaningful. Providers with natively multimodal prompts
+(Gemini image models, OpenRouter) receive the parts exactly as written, so
+text can refer to its neighbouring images:
+
+```typescript
+await generateImage({
+  adapter: geminiImage('gemini-3.1-flash-image-preview'),
+  prompt: [
+    { type: 'text', content: 'Not like this' },
+    { type: 'image', source: { type: 'url', value: badExampleUrl } },
+    { type: 'text', content: 'more like this' },
+    { type: 'image', source: { type: 'url', value: goodExampleUrl } },
+  ],
+})
+```
+
+Providers with named request fields (OpenAI, fal, xAI) extract the image
+parts and flatten the text (text parts are joined verbatim, paragraph
+separated).
+
+The accepted part types are narrowed **per model at compile time**: passing
+an image part to a text-only model (e.g. `dall-e-3`, Imagen) is a type
+error, not just a runtime throw.
+
+### Referencing images from your prompt
+
+**Your prompt text is always sent verbatim — the SDK never injects or
+rewrites referencing markers.** When you want the text to refer to specific
+input images, write the provider's own convention yourself:
+
+| Provider | Convention | Example |
+| -------- | ---------- | ------- |
+| **OpenAI** (gpt-image) | Indexed prose, per OpenAI's prompting guide | `"apply the style of image 2 to image 1"` |
+| **FLUX.2 on fal / BFL** | Indexed prose (BFL's docs parse `image N`) | `"subject from image 1, style from image 2"` |
+| **Gemini** (native image models) | Describe the reference by content/role | `"using the attached fabric sample as the texture"` |
+| **fal Kling / Seedance endpoints** | `@`-tags, 1-indexed by input order | `"Put @Image1 in the style of @Image2"` |
+| **xAI grok-imagine** | No in-prompt syntax — images addressed in request order | `"render the product in the style of the second image"` |
+
+To keep track of which part you meant by "image 2" or `@Image2`, you can
+label parts with the informational `metadata.tag` field — the SDK ignores
+it, but it keeps your code self-documenting:
+
+```typescript
+prompt: [
+  { type: 'text', content: 'Put @Image1 in the style of @Image2' },
+  { type: 'image', source: { type: 'url', value: productUrl },
+    metadata: { tag: 'product' } },
+  { type: 'image', source: { type: 'url', value: styleUrl },
+    metadata: { tag: 'style' } },
+]
+```
+
+### Source format
+
+`ImagePart.source` is a discriminated union supporting both URLs and inline
+base64 data — pass whichever you have:
+
+```typescript
+// URL source
+{ type: 'image', source: { type: 'url', value: 'https://example.com/img.png' } }
+
+// Inline base64 data (mimeType required)
+{ type: 'image', source: { type: 'data', value: base64String, mimeType: 'image/png' } }
+```
+
+OpenAI's edit endpoint requires file uploads; the adapter fetches URL sources
+and converts base64 to a `File` automatically.
+
+### Role hints via `metadata.role`
+
+When a generation has multiple inputs with different roles (mask vs reference
+vs start/end frame), set `metadata.role` on each part. Adapters route by role
+to the provider-specific field; parts without a role fall back to positional
+mapping.
+
+| Role            | Maps to                                                                                |
+| --------------- | -------------------------------------------------------------------------------------- |
+| `'reference'`   | fal `reference_image_urls`; Gemini multimodal part; positional fallback                |
+| `'character'`   | Same as `'reference'`; Veo `referenceImages` slot (planned — no Veo adapter yet)       |
+| `'mask'`        | OpenAI `mask` (gpt-image-2, gpt-image-1, dall-e-2); fal `mask_url`                     |
+| `'control'`     | fal `control_image_url` (ControlNet / depth / pose conditioning)                       |
+| `'start_frame'` | fal `start_image_url`; Veo `image` (planned) (used by `generateVideo`)                 |
+| `'end_frame'`   | fal `end_image_url`; Veo `lastFrame` (planned) (used by `generateVideo`)               |
+
+#### Inpaint / edit with a mask
+
+```typescript
+await generateImage({
+  adapter: openaiImage('gpt-image-2'),
+  prompt: [
+    { type: 'text', content: 'Replace the masked region with a tree' },
+    {
+      type: 'image',
+      source: { type: 'url', value: photoUrl },
+    },
+    {
+      type: 'image',
+      source: { type: 'url', value: maskUrl },
+      metadata: { role: 'mask' },
+    },
+  ],
+})
+```
+
+#### Multi-reference composition
+
+```typescript
+await generateImage({
+  adapter: geminiImage('gemini-3.1-flash-image-preview'),
+  prompt: [
+    {
+      type: 'text',
+      content:
+        'Generate a new image of the product using the style of the second reference',
+    },
+    {
+      type: 'image',
+      source: { type: 'url', value: 'https://example.com/product.png' },
+    },
+    {
+      type: 'image',
+      source: { type: 'url', value: 'https://example.com/style.png' },
+    },
+  ],
+})
+```
+
+### Provider support
+
+| Provider     | Behavior                                                                                                  |
+| ------------ | --------------------------------------------------------------------------------------------------------- |
+| **OpenAI**   | `gpt-image-2` / `gpt-image-1` / `gpt-image-1-mini` → routes to `images.edit()`, up to 16 source images plus optional mask.<br>`dall-e-2` → `images.edit()` with 1 source image only.<br>`dall-e-3` → throws (no edit support). |
+| **Gemini**   | Native models (`gemini-*-flash-image`, "nano-banana", etc.) → prompt parts map 1:1 onto multimodal `contents`, preserving interleaved order. Up to ~14 input images (provider limit, not enforced by the SDK).<br>Imagen models → throws (text-to-image only). |
+| **fal.ai**   | Field names resolve per endpoint from a map generated from the fal SDK's endpoint types (e.g. nano-banana edit gets `image_urls`, Fooocus masks get `mask_image_url`). Defaults for unknown endpoints: 1 input → `image_url`; multiple → `image_urls`; `role: 'mask'` → `mask_url`; `role: 'control'` → `control_image_url`; `role: 'reference'` / `'character'` → `reference_image_urls`. Override with `modelOptions` for endpoint-specific fields. |
+| **Grok**     | grok-imagine models → xAI's `/v1/images/edits` (up to 3 source images, addressed by xAI in request order; prompt sent verbatim). `role: 'mask'` / `'control'` throw (no Imagine API equivalent). `grok-2-image-1212` throws (text-to-image only). |
+| **OpenRouter** | Prompt parts map 1:1 onto multimodal `image_url` / `text` content parts, preserving interleaved order, and are forwarded to the underlying image model.                                                                                    |
+| **Anthropic** | n/a — no image generation API.                                                                                                                                                                          |
+
+Adapters that don't support image-conditioned generation throw a clear
+runtime error so calls fail fast rather than silently dropping the inputs.
+
 ## Model Options
 
 ### OpenAI Model Options
diff --git a/docs/media/video-generation.md b/docs/media/video-generation.md
index 4af93f020..3c497b053 100644
--- a/docs/media/video-generation.md
+++ b/docs/media/video-generation.md
@@ -363,11 +363,93 @@ And returns:
 | Option | Type | Description |
 |--------|------|-------------|
 | `adapter` | `VideoAdapter` | Video adapter instance with model (required) |
-| `prompt` | `string` | Text description of the video to generate (required) |
+| `prompt` | `string \| MediaPromptPart[]` | Description of the video to generate (required). A plain string, or — on models that support conditioned generation — an ordered array of content parts interleaving text with image / video / audio inputs. See [Image-to-Video](#image-to-video) below. |
 | `size` | `string` | Video resolution in WIDTHxHEIGHT format |
 | `duration` | `number` | Video duration in seconds (maps to `seconds` parameter in API) |
 | `modelOptions?` | `object` | Model-specific options (renamed from `providerOptions`) |
 
+## Image-to-Video
+
+For starting-frame, ending-frame, and reference-image conditioned video
+generation, pass the `prompt` as an array of content parts:
+
+```typescript
+import { generateVideo } from '@tanstack/ai'
+import { openaiVideo } from '@tanstack/ai-openai'
+
+const { jobId } = await generateVideo({
+  adapter: openaiVideo('sora-2'),
+  prompt: [
+    {
+      type: 'text',
+      content:
+        'Animate this still into a slow cinematic push-in with subtle motion',
+    },
+    {
+      type: 'image',
+      source: {
+        type: 'data',
+        value: base64Image,
+        mimeType: 'image/png',
+      },
+    },
+  ],
+})
+```
+
+The accepted part types are narrowed **per model at compile time** — fal
+endpoints, for example, only admit image / video / audio parts that their
+SDK input type actually declares fields for.
+
+Prompt text is always sent **verbatim** — the SDK never injects or rewrites
+in-prompt referencing markers. Some fal video endpoints have their own
+referencing syntax you can write directly in your text (e.g. Kling v3
+elements as `@Element1`, Seedance 2.0 reference-to-video as `@Image1` /
+`@Video1` / `@Audio1`, 1-indexed by input order); Veo and Sora take
+reference images as plain inputs with naturally written prompts. See
+[Referencing images from your prompt](./image-generation.md#referencing-images-from-your-prompt)
+for the per-provider table.
+
+### Role hints
+
+Each `ImagePart` can carry an optional `metadata.role` hint that the
+adapter uses to route the input to the provider-specific field:
+
+| Role            | Maps to                                                       |
+| --------------- | ------------------------------------------------------------- |
+| `'start_frame'` | fal `start_image_url` (positional default for the first input)         |
+| `'end_frame'`   | fal `end_image_url` (Veo `lastFrame` planned — no Veo adapter yet)      |
+| `'reference'`   | fal `reference_image_urls` (Veo `referenceImages` planned)              |
+| `'character'`   | Same as `'reference'` — character consistency images                    |
+
+```typescript
+import { falVideo } from '@tanstack/ai-fal'
+
+await generateVideo({
+  adapter: falVideo('fal-ai/kling-video/v3/pro/image-to-video'),
+  prompt: [
+    { type: 'image', source: { type: 'url', value: firstFrameUrl } },
+    { type: 'text', content: 'Slow cinematic push-in then a hard cut' },
+    {
+      type: 'image',
+      source: { type: 'url', value: lastFrameUrl },
+      metadata: { role: 'end_frame' },
+    },
+  ],
+})
+```
+
+### Provider support
+
+| Provider     | Image-to-Video Behavior                                                                                  |
+| ------------ | -------------------------------------------------------------------------------------------------------- |
+| **OpenAI**   | Sora-2 / Sora-2-Pro → the image part goes to `input_reference`; flattened text is the prompt. Single image only — throws if more than one. |
+| **fal.ai**   | Field names resolve per endpoint from a map generated from the fal SDK's endpoint types — e.g. `role: 'start_frame'` lands on `image_url` for Kling/Veo image-to-video, `first_frame_url` for first-last-frame endpoints, and `start_image_url` otherwise. Defaults: single input → `image_url` (start frame); `role: 'end_frame'` → `end_image_url`; `role: 'reference'` / `'character'` → `reference_image_urls`. Override per-endpoint via `modelOptions` — the media-conditioning fields are typed optional there (even when the endpoint requires them) since they usually arrive as prompt parts. |
+| **Gemini**   | Veo adapter not yet implemented — image prompt parts will be supported when Veo lands.                    |
+
+Adapters whose underlying API can't accept image inputs throw a clear
+runtime error so calls fail fast.
+
 ### Supported Sizes
 
 Based on [OpenAI API docs](https://platform.openai.com/docs/api-reference/videos/create):
diff --git a/examples/ts-react-media/src/components/ImageGenerator.tsx b/examples/ts-react-media/src/components/ImageGenerator.tsx
index 484df42c9..81dd1a5f3 100644
--- a/examples/ts-react-media/src/components/ImageGenerator.tsx
+++ b/examples/ts-react-media/src/components/ImageGenerator.tsx
@@ -1,10 +1,13 @@
-import { useState } from 'react'
-import { ImageIcon, Loader2, Shuffle } from 'lucide-react'
+import { useRef, useState } from 'react'
+import { ImageIcon, Loader2, Plus, Shuffle, X } from 'lucide-react'
 import type { ImageGenerationResult } from '@tanstack/ai'
+import type { MediaPrompt } from '@tanstack/ai/client'
 
 import { generateImageFn } from '@/lib/server-functions'
 import { getRandomImagePrompt } from '@/lib/prompts'
 import { IMAGE_MODELS } from '@/lib/models'
+import { readImageFile, toImagePart } from '@/lib/media'
+import type { AttachedImage } from '@/lib/media'
 
 interface ImageGeneratorProps {
   onImageGenerated?: (imageUrl: string) => void
@@ -32,11 +35,37 @@ export default function ImageGenerator({
   const [selectedModel, setSelectedModel] = useState<string>('all')
   const [isLoading, setIsLoading] = useState(false)
   const [results, setResults] = useState<Record<string, ModelResult>>({})
+  const [images, setImages] = useState<Array<AttachedImage>>([])
+  const fileInputRef = useRef<HTMLInputElement>(null)
 
   const currentModel = IMAGE_MODELS.find((m) => m.id === selectedModel)
 
+  // When images are attached, send an ordered parts array (text first, then one
+  // image part per attachment). Otherwise send the plain string. Only image-capable
+  // models accept image inputs — unsupported models surface a server error.
+  const buildPrompt = (): MediaPrompt => {
+    if (images.length === 0) return prompt
+    return [
+      { type: 'text', content: prompt },
+      ...images.map((image) => toImagePart(image)),
+    ]
+  }
+
+  const handleImageSelect = async (e: React.ChangeEvent<HTMLInputElement>) => {
+    const files = Array.from(e.target.files ?? [])
+    if (fileInputRef.current) fileInputRef.current.value = ''
+    if (files.length === 0) return
+    const attached = await Promise.all(files.map((file) => readImageFile(file)))
+    setImages((prev) => [...prev, ...attached])
+  }
+
+  const removeImage = (id: string) => {
+    setImages((prev) => prev.filter((image) => image.id !== id))
+  }
+
   const handleGenerate = async () => {
     if (!prompt.trim()) return
+    const builtPrompt = buildPrompt()
 
     setIsLoading(true)
     setResults({})
@@ -53,7 +82,7 @@ export default function ImageGenerator({
       const promises = IMAGE_MODELS.map(async (model) => {
         try {
           const response = await generateImageFn({
-            data: { prompt, model: model.id },
+            data: { prompt: builtPrompt, model: model.id },
           })
           setResults((prev) => ({
             ...prev,
@@ -83,7 +112,7 @@ export default function ImageGenerator({
 
       try {
         const response = await generateImageFn({
-          data: { prompt, model: selectedModel },
+          data: { prompt: builtPrompt, model: selectedModel },
         })
         setResults({ [selectedModel]: { status: 'success', result: response } })
         const image = response.images[0]
@@ -162,6 +191,55 @@ export default function ImageGenerator({
           />
         </div>
 
+        <div>
+          <div className="flex items-center justify-between mb-2">
+            <label className="text-sm font-medium text-gray-300">
+              Reference Images
+            </label>
+            <span className="text-xs text-gray-500">
+              Supported by Gemini native (NanoBanana) models only
+            </span>
+          </div>
+          <div className="flex flex-wrap gap-2">
+            {images.map((image) => (
+              <div
+                key={image.id}
+                className="relative w-20 h-20 rounded-lg overflow-hidden border border-gray-700"
+              >
+                <img
+                  src={image.dataUrl}
+                  alt={image.name}
+                  className="w-full h-full object-cover"
+                />
+                <button
+                  onClick={() => removeImage(image.id)}
+                  disabled={isLoading}
+                  className="absolute top-1 right-1 p-0.5 bg-gray-900/80 hover:bg-gray-800 rounded-full text-white disabled:opacity-50"
+                  aria-label={`Remove ${image.name}`}
+                >
+                  <X className="w-3.5 h-3.5" />
+                </button>
+              </div>
+            ))}
+            <button
+              onClick={() => fileInputRef.current?.click()}
+              disabled={isLoading}
+              className="w-20 h-20 flex flex-col items-center justify-center gap-1 border-2 border-dashed border-gray-600 hover:border-gray-500 rounded-lg text-gray-400 hover:text-gray-300 transition-colors disabled:opacity-50"
+            >
+              <Plus className="w-5 h-5" />
+              <span className="text-xs">Add</span>
+            </button>
+          </div>
+          <input
+            ref={fileInputRef}
+            type="file"
+            accept="image/*"
+            multiple
+            onChange={handleImageSelect}
+            className="hidden"
+          />
+        </div>
+
         <button
           onClick={handleGenerate}
           disabled={isLoading || !prompt.trim()}
diff --git a/examples/ts-react-media/src/components/VideoGenerator.tsx b/examples/ts-react-media/src/components/VideoGenerator.tsx
index 13fd69a8b..35dbf54ef 100644
--- a/examples/ts-react-media/src/components/VideoGenerator.tsx
+++ b/examples/ts-react-media/src/components/VideoGenerator.tsx
@@ -9,6 +9,7 @@ import {
 } from '@/lib/server-functions'
 import { VIDEO_MODELS } from '@/lib/models'
 import { getRandomVideoPrompt } from '@/lib/prompts'
+import { imageUrlToPart, readImageFile } from '@/lib/media'
 
 type JobState =
   | { status: 'idle' }
@@ -61,15 +62,12 @@ export default function VideoGenerator({
     }
   }, [])
 
-  const handleImageSelect = (e: React.ChangeEvent<HTMLInputElement>) => {
+  const handleImageSelect = async (e: React.ChangeEvent<HTMLInputElement>) => {
     const file = e.target.files?.[0]
+    if (fileInputRef.current) fileInputRef.current.value = ''
     if (!file) return
-
-    const reader = new FileReader()
-    reader.onload = (event) => {
-      setImagePreview(event.target?.result as string)
-    }
-    reader.readAsDataURL(file)
+    const attached = await readImageFile(file)
+    setImagePreview(attached.dataUrl)
   }
 
   const clearImage = () => {
@@ -136,13 +134,20 @@ export default function VideoGenerator({
     }))
 
     try {
-      const imageUrl =
-        mode === 'image-to-video' ? (imagePreview ?? undefined) : undefined
+      // Image-to-video sends the start frame as a prompt part — the fal
+      // adapter routes `role: 'start_frame'` to the endpoint's start-image
+      // field (e.g. `image_url` on Kling i2v).
+      const builtPrompt =
+        mode === 'image-to-video' && imagePreview
+          ? [
+              { type: 'text' as const, content: prompt },
+              imageUrlToPart(imagePreview, { role: 'start_frame' }),
+            ]
+          : prompt
       const result = await createVideoJobFn({
         data: {
-          prompt,
+          prompt: builtPrompt,
           model: modelId,
-          ...(imageUrl !== undefined && { imageUrl }),
         },
       })
 
diff --git a/examples/ts-react-media/src/lib/media.ts b/examples/ts-react-media/src/lib/media.ts
new file mode 100644
index 000000000..40d82c039
--- /dev/null
+++ b/examples/ts-react-media/src/lib/media.ts
@@ -0,0 +1,78 @@
+import type { MediaInputMetadata, MediaPromptPart } from '@tanstack/ai/client'
+
+/**
+ * An image the user attached as conditioning input. `dataUrl` is the full
+ * `data:<mime>;base64,...` string used directly for the thumbnail preview;
+ * `base64` is the same payload with the prefix stripped for the prompt part.
+ */
+export interface AttachedImage {
+  id: string
+  name: string
+  mimeType: string
+  /** Full data URL, used for the <img> preview. */
+  dataUrl: string
+  /** Base64 payload without the `data:` prefix, used for the prompt part. */
+  base64: string
+}
+
+/** Reads a File into an AttachedImage (data URL preview + raw base64 payload). */
+export function readImageFile(file: File): Promise<AttachedImage> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader()
+    reader.onerror = () =>
+      reject(reader.error ?? new Error('Failed to read file'))
+    reader.onload = () => {
+      const dataUrl = reader.result
+      if (typeof dataUrl !== 'string') {
+        reject(new Error('Unexpected file read result'))
+        return
+      }
+      const base64 = dataUrl.slice(dataUrl.indexOf(',') + 1)
+      resolve({
+        id: crypto.randomUUID(),
+        name: file.name,
+        mimeType: file.type,
+        dataUrl,
+        base64,
+      })
+    }
+    reader.readAsDataURL(file)
+  })
+}
+
+/** Builds an image prompt part from an attached image, with optional role hint. */
+export function toImagePart(
+  image: AttachedImage,
+  metadata?: MediaInputMetadata,
+): MediaPromptPart {
+  return {
+    type: 'image',
+    source: { type: 'data', value: image.base64, mimeType: image.mimeType },
+    ...(metadata ? { metadata } : {}),
+  }
+}
+
+/**
+ * Builds an image prompt part from a URL string — either a remote URL
+ * (passed through as a `url` source) or a `data:` URL (decomposed into a
+ * `data` source so adapters that upload files get the raw payload).
+ */
+export function imageUrlToPart(
+  url: string,
+  metadata?: MediaInputMetadata,
+): MediaPromptPart {
+  const meta = metadata ? { metadata } : {}
+  if (!url.startsWith('data:')) {
+    return { type: 'image', source: { type: 'url', value: url }, ...meta }
+  }
+  const comma = url.indexOf(',')
+  const mimeType = url.slice(5, comma).split(';')[0]
+  if (comma === -1 || !mimeType) {
+    throw new Error('data: URL is missing a mime type')
+  }
+  return {
+    type: 'image',
+    source: { type: 'data', value: url.slice(comma + 1), mimeType },
+    ...meta,
+  }
+}
diff --git a/examples/ts-react-media/src/lib/server-functions.ts b/examples/ts-react-media/src/lib/server-functions.ts
index 21029e74a..3b25b16cc 100644
--- a/examples/ts-react-media/src/lib/server-functions.ts
+++ b/examples/ts-react-media/src/lib/server-functions.ts
@@ -4,10 +4,72 @@ import { geminiImage } from '@tanstack/ai-gemini'
 import { generateImage, generateVideo, getVideoJobStatus } from '@tanstack/ai'
 
 import type { FalModel } from '@tanstack/ai-fal'
+import type {
+  ImagePart,
+  MediaInputMetadata,
+  MediaPrompt,
+  TextPart,
+} from '@tanstack/ai/client'
+
+/** A prompt restricted to text — accepted by every (incl. text-only) model. */
+type TextPrompt = string | Array<TextPart>
+/** A prompt of text + image parts — accepted by image-conditioned models. */
+type ImagePrompt = string | Array<TextPart | ImagePart<MediaInputMetadata>>
+
+/** True when the prompt carries text — a non-empty string or any prompt part. */
+function hasPromptContent(prompt: MediaPrompt): boolean {
+  return typeof prompt === 'string'
+    ? prompt.trim().length > 0
+    : prompt.length > 0
+}
+
+/**
+ * Narrows a wire `MediaPrompt` to a text + image prompt for image-conditioned
+ * models, throwing on any other part kind (video/audio) so unsupported inputs
+ * fail fast rather than being silently dropped.
+ */
+function asImagePrompt(prompt: MediaPrompt): ImagePrompt {
+  if (typeof prompt === 'string') return prompt
+  return prompt.map((part) => {
+    if (part.type === 'text' || part.type === 'image') return part
+    throw new Error(`Unsupported prompt part for image model: ${part.type}`)
+  })
+}
+
+/**
+ * Narrows a wire `MediaPrompt` to a text-only prompt, throwing if any image /
+ * video / audio part is present (text-to-image models can't accept inputs).
+ */
+function asTextPrompt(prompt: MediaPrompt): TextPrompt {
+  if (typeof prompt === 'string') return prompt
+  return prompt.map((part) => {
+    if (part.type === 'text') return part
+    throw new Error(
+      `Model does not support image inputs (received ${part.type} part)`,
+    )
+  })
+}
+
+/**
+ * Like `asImagePrompt`, but additionally requires at least one image part —
+ * image-to-video endpoints need a start frame.
+ */
+function asImageToVideoPrompt(
+  prompt: MediaPrompt,
+): Array<TextPart | ImagePart<MediaInputMetadata>> {
+  const narrowed = asImagePrompt(prompt)
+  if (
+    typeof narrowed === 'string' ||
+    !narrowed.some((part) => part.type === 'image')
+  ) {
+    throw new Error('Start image is required for image-to-video')
+  }
+  return narrowed
+}
 
 export const generateImageFn = createServerFn({ method: 'POST' })
-  .inputValidator((data: { prompt: string; model: string }) => {
-    if (!data.prompt.trim()) throw new Error('Prompt is required')
+  .inputValidator((data: { prompt: MediaPrompt; model: string }) => {
+    if (!hasPromptContent(data.prompt)) throw new Error('Prompt is required')
     if (!data.model) throw new Error('Model is required')
     return data
   })
@@ -20,7 +82,7 @@ export const generateImageFn = createServerFn({ method: 'POST' })
       case 'fal-ai/nano-banana-pro': {
         return generateImage({
           adapter: falImage('fal-ai/nano-banana-pro'),
-          prompt: data.prompt,
+          prompt: asTextPrompt(data.prompt),
           numberOfImages: 1,
           size: '16:9_4K',
           modelOptions: {
@@ -31,7 +93,7 @@ export const generateImageFn = createServerFn({ method: 'POST' })
       case 'xai/grok-imagine-image': {
         return generateImage({
           adapter: falImage('xai/grok-imagine-image'),
-          prompt: data.prompt,
+          prompt: asTextPrompt(data.prompt),
           numberOfImages: 1,
           size: '16:9_4K',
         })
@@ -40,7 +102,7 @@ export const generateImageFn = createServerFn({ method: 'POST' })
         // NOTE: Newer models are untyped (at the moment)
         return generateImage({
           adapter: falImage('fal-ai/flux-2/klein/9b'),
-          prompt: data.prompt,
+          prompt: asTextPrompt(data.prompt),
           numberOfImages: 1,
           size: 'landscape_16_9',
         })
@@ -48,7 +110,7 @@ export const generateImageFn = createServerFn({ method: 'POST' })
       case 'fal-ai/z-image/turbo': {
         return generateImage({
           adapter: falImage('fal-ai/z-image/turbo'),
-          prompt: data.prompt,
+          prompt: asTextPrompt(data.prompt),
           numberOfImages: 1,
           size: 'landscape_16_9',
           modelOptions: {
@@ -60,7 +122,7 @@ export const generateImageFn = createServerFn({ method: 'POST' })
       case 'gemini-3.1-flash-image-preview': {
         return generateImage({
           adapter: geminiImage('gemini-3.1-flash-image-preview'),
-          prompt: data.prompt,
+          prompt: asImagePrompt(data.prompt),
           numberOfImages: 1,
           size: '16:9_4K',
         })
@@ -68,7 +130,7 @@ export const generateImageFn = createServerFn({ method: 'POST' })
       case 'gemini-3-pro-image-preview': {
         return generateImage({
           adapter: geminiImage('gemini-3-pro-image-preview'),
-          prompt: data.prompt,
+          prompt: asImagePrompt(data.prompt),
           numberOfImages: 1,
           size: '16:9_4K',
         })
@@ -76,7 +138,7 @@ export const generateImageFn = createServerFn({ method: 'POST' })
       case 'imagen-4.0-ultra-generate-001': {
         return generateImage({
           adapter: geminiImage('imagen-4.0-ultra-generate-001'),
-          prompt: data.prompt,
+          prompt: asTextPrompt(data.prompt),
           numberOfImages: 1,
           size: '1024x1024',
         })
@@ -84,7 +146,7 @@ export const generateImageFn = createServerFn({ method: 'POST' })
       case 'imagen-4.0-generate-001': {
         return generateImage({
           adapter: geminiImage('imagen-4.0-generate-001'),
-          prompt: data.prompt,
+          prompt: asTextPrompt(data.prompt),
           numberOfImages: 1,
           size: '1024x1024',
         })
@@ -92,7 +154,7 @@ export const generateImageFn = createServerFn({ method: 'POST' })
       case 'imagen-4.0-fast-generate-001': {
         return generateImage({
           adapter: geminiImage('imagen-4.0-fast-generate-001'),
-          prompt: data.prompt,
+          prompt: asTextPrompt(data.prompt),
           numberOfImages: 1,
           size: '1024x1024',
         })
@@ -103,20 +165,21 @@ export const generateImageFn = createServerFn({ method: 'POST' })
   })
 
 export const createVideoJobFn = createServerFn({ method: 'POST' })
-  .inputValidator(
-    (data: { prompt: string; model: string; imageUrl?: string }) => {
-      if (!data.prompt.trim()) throw new Error('Prompt is required')
-      if (!data.model) throw new Error('Model is required')
-      return data
-    },
-  )
+  .inputValidator((data: { prompt: MediaPrompt; model: string }) => {
+    if (!hasPromptContent(data.prompt)) throw new Error('Prompt is required')
+    if (!data.model) throw new Error('Model is required')
+    return data
+  })
   .handler(async ({ data }) => {
+    // Image-to-video models receive the start frame as a prompt part
+    // (role: 'start_frame') — the fal adapter routes it to the endpoint's
+    // start-image field. Text-to-video models take the text prompt only.
     switch (data.model) {
       // Text-to-video models
       case 'fal-ai/kling-video/v3/pro/text-to-video': {
         return generateVideo({
           adapter: falVideo('fal-ai/kling-video/v3/pro/text-to-video'),
-          prompt: data.prompt,
+          prompt: asTextPrompt(data.prompt),
           size: '16:9',
           modelOptions: {
             duration: '5',
@@ -128,7 +191,7 @@ export const createVideoJobFn = createServerFn({ method: 'POST' })
         // This makes use of existing types and avoids type errors
         return generateVideo({
           adapter: falVideo('fal-ai/veo3.1'),
-          prompt: data.prompt,
+          prompt: asTextPrompt(data.prompt),
           size: '16:9_1080p',
           modelOptions: {
             duration: '4s',
@@ -138,7 +201,7 @@ export const createVideoJobFn = createServerFn({ method: 'POST' })
       case 'xai/grok-imagine-video/text-to-video': {
         return generateVideo({
           adapter: falVideo('xai/grok-imagine-video/text-to-video'),
-          prompt: data.prompt,
+          prompt: asTextPrompt(data.prompt),
           size: '16:9_720p',
           modelOptions: {
             duration: 5,
@@ -148,61 +211,46 @@ export const createVideoJobFn = createServerFn({ method: 'POST' })
       case 'fal-ai/ltx-2.3/text-to-video/fast': {
         return generateVideo({
           adapter: falVideo('fal-ai/ltx-2.3/text-to-video/fast'),
-          prompt: data.prompt,
+          prompt: asTextPrompt(data.prompt),
           size: '16:9_2160p',
         })
       }
       // Image-to-video models
       case 'fal-ai/kling-video/v3/pro/image-to-video': {
-        if (!data.imageUrl)
-          throw new Error('Image URL is required for image-to-video')
         return generateVideo({
           adapter: falVideo('fal-ai/kling-video/v3/pro/image-to-video'),
-          prompt: data.prompt,
+          prompt: asImageToVideoPrompt(data.prompt),
           modelOptions: {
-            start_image_url: data.imageUrl,
             generate_audio: true,
             duration: '5',
           },
         })
       }
       case 'fal-ai/veo3.1/image-to-video': {
-        if (!data.imageUrl) {
-          throw new Error('Image URL is required for image-to-video')
-        }
         return generateVideo({
           adapter: falVideo('fal-ai/veo3.1/image-to-video'),
-          prompt: data.prompt,
+          prompt: asImageToVideoPrompt(data.prompt),
           size: '16:9_1080p',
           modelOptions: {
-            image_url: data.imageUrl,
             duration: '4s',
           },
         })
       }
       case 'xai/grok-imagine-video/image-to-video': {
-        if (!data.imageUrl)
-          throw new Error('Image URL is required for image-to-video')
         return generateVideo({
           adapter: falVideo('xai/grok-imagine-video/image-to-video'),
-          prompt: data.prompt,
+          prompt: asImageToVideoPrompt(data.prompt),
           size: '16:9_720p',
           modelOptions: {
-            image_url: data.imageUrl,
             duration: 5,
           },
         })
       }
       case 'fal-ai/ltx-2.3/image-to-video/fast': {
-        if (!data.imageUrl)
-          throw new Error('Image URL is required for image-to-video')
         return generateVideo({
           adapter: falVideo('fal-ai/ltx-2.3/image-to-video/fast'),
-          prompt: data.prompt,
+          prompt: asImageToVideoPrompt(data.prompt),
           size: '16:9_2160p',
-          modelOptions: {
-            image_url: data.imageUrl,
-          },
         })
       }
       default:
diff --git a/package.json b/package.json
index 924d53b10..6ffff085c 100644
--- a/package.json
+++ b/package.json
@@ -37,6 +37,7 @@
     "dev:chat": "pnpm --filter ts-react-chat dev",
     "format": "prettier --experimental-cli --ignore-unknown '**/*' --write",
     "generate-docs": "node scripts/generate-docs.ts && pnpm run copy:readme",
+    "generate:fal-image-fields": "tsx scripts/generate-fal-image-field-map.ts",
     "generate:models": "pnpm generate:models:fetch && pnpm regenerate:models && tsx scripts/sync-provider-models.ts && pnpm format",
     "generate:models:fetch": "tsx scripts/fetch-openrouter-models.ts",
     "regenerate:models": "tsx scripts/convert-openrouter-models.ts",
diff --git a/packages/ai-client/src/generation-types.ts b/packages/ai-client/src/generation-types.ts
index 05d695cf8..cb170960a 100644
--- a/packages/ai-client/src/generation-types.ts
+++ b/packages/ai-client/src/generation-types.ts
@@ -1,4 +1,4 @@
-import type { StreamChunk } from '@tanstack/ai/client'
+import type { MediaPrompt, StreamChunk } from '@tanstack/ai/client'
 import type { ConnectConnectionAdapter } from './connection-adapters'
 import type { AIDevtoolsClientMetadata } from './devtools'
 import type {
@@ -216,8 +216,12 @@ export interface VideoGenerationClientOptions<
  * Input for image generation.
  */
 export interface ImageGenerateInput {
-  /** Text description of the desired image(s) */
-  prompt: string
+  /**
+   * Description of the desired image(s): plain text, or an ordered array of
+   * content parts (text + image) for image-conditioned generation
+   * (image-to-image, multi-reference, edit / inpaint).
+   */
+  prompt: MediaPrompt
   /** Number of images to generate (default: 1) */
   numberOfImages?: number
   /** Image size in WIDTHxHEIGHT format (e.g., "1024x1024") */
@@ -290,8 +294,12 @@ export interface SummarizeGenerateInput {
  * Input for video generation.
  */
 export interface VideoGenerateInput {
-  /** Text description of the desired video */
-  prompt: string
+  /**
+   * Description of the desired video: plain text, or an ordered array of
+   * content parts (text + image) for image-conditioned generation
+   * (image-to-video, start/end frames).
+   */
+  prompt: MediaPrompt
   /** Video size — format depends on provider (e.g., "16:9", "1280x720") */
   size?: string
   /** Video duration in seconds */
diff --git a/packages/ai-client/tests/video-generation-client.test.ts b/packages/ai-client/tests/video-generation-client.test.ts
index 98ff24c38..47692d110 100644
--- a/packages/ai-client/tests/video-generation-client.test.ts
+++ b/packages/ai-client/tests/video-generation-client.test.ts
@@ -3,6 +3,7 @@ import { EventType } from '@tanstack/ai/client'
 import { VideoGenerationClient } from '../src/video-generation-client'
 import type { StreamChunk } from '@tanstack/ai/client'
 import type { ConnectConnectionAdapter } from '../src/connection-adapters'
+import type { VideoGenerateInput } from '../src/generation-types'
 
 // Helper to create a mock connect-based adapter from StreamChunks
 function createMockConnection(
@@ -83,7 +84,7 @@ describe('VideoGenerationClient', () => {
     it('should pass abort signal to fetcher', async () => {
       const fetcherSpy = vi.fn(
         async (
-          _input: { prompt: string },
+          _input: VideoGenerateInput,
           options?: { signal: AbortSignal },
         ) => {
           expect(options).toBeDefined()
diff --git a/packages/ai-event-client/src/index.ts b/packages/ai-event-client/src/index.ts
index 59d10d62e..b064cd0bd 100644
--- a/packages/ai-event-client/src/index.ts
+++ b/packages/ai-event-client/src/index.ts
@@ -606,6 +606,12 @@ export interface ImageRequestStartedEvent extends BaseEventContext {
   prompt: string
   numberOfImages?: number
   size?: string
+  /** Count of image conditioning inputs (image-to-image, mask, reference). */
+  imageInputCount?: number
+  /** Count of video conditioning inputs (video-to-video). */
+  videoInputCount?: number
+  /** Count of audio conditioning inputs (lipsync, voice reference). */
+  audioInputCount?: number
 }
 
 /** Emitted when an image request completes. */
diff --git a/packages/ai-fal/src/adapters/image.ts b/packages/ai-fal/src/adapters/image.ts
index 11dcbaeb2..c9df7a534 100644
--- a/packages/ai-fal/src/adapters/image.ts
+++ b/packages/ai-fal/src/adapters/image.ts
@@ -1,15 +1,19 @@
 import { fal } from '@fal-ai/client'
+import { resolveMediaPrompt } from '@tanstack/ai'
 import { BaseImageAdapter } from '@tanstack/ai/adapters'
 import { configureFalClient, generateId as utilGenerateId } from '../utils'
 import { mapSizeToFalFormat } from '../image/image-provider-options'
+import { mapImageInputsToFalFields } from '../image/image-inputs'
 import type { OutputType, Result } from '@fal-ai/client'
 import type { FalClientConfig } from '../utils'
 import type {
   GeneratedImage,
   ImageGenerationOptions,
   ImageGenerationResult,
+  ResolvedMediaPrompt,
 } from '@tanstack/ai'
 import type {
+  FalImagePromptModalitiesFor,
   FalImageProviderOptions,
   FalModel,
   FalModelImageSize,
@@ -40,7 +44,8 @@ export class FalImageAdapter<TModel extends FalModel> extends BaseImageAdapter<
   TModel,
   FalImageProviderOptions<TModel>,
   Record<TModel, FalImageProviderOptions<TModel>>,
-  Record<TModel, FalModelImageSize<TModel>>
+  Record<TModel, FalModelImageSize<TModel>>,
+  Record<TModel, FalImagePromptModalitiesFor<TModel>>
 > {
   override readonly kind = 'image' as const
   readonly name = 'fal' as const
@@ -63,8 +68,21 @@ export class FalImageAdapter<TModel extends FalModel> extends BaseImageAdapter<
       model: this.model,
     })
 
+    const resolved = resolveMediaPrompt(options.prompt)
+
+    if (resolved.videos.length > 0) {
+      throw new Error(
+        `fal.generateImages does not support video prompt parts on model ${this.model}.`,
+      )
+    }
+    if (resolved.audios.length > 0) {
+      throw new Error(
+        `fal.generateImages does not support audio prompt parts on model ${this.model}.`,
+      )
+    }
+
     try {
-      const input = this.buildInput(options)
+      const input = this.buildInput(options, resolved)
       const result = await fal.subscribe(this.model, { input })
       return this.transformResponse(result)
     } catch (error) {
@@ -81,12 +99,20 @@ export class FalImageAdapter<TModel extends FalModel> extends BaseImageAdapter<
       FalImageProviderOptions<TModel>,
       FalModelImageSize<TModel>
     >,
+    resolved: ResolvedMediaPrompt,
   ): FalModelInput<TModel> {
     const sizeParams = mapSizeToFalFormat(options.size)
+    // Order matters: modelOptions first (so user overrides win for
+    // mask_url / control_image_url / reference_image_urls), then size,
+    // then derived image-input fields, then prompt / num_images.
+    const inputFields = mapImageInputsToFalFields(this.model, resolved.images)
     const input = {
       ...options.modelOptions,
       ...sizeParams,
-      prompt: options.prompt,
+      ...inputFields,
+      // Media-only prompts (e.g. upscalers, background removal) omit the
+      // prompt field entirely rather than sending an empty string.
+      ...(resolved.text ? { prompt: resolved.text } : {}),
       num_images: options.numberOfImages,
     } as FalModelInput<TModel>
     return input
diff --git a/packages/ai-fal/src/adapters/video.ts b/packages/ai-fal/src/adapters/video.ts
index 662b4f60f..ef074b4b4 100644
--- a/packages/ai-fal/src/adapters/video.ts
+++ b/packages/ai-fal/src/adapters/video.ts
@@ -1,10 +1,15 @@
 import { fal } from '@fal-ai/client'
+import { resolveMediaPrompt } from '@tanstack/ai'
 import { BaseVideoAdapter } from '@tanstack/ai/adapters'
 import { configureFalClient, generateId as utilGenerateId } from '../utils'
 import { mapVideoSizeToFalFormat } from '../video/video-provider-options'
+import { mapImageInputsToFalVideoFields } from '../image/image-inputs'
 import type {
+  AudioPart,
+  MediaInputMetadata,
   VideoGenerationOptions,
   VideoJobResult,
+  VideoPart,
   VideoStatusResult,
   VideoUrlResult,
 } from '@tanstack/ai'
@@ -12,10 +17,68 @@ import type {
   FalModel,
   FalModelInput,
   FalModelVideoSize,
+  FalVideoPromptModalitiesFor,
   FalVideoProviderOptions,
 } from '../model-meta'
 import type { FalClientConfig } from '../utils'
 
+/**
+ * Map video conditioning inputs onto fal field names.
+ * Video-to-video endpoints on fal almost universally use `video_url`; the
+ * occasional model takes `video_urls` (rare). Mirror the image-input logic
+ * positionally with a `reference` role escape hatch via `reference_video_urls`.
+ */
+function mapVideoInputsToFalFields(
+  videoInputs?: ReadonlyArray<VideoPart<MediaInputMetadata>>,
+): Record<string, unknown> {
+  if (!videoInputs || videoInputs.length === 0) return {}
+  const references: Array<string> = []
+  const sources: Array<string> = []
+  for (const part of videoInputs) {
+    const url = videoPartToUrl(part)
+    if (
+      part.metadata?.role === 'reference' ||
+      part.metadata?.role === 'character'
+    ) {
+      references.push(url)
+    } else {
+      sources.push(url)
+    }
+  }
+  const out: Record<string, unknown> = {}
+  if (references.length > 0) out.reference_video_urls = references
+  if (sources.length === 1) {
+    out.video_url = sources[0]
+  } else if (sources.length > 1) {
+    out.video_urls = sources
+  }
+  return out
+}
+
+function mapAudioInputsToFalFields(
+  audioInputs?: ReadonlyArray<AudioPart<MediaInputMetadata>>,
+): Record<string, unknown> {
+  if (!audioInputs || audioInputs.length === 0) return {}
+  const [part, ...rest] = audioInputs
+  if (!part || rest.length > 0) {
+    throw new Error(
+      `fal: exactly one audio prompt part is supported (received ${audioInputs.length}).`,
+    )
+  }
+  return {
+    audio_url:
+      part.source.type === 'url'
+        ? part.source.value
+        : `data:${part.source.mimeType};base64,${part.source.value}`,
+  }
+}
+
+function videoPartToUrl(part: VideoPart<MediaInputMetadata>): string {
+  return part.source.type === 'url'
+    ? part.source.value
+    : `data:${part.source.mimeType};base64,${part.source.value}`
+}
+
 type FalQueueStatus = 'IN_QUEUE' | 'IN_PROGRESS' | 'COMPLETED'
 
 interface FalStatusResponse {
@@ -64,7 +127,8 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
   TModel,
   FalVideoProviderOptions<TModel>,
   Record<TModel, FalVideoProviderOptions<TModel>>,
-  Record<TModel, FalModelVideoSize<TModel>>
+  Record<TModel, FalModelVideoSize<TModel>>,
+  Record<TModel, FalVideoPromptModalitiesFor<TModel>>
 > {
   override readonly kind = 'video' as const
   readonly name = 'fal' as const
@@ -80,7 +144,7 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
       FalModelVideoSize<TModel>
     >,
   ): Promise<VideoJobResult> {
-    const { prompt, size, duration, modelOptions, logger } = options
+    const { size, duration, modelOptions, logger } = options
 
     logger.request(`activity=generateVideo provider=fal model=${this.model}`, {
       provider: 'fal',
@@ -88,12 +152,24 @@ export class FalVideoAdapter<TModel extends FalModel> extends BaseVideoAdapter<
     })
 
     try {
+      const resolved = resolveMediaPrompt(options.prompt)
       const sizeParams = mapVideoSizeToFalFormat(size)
+      const inputImageFields = mapImageInputsToFalVideoFields(
+        this.model,
+        resolved.images,
+      )
+      const videoFields = mapVideoInputsToFalFields(resolved.videos)
+      const audioFields = mapAudioInputsToFalFields(resolved.audios)
 
       const input = {
         ...modelOptions,
         ...sizeParams,
-        prompt,
+        ...inputImageFields,
+        ...videoFields,
+        ...audioFields,
+        // Media-only prompts omit the prompt field rather than sending an
+        // empty string (e.g. pure image-to-video endpoints).
+        ...(resolved.text ? { prompt: resolved.text } : {}),
         ...(duration ? { duration } : {}),
       } as FalModelInput<TModel>
 
diff --git a/packages/ai-fal/src/image/generated/image-field-overrides.ts b/packages/ai-fal/src/image/generated/image-field-overrides.ts
new file mode 100644
index 000000000..55e1f67eb
--- /dev/null
+++ b/packages/ai-fal/src/image/generated/image-field-overrides.ts
@@ -0,0 +1,430 @@
+/* eslint-disable */
+// ---------------------------------------------------------------------------
+// AUTO-GENERATED — do not edit by hand.
+//
+// Generated from @fal-ai/client@1.10.1 EndpointTypeMap by
+// scripts/generate-fal-image-field-map.ts. Regenerate after bumping
+// @fal-ai/client:
+//
+//   pnpm tsx scripts/generate-fal-image-field-map.ts
+//
+// Maps fal endpoint ids to the image-conditioning input fields they accept
+// whenever those differ from the defaults in image-inputs.ts. Endpoints
+// matching the defaults are omitted. The `satisfies` clause below checks
+// every field name against the SDK's endpoint input types at compile time
+// (type-only import — nothing from endpoints.d.ts is shipped at runtime).
+// ---------------------------------------------------------------------------
+import type { EndpointTypeMap } from '@fal-ai/client/endpoints'
+
+/** sha256 of the endpoints.d.ts this file was generated from. */
+export const FAL_ENDPOINTS_DTS_SHA256 =
+  'a071f97905b8a1068f924c74108b881362f20c9054620b70359c200404e23b4e'
+
+/** Every input field name the image-input mappers may emit. */
+export type FalImageFieldName =
+  | 'control_image_url'
+  | 'end_image_url'
+  | 'first_frame_url'
+  | 'first_image_url'
+  | 'image_data_url'
+  | 'image_url'
+  | 'image_urls'
+  | 'input_image_url'
+  | 'input_image_urls'
+  | 'last_frame_url'
+  | 'mask_image_url'
+  | 'mask_url'
+  | 'ref_image_urls'
+  | 'reference_image_url'
+  | 'reference_image_urls'
+  | 'start_image_url'
+  | 'tail_image_url'
+
+/**
+ * Per-role input-field overrides. Roles: `single` / `multi` route unroled
+ * source images; the rest mirror `MediaInputRole` (`start` / `end` map the
+ * `start_frame` / `end_frame` roles).
+ */
+export interface FalImageFieldOverride {
+  single?: string
+  multi?: string
+  mask?: string
+  control?: string
+  reference?: string
+  start?: string
+  end?: string
+}
+
+type InputFieldOf<K extends keyof EndpointTypeMap> = Extract<
+  keyof EndpointTypeMap[K]['input'],
+  string
+>
+
+export const FAL_IMAGE_FIELD_OVERRIDES = {
+  'bytedance/lynx': { start: 'image_url' },
+  'decart/lucy-i2v': { start: 'image_url' },
+  'fal-ai/ai-avatar/multi': { start: 'image_url' },
+  'fal-ai/ai-avatar/multi-text': { start: 'image_url' },
+  'fal-ai/ai-avatar/single-text': { start: 'image_url' },
+  'fal-ai/bytedance/dreamactor/v2': { start: 'image_url' },
+  'fal-ai/bytedance/omnihuman': { start: 'image_url' },
+  'fal-ai/bytedance/omnihuman/v1.5': { start: 'image_url' },
+  'fal-ai/bytedance/seed/v2/mini': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/bytedance/seedance/v1.5/pro/image-to-video': { start: 'image_url' },
+  'fal-ai/bytedance/seedance/v1/lite/image-to-video': { start: 'image_url' },
+  'fal-ai/bytedance/seedance/v1/lite/reference-to-video': { multi: 'reference_image_urls' },
+  'fal-ai/bytedance/seedance/v1/pro/fast/image-to-video': { start: 'image_url' },
+  'fal-ai/bytedance/seedance/v1/pro/image-to-video': { start: 'image_url' },
+  'fal-ai/bytedance/seedream/v4.5/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/bytedance/seedream/v4/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/bytedance/seedream/v5/lite/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/cogvideox-5b/image-to-video': { start: 'image_url' },
+  'fal-ai/controlnext': { start: 'image_url' },
+  'fal-ai/cosmos-predict-2.5/image-to-video': { start: 'image_url' },
+  'fal-ai/creatify/aurora': { start: 'image_url' },
+  'fal-ai/davinci-magihuman': { start: 'image_url' },
+  'fal-ai/dreamomni2/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/echomimic-v3': { start: 'image_url' },
+  'fal-ai/fast-svd-lcm': { start: 'image_url' },
+  'fal-ai/firered-image-edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/firered-image-edit-v1.1': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2-flex/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2-klein-4b-base-trainer': { single: 'image_data_url' },
+  'fal-ai/flux-2-klein-4b-base-trainer/edit': { single: 'image_data_url' },
+  'fal-ai/flux-2-klein-9b-base-trainer': { single: 'image_data_url' },
+  'fal-ai/flux-2-klein-9b-base-trainer/edit': { single: 'image_data_url' },
+  'fal-ai/flux-2-lora-gallery/add-background': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2-lora-gallery/apartment-staging': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2-lora-gallery/face-to-full-portrait': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2-lora-gallery/multiple-angles': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2-lora-gallery/virtual-tryon': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2-max/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2-pro/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2-trainer': { single: 'image_data_url' },
+  'fal-ai/flux-2-trainer-v2': { single: 'image_data_url' },
+  'fal-ai/flux-2-trainer-v2/edit': { single: 'image_data_url' },
+  'fal-ai/flux-2-trainer/edit': { single: 'image_data_url' },
+  'fal-ai/flux-2/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2/flash/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2/klein/4b/base/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2/klein/4b/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2/klein/4b/edit/lora': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2/klein/9b/base/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2/klein/9b/base/edit/lora': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2/klein/9b/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2/klein/9b/edit/lora': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2/lora/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-2/turbo/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-general': { reference: 'reference_image_url' },
+  'fal-ai/flux-general/differential-diffusion': { reference: 'reference_image_url' },
+  'fal-ai/flux-general/image-to-image': { reference: 'reference_image_url' },
+  'fal-ai/flux-general/inpainting': { reference: 'reference_image_url' },
+  'fal-ai/flux-general/rf-inversion': { reference: 'reference_image_url' },
+  'fal-ai/flux-kontext-trainer': { single: 'image_data_url' },
+  'fal-ai/flux-pro/kontext/max/multi': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-pro/kontext/multi': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/flux-pulid': { reference: 'reference_image_url' },
+  'fal-ai/fooocus': { mask: 'mask_image_url' },
+  'fal-ai/fooocus/image-prompt': { mask: 'mask_image_url' },
+  'fal-ai/fooocus/inpaint': { mask: 'mask_image_url' },
+  'fal-ai/framepack': { start: 'image_url' },
+  'fal-ai/framepack/f1': { start: 'image_url' },
+  'fal-ai/framepack/flf2v': { start: 'image_url' },
+  'fal-ai/gemini-25-flash-image/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/gemini-3-pro-image-preview/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/gemini-3.1-flash-image-preview/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/gemini-flash-edit/multi': { single: 'input_image_urls', multi: 'input_image_urls', reference: 'input_image_urls' },
+  'fal-ai/glm-image/image-to-image': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/goal-force': { start: 'image_url' },
+  'fal-ai/got-ocr/v2': { single: 'input_image_urls', multi: 'input_image_urls', reference: 'input_image_urls' },
+  'fal-ai/gpt-image-1-mini/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/gpt-image-1.5/edit': { single: 'image_urls', mask: 'mask_image_url', reference: 'image_urls' },
+  'fal-ai/gpt-image-1/edit-image': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/heygen/avatar4/image-to-video': { start: 'image_url' },
+  'fal-ai/hunyuan-3d/v3.1/pro/image-to-3d': { single: 'input_image_url' },
+  'fal-ai/hunyuan-3d/v3.1/rapid/image-to-3d': { single: 'input_image_url' },
+  'fal-ai/hunyuan-avatar': { start: 'image_url' },
+  'fal-ai/hunyuan-custom': { start: 'image_url' },
+  'fal-ai/hunyuan-image/v3/instruct/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/hunyuan-portrait': { start: 'image_url' },
+  'fal-ai/hunyuan-video-image-to-video': { start: 'image_url' },
+  'fal-ai/hunyuan-video-img2vid-lora': { start: 'image_url' },
+  'fal-ai/hunyuan-video-v1.5/image-to-video': { start: 'image_url' },
+  'fal-ai/hunyuan3d-v21': { single: 'input_image_url' },
+  'fal-ai/hunyuan3d-v3/image-to-3d': { single: 'input_image_url' },
+  'fal-ai/hunyuan3d-v3/sketch-to-3d': { single: 'input_image_url' },
+  'fal-ai/hunyuan3d/v2': { single: 'input_image_url' },
+  'fal-ai/hunyuan3d/v2/mini': { single: 'input_image_url' },
+  'fal-ai/hunyuan3d/v2/mini/turbo': { single: 'input_image_url' },
+  'fal-ai/hunyuan3d/v2/turbo': { single: 'input_image_url' },
+  'fal-ai/hy-wu-edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/hyper3d/rodin': { single: 'input_image_urls', multi: 'input_image_urls', reference: 'input_image_urls' },
+  'fal-ai/hyper3d/rodin/v2': { single: 'input_image_urls', multi: 'input_image_urls', reference: 'input_image_urls' },
+  'fal-ai/iclight-v2': { mask: 'mask_image_url' },
+  'fal-ai/ideogram/character': { single: 'image_urls' },
+  'fal-ai/ideogram/v3': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/ideogram/v3/edit': { reference: 'image_urls' },
+  'fal-ai/ideogram/v3/reframe': { reference: 'image_urls' },
+  'fal-ai/ideogram/v3/remix': { reference: 'image_urls' },
+  'fal-ai/ideogram/v3/replace-background': { reference: 'image_urls' },
+  'fal-ai/infinitalk': { start: 'image_url' },
+  'fal-ai/infinitalk/single-text': { start: 'image_url' },
+  'fal-ai/kandinsky5-pro/image-to-video': { start: 'image_url' },
+  'fal-ai/kling-image/o1': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/kling-image/o3/image-to-image': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/kling-video/ai-avatar/v2/pro': { start: 'image_url' },
+  'fal-ai/kling-video/ai-avatar/v2/standard': { start: 'image_url' },
+  'fal-ai/kling-video/o1/reference-to-video': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/kling-video/o1/standard/reference-to-video': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/kling-video/o1/standard/video-to-video/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/kling-video/o1/standard/video-to-video/reference': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/kling-video/o1/video-to-video/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/kling-video/o1/video-to-video/reference': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/kling-video/o3/pro/image-to-video': { start: 'image_url' },
+  'fal-ai/kling-video/o3/pro/reference-to-video': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/kling-video/o3/pro/video-to-video/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/kling-video/o3/pro/video-to-video/reference': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/kling-video/o3/standard/image-to-video': { start: 'image_url' },
+  'fal-ai/kling-video/o3/standard/reference-to-video': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/kling-video/o3/standard/video-to-video/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/kling-video/o3/standard/video-to-video/reference': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/kling-video/v1.5/pro/effects': { single: 'input_image_urls', multi: 'input_image_urls', reference: 'input_image_urls' },
+  'fal-ai/kling-video/v1.5/pro/image-to-video': { start: 'image_url', end: 'tail_image_url' },
+  'fal-ai/kling-video/v1.6/pro/effects': { single: 'input_image_urls', multi: 'input_image_urls', reference: 'input_image_urls' },
+  'fal-ai/kling-video/v1.6/pro/elements': { single: 'input_image_urls', multi: 'input_image_urls', reference: 'input_image_urls' },
+  'fal-ai/kling-video/v1.6/pro/image-to-video': { start: 'image_url', end: 'tail_image_url' },
+  'fal-ai/kling-video/v1.6/standard/effects': { single: 'input_image_urls', multi: 'input_image_urls', reference: 'input_image_urls' },
+  'fal-ai/kling-video/v1.6/standard/elements': { single: 'input_image_urls', multi: 'input_image_urls', reference: 'input_image_urls' },
+  'fal-ai/kling-video/v1.6/standard/image-to-video': { start: 'image_url' },
+  'fal-ai/kling-video/v1/pro/ai-avatar': { start: 'image_url' },
+  'fal-ai/kling-video/v1/standard/ai-avatar': { start: 'image_url' },
+  'fal-ai/kling-video/v1/standard/effects': { single: 'input_image_urls', multi: 'input_image_urls', reference: 'input_image_urls' },
+  'fal-ai/kling-video/v1/standard/image-to-video': { start: 'image_url', end: 'tail_image_url' },
+  'fal-ai/kling-video/v2.1/master/image-to-video': { start: 'image_url' },
+  'fal-ai/kling-video/v2.1/standard/image-to-video': { start: 'image_url' },
+  'fal-ai/kling-video/v2.5-turbo/pro/image-to-video': { start: 'image_url', end: 'tail_image_url' },
+  'fal-ai/kling-video/v2.5-turbo/standard/image-to-video': { start: 'image_url' },
+  'fal-ai/kling-video/v2.6/pro/motion-control': { start: 'image_url' },
+  'fal-ai/kling-video/v2.6/standard/motion-control': { start: 'image_url' },
+  'fal-ai/kling-video/v2/master/image-to-video': { start: 'image_url' },
+  'fal-ai/kling-video/v3/pro/motion-control': { start: 'image_url' },
+  'fal-ai/kling-video/v3/standard/motion-control': { start: 'image_url' },
+  'fal-ai/live-avatar': { start: 'image_url' },
+  'fal-ai/live-portrait': { start: 'image_url' },
+  'fal-ai/longcat-multi-avatar/image-audio-to-video': { start: 'image_url' },
+  'fal-ai/longcat-single-avatar/image-audio-to-video': { start: 'image_url' },
+  'fal-ai/longcat-video/distilled/image-to-video/480p': { start: 'image_url' },
+  'fal-ai/longcat-video/distilled/image-to-video/720p': { start: 'image_url' },
+  'fal-ai/longcat-video/image-to-video/480p': { start: 'image_url' },
+  'fal-ai/longcat-video/image-to-video/720p': { start: 'image_url' },
+  'fal-ai/ltx-2-19b/audio-to-video': { start: 'image_url' },
+  'fal-ai/ltx-2-19b/audio-to-video/lora': { start: 'image_url' },
+  'fal-ai/ltx-2-19b/distilled/audio-to-video': { start: 'image_url' },
+  'fal-ai/ltx-2-19b/distilled/audio-to-video/lora': { start: 'image_url' },
+  'fal-ai/ltx-2-19b/distilled/image-to-video': { start: 'image_url' },
+  'fal-ai/ltx-2-19b/distilled/video-to-video': { start: 'image_url' },
+  'fal-ai/ltx-2-19b/distilled/video-to-video/lora': { start: 'image_url' },
+  'fal-ai/ltx-2-19b/image-to-video': { start: 'image_url' },
+  'fal-ai/ltx-2-19b/image-to-video/lora': { start: 'image_url' },
+  'fal-ai/ltx-2-19b/video-to-video': { start: 'image_url' },
+  'fal-ai/ltx-2-19b/video-to-video/lora': { start: 'image_url' },
+  'fal-ai/ltx-2.3/audio-to-video': { start: 'image_url' },
+  'fal-ai/ltx-2.3/image-to-video': { start: 'image_url' },
+  'fal-ai/ltx-2.3/image-to-video/fast': { start: 'image_url' },
+  'fal-ai/ltx-2/audio-to-video': { start: 'image_url' },
+  'fal-ai/ltx-2/image-to-video': { start: 'image_url' },
+  'fal-ai/ltx-2/image-to-video/fast': { start: 'image_url' },
+  'fal-ai/ltx-video-13b-dev/image-to-video': { start: 'image_url' },
+  'fal-ai/ltx-video-13b-distilled/image-to-video': { start: 'image_url' },
+  'fal-ai/ltx-video-lora/image-to-video': { start: 'image_url' },
+  'fal-ai/ltx-video-v095/image-to-video': { start: 'image_url' },
+  'fal-ai/ltx-video-v097/image-to-video': { start: 'image_url' },
+  'fal-ai/ltx-video/image-to-video': { start: 'image_url' },
+  'fal-ai/ltxv-13b-098-distilled/image-to-video': { start: 'image_url' },
+  'fal-ai/luma-dream-machine/ray-2-flash/image-to-video': { start: 'image_url' },
+  'fal-ai/luma-dream-machine/ray-2-flash/modify': { start: 'image_url' },
+  'fal-ai/luma-dream-machine/ray-2-flash/reframe': { start: 'image_url' },
+  'fal-ai/luma-dream-machine/ray-2/image-to-video': { start: 'image_url' },
+  'fal-ai/luma-dream-machine/ray-2/reframe': { start: 'image_url' },
+  'fal-ai/magi-distilled/image-to-video': { start: 'image_url' },
+  'fal-ai/magi/image-to-video': { start: 'image_url' },
+  'fal-ai/meshy/v5/multi-image-to-3d': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/minimax/hailuo-02-fast/image-to-video': { start: 'image_url' },
+  'fal-ai/minimax/hailuo-02/pro/image-to-video': { start: 'image_url' },
+  'fal-ai/minimax/hailuo-02/standard/image-to-video': { start: 'image_url' },
+  'fal-ai/minimax/hailuo-2.3-fast/pro/image-to-video': { start: 'image_url' },
+  'fal-ai/minimax/hailuo-2.3-fast/standard/image-to-video': { start: 'image_url' },
+  'fal-ai/minimax/hailuo-2.3/pro/image-to-video': { start: 'image_url' },
+  'fal-ai/minimax/hailuo-2.3/standard/image-to-video': { start: 'image_url' },
+  'fal-ai/minimax/video-01-director/image-to-video': { start: 'image_url' },
+  'fal-ai/minimax/video-01-live/image-to-video': { start: 'image_url' },
+  'fal-ai/minimax/video-01/image-to-video': { start: 'image_url' },
+  'fal-ai/muse-pose': { start: 'image_url' },
+  'fal-ai/nano-banana-2/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/nano-banana-pro/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/nano-banana/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/omnigen-v1': { single: 'input_image_urls', multi: 'input_image_urls', reference: 'input_image_urls' },
+  'fal-ai/omnigen-v2': { single: 'input_image_urls', multi: 'input_image_urls', reference: 'input_image_urls' },
+  'fal-ai/omnipart': { single: 'input_image_url' },
+  'fal-ai/phota/create-profile': { single: 'image_data_url' },
+  'fal-ai/phota/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/pika/v1.5/pikaffects': { start: 'image_url' },
+  'fal-ai/pika/v2.1/image-to-video': { start: 'image_url' },
+  'fal-ai/pika/v2.2/image-to-video': { start: 'image_url' },
+  'fal-ai/pika/v2.2/pikaframes': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/pika/v2/pikadditions': { start: 'image_url' },
+  'fal-ai/pika/v2/turbo/image-to-video': { start: 'image_url' },
+  'fal-ai/pixverse/swap': { start: 'image_url' },
+  'fal-ai/pixverse/v3.5/image-to-video': { start: 'image_url' },
+  'fal-ai/pixverse/v4.5/effects': { start: 'image_url' },
+  'fal-ai/pixverse/v4.5/image-to-video': { start: 'image_url' },
+  'fal-ai/pixverse/v4.5/image-to-video/fast': { start: 'image_url' },
+  'fal-ai/pixverse/v4.5/transition': { start: 'first_image_url' },
+  'fal-ai/pixverse/v4/effects': { start: 'image_url' },
+  'fal-ai/pixverse/v4/image-to-video': { start: 'image_url' },
+  'fal-ai/pixverse/v4/image-to-video/fast': { start: 'image_url' },
+  'fal-ai/pixverse/v5.5/effects': { start: 'image_url' },
+  'fal-ai/pixverse/v5.5/image-to-video': { start: 'image_url' },
+  'fal-ai/pixverse/v5.5/transition': { start: 'first_image_url' },
+  'fal-ai/pixverse/v5.6/image-to-video': { start: 'image_url' },
+  'fal-ai/pixverse/v5.6/transition': { start: 'first_image_url' },
+  'fal-ai/pixverse/v5/effects': { start: 'image_url' },
+  'fal-ai/pixverse/v5/image-to-video': { start: 'image_url' },
+  'fal-ai/pixverse/v5/transition': { start: 'first_image_url' },
+  'fal-ai/pixverse/v6/image-to-video': { start: 'image_url' },
+  'fal-ai/pixverse/v6/transition': { start: 'first_image_url' },
+  'fal-ai/qwen-image-2/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-2/pro/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-2512-trainer': { single: 'image_data_url' },
+  'fal-ai/qwen-image-2512-trainer-v2': { single: 'image_data_url' },
+  'fal-ai/qwen-image-edit-2509': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-2509-lora': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-2509-lora-gallery/add-background': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-2509-lora-gallery/face-to-full-portrait': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-2509-lora-gallery/group-photo': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-2509-lora-gallery/integrate-product': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-2509-lora-gallery/lighting-restoration': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-2509-lora-gallery/multiple-angles': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-2509-lora-gallery/next-scene': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-2509-lora-gallery/remove-element': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-2509-lora-gallery/remove-lighting': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-2509-lora-gallery/shirt-design': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-2509-trainer': { single: 'image_data_url' },
+  'fal-ai/qwen-image-edit-2511': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-2511-multiple-angles': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-2511-trainer': { single: 'image_data_url' },
+  'fal-ai/qwen-image-edit-2511/lora': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-plus': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-plus-lora': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-plus-lora-gallery/add-background': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-plus-lora-gallery/face-to-full-portrait': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-plus-lora-gallery/group-photo': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-plus-lora-gallery/integrate-product': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-plus-lora-gallery/lighting-restoration': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-plus-lora-gallery/multiple-angles': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-plus-lora-gallery/next-scene': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-plus-lora-gallery/remove-element': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-plus-lora-gallery/remove-lighting': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-plus-lora-gallery/shirt-design': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-edit-plus-trainer': { single: 'image_data_url' },
+  'fal-ai/qwen-image-edit-trainer': { single: 'image_data_url' },
+  'fal-ai/qwen-image-layered-trainer': { single: 'image_data_url' },
+  'fal-ai/qwen-image-max/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/qwen-image-trainer': { single: 'image_data_url' },
+  'fal-ai/qwen-image-trainer-v2': { single: 'image_data_url' },
+  'fal-ai/scail': { start: 'image_url' },
+  'fal-ai/skyreels-i2v': { start: 'image_url' },
+  'fal-ai/sora-2/image-to-video': { start: 'image_url' },
+  'fal-ai/sora-2/image-to-video/pro': { start: 'image_url' },
+  'fal-ai/stable-avatar': { start: 'image_url' },
+  'fal-ai/stable-video': { start: 'image_url' },
+  'fal-ai/steady-dancer': { start: 'image_url' },
+  'fal-ai/trellis/multi': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/uno': { single: 'input_image_urls', multi: 'input_image_urls', reference: 'input_image_urls' },
+  'fal-ai/uso': { single: 'input_image_urls', multi: 'input_image_urls', reference: 'input_image_urls' },
+  'fal-ai/vecglypher/image-to-svg': { multi: 'reference_image_urls' },
+  'fal-ai/veo2/image-to-video': { start: 'image_url' },
+  'fal-ai/veo3.1/fast/first-last-frame-to-video': { start: 'first_frame_url', end: 'last_frame_url' },
+  'fal-ai/veo3.1/fast/image-to-video': { start: 'image_url' },
+  'fal-ai/veo3.1/first-last-frame-to-video': { start: 'first_frame_url', end: 'last_frame_url' },
+  'fal-ai/veo3.1/image-to-video': { start: 'image_url' },
+  'fal-ai/veo3.1/lite/first-last-frame-to-video': { start: 'first_frame_url', end: 'last_frame_url' },
+  'fal-ai/veo3.1/lite/image-to-video': { start: 'image_url' },
+  'fal-ai/veo3.1/reference-to-video': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/veo3/fast/image-to-video': { start: 'image_url' },
+  'fal-ai/veo3/image-to-video': { start: 'image_url' },
+  'fal-ai/video-as-prompt': { start: 'image_url' },
+  'fal-ai/vidu/image-to-video': { start: 'image_url' },
+  'fal-ai/vidu/q1/image-to-video': { start: 'image_url' },
+  'fal-ai/vidu/q1/reference-to-video': { multi: 'reference_image_urls' },
+  'fal-ai/vidu/q2/image-to-video/pro': { start: 'image_url' },
+  'fal-ai/vidu/q2/image-to-video/turbo': { start: 'image_url' },
+  'fal-ai/vidu/q2/reference-to-image': { multi: 'reference_image_urls' },
+  'fal-ai/vidu/q2/reference-to-video/pro': { multi: 'reference_image_urls' },
+  'fal-ai/vidu/q3/image-to-video': { start: 'image_url' },
+  'fal-ai/vidu/q3/image-to-video/turbo': { start: 'image_url' },
+  'fal-ai/vidu/reference-to-image': { multi: 'reference_image_urls' },
+  'fal-ai/vidu/reference-to-video': { multi: 'reference_image_urls' },
+  'fal-ai/vidu/template-to-video': { single: 'input_image_urls', multi: 'input_image_urls', reference: 'input_image_urls' },
+  'fal-ai/wan-22-vace-fun-a14b/depth': { multi: 'ref_image_urls', reference: 'ref_image_urls', start: 'first_frame_url', end: 'last_frame_url' },
+  'fal-ai/wan-22-vace-fun-a14b/inpainting': { multi: 'ref_image_urls', mask: 'mask_image_url', reference: 'ref_image_urls', start: 'first_frame_url', end: 'last_frame_url' },
+  'fal-ai/wan-22-vace-fun-a14b/outpainting': { multi: 'ref_image_urls', reference: 'ref_image_urls', start: 'first_frame_url', end: 'last_frame_url' },
+  'fal-ai/wan-22-vace-fun-a14b/pose': { multi: 'ref_image_urls', reference: 'ref_image_urls', start: 'first_frame_url', end: 'last_frame_url' },
+  'fal-ai/wan-22-vace-fun-a14b/reframe': { start: 'first_frame_url', end: 'last_frame_url' },
+  'fal-ai/wan-25-preview/image-to-image': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/wan-25-preview/image-to-video': { start: 'image_url' },
+  'fal-ai/wan-ati': { start: 'image_url' },
+  'fal-ai/wan-effects': { start: 'image_url' },
+  'fal-ai/wan-fun-control': { reference: 'reference_image_url' },
+  'fal-ai/wan-i2v': { start: 'image_url' },
+  'fal-ai/wan-i2v-lora': { start: 'image_url' },
+  'fal-ai/wan-motion': { start: 'image_url' },
+  'fal-ai/wan-move': { start: 'image_url' },
+  'fal-ai/wan-pro/image-to-video': { start: 'image_url' },
+  'fal-ai/wan-vace': { multi: 'ref_image_urls', mask: 'mask_image_url', reference: 'ref_image_urls' },
+  'fal-ai/wan-vace-1-3b': { multi: 'ref_image_urls', mask: 'mask_image_url', reference: 'ref_image_urls' },
+  'fal-ai/wan-vace-14b': { multi: 'ref_image_urls', mask: 'mask_image_url', reference: 'ref_image_urls', start: 'first_frame_url', end: 'last_frame_url' },
+  'fal-ai/wan-vace-14b/depth': { multi: 'ref_image_urls', reference: 'ref_image_urls', start: 'first_frame_url', end: 'last_frame_url' },
+  'fal-ai/wan-vace-14b/inpainting': { multi: 'ref_image_urls', mask: 'mask_image_url', reference: 'ref_image_urls', start: 'first_frame_url', end: 'last_frame_url' },
+  'fal-ai/wan-vace-14b/outpainting': { multi: 'ref_image_urls', reference: 'ref_image_urls', start: 'first_frame_url', end: 'last_frame_url' },
+  'fal-ai/wan-vace-14b/pose': { multi: 'ref_image_urls', reference: 'ref_image_urls', start: 'first_frame_url', end: 'last_frame_url' },
+  'fal-ai/wan-vace-14b/reframe': { start: 'first_frame_url', end: 'last_frame_url' },
+  'fal-ai/wan-vace-apps/video-edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/wan/v2.2-14b/animate/move': { start: 'image_url' },
+  'fal-ai/wan/v2.2-14b/animate/replace': { start: 'image_url' },
+  'fal-ai/wan/v2.2-14b/speech-to-video': { start: 'image_url' },
+  'fal-ai/wan/v2.2-5b/image-to-video': { start: 'image_url' },
+  'fal-ai/wan/v2.2-a14b/image-to-video/lora': { start: 'image_url' },
+  'fal-ai/wan/v2.2-a14b/image-to-video/turbo': { start: 'image_url' },
+  'fal-ai/wan/v2.7/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/wan/v2.7/edit-video': { reference: 'reference_image_url' },
+  'fal-ai/wan/v2.7/image-to-video': { start: 'image_url' },
+  'fal-ai/wan/v2.7/pro/edit': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/wan/v2.7/reference-to-video': { multi: 'reference_image_urls' },
+  'fal-ai/x-ailab/nsfw': { single: 'image_urls', reference: 'image_urls' },
+  'fal-ai/z-image-base-trainer': { single: 'image_data_url' },
+  'fal-ai/z-image-trainer': { single: 'image_data_url' },
+  'fal-ai/z-image-turbo-trainer-v2': { single: 'image_data_url' },
+  'fal-ai/z-image/turbo/inpaint': { mask: 'mask_image_url' },
+  'fal-ai/z-image/turbo/inpaint/lora': { mask: 'mask_image_url' },
+  'fal-ai/z-image/turbo/tiling': { mask: 'mask_image_url' },
+  'fal-ai/z-image/turbo/tiling/lora': { mask: 'mask_image_url' },
+  'moonvalley/marey/i2v': { start: 'image_url' },
+  'moonvalley/marey/motion-transfer': { reference: 'reference_image_url' },
+  'moonvalley/marey/pose-transfer': { reference: 'reference_image_url' },
+  'openrouter/router/vision': { single: 'image_urls', reference: 'image_urls' },
+  'veed/fabric-1.0': { start: 'image_url' },
+  'veed/fabric-1.0/fast': { start: 'image_url' },
+  'veed/fabric-1.0/text': { start: 'image_url' },
+  'wan/v2.6/image-to-image': { single: 'image_urls', reference: 'image_urls' },
+  'wan/v2.6/image-to-video': { start: 'image_url' },
+  'wan/v2.6/image-to-video/flash': { start: 'image_url' },
+  'wan/v2.6/reference-to-video/flash': { single: 'image_urls', reference: 'image_urls' },
+  'xai/grok-imagine-image/edit': { single: 'image_urls', reference: 'image_urls' },
+  'xai/grok-imagine-video/image-to-video': { start: 'image_url' },
+  'xai/grok-imagine-video/reference-to-video': { multi: 'reference_image_urls' },
+} as const satisfies {
+  [K in keyof EndpointTypeMap]?: {
+    [Role in keyof FalImageFieldOverride]?: InputFieldOf<K>
+  }
+}
diff --git a/packages/ai-fal/src/image/image-inputs.ts b/packages/ai-fal/src/image/image-inputs.ts
new file mode 100644
index 000000000..6196627c6
--- /dev/null
+++ b/packages/ai-fal/src/image/image-inputs.ts
@@ -0,0 +1,246 @@
+import { FAL_IMAGE_FIELD_OVERRIDES } from './generated/image-field-overrides'
+import type {
+  FalImageFieldName,
+  FalImageFieldOverride,
+} from './generated/image-field-overrides'
+import type { ImagePart, MediaInputMetadata } from '@tanstack/ai'
+import type { FalModel, FalModelInput } from '../model-meta'
+
+/**
+ * The image-conditioning fields the mappers may set, narrowed to the ones
+ * that actually exist on the given endpoint's input type. For endpoints
+ * unknown to the installed `@fal-ai/client` this widens to all known field
+ * names.
+ */
+export type FalImageInputFields<TModel extends string> = Partial<
+  Pick<
+    FalModelInput<TModel>,
+    Extract<keyof FalModelInput<TModel>, FalImageFieldName>
+  >
+>
+
+/**
+ * Default field per routing role. Endpoint-specific deviations live in the
+ * generated `FAL_IMAGE_FIELD_OVERRIDES` map (regenerate with
+ * `pnpm generate:fal-image-fields`); these defaults must stay in sync with
+ * `DEFAULTS` in scripts/generate-fal-image-field-map.ts.
+ */
+const DEFAULT_FIELDS = {
+  single: 'image_url',
+  multi: 'image_urls',
+  mask: 'mask_url',
+  control: 'control_image_url',
+  reference: 'reference_image_urls',
+  start: 'start_image_url',
+  end: 'end_image_url',
+} satisfies Required<FalImageFieldOverride>
+
+/**
+ * Field names that accept an array of images. The generator asserts the
+ * SDK types agree with this set, so wrap-vs-scalar decisions stay correct.
+ */
+const LIST_FIELDS = new Set<string>([
+  'image_urls',
+  'input_image_urls',
+  'ref_image_urls',
+  'reference_image_urls',
+])
+
+/** Resolve the per-role field names for a model: defaults + generated overrides. */
+function fieldSpecFor(model: string): Required<FalImageFieldOverride> {
+  const overrides = (
+    FAL_IMAGE_FIELD_OVERRIDES as Record<string, FalImageFieldOverride>
+  )[model]
+  return { ...DEFAULT_FIELDS, ...overrides }
+}
+
+/**
+ * Assign URLs to a field, wrapping or unwrapping based on whether the field
+ * takes an array. When two roles resolve to the same list field (e.g.
+ * sources and references both land on `image_urls` for nano-banana edit)
+ * the values are merged in assignment order; two roles resolving to the
+ * same scalar field is ambiguous and throws. Throws when multiple images
+ * target a scalar field.
+ */
+function assignField(
+  fields: Record<string, unknown>,
+  field: string,
+  urls: Array<string>,
+  model: string,
+  what: string,
+): void {
+  if (urls.length === 0) return
+  const existing = fields[field]
+  if (LIST_FIELDS.has(field)) {
+    fields[field] = Array.isArray(existing) ? [...existing, ...urls] : urls
+  } else if (existing !== undefined) {
+    throw new Error(
+      `fal: multiple inputs map to '${field}' on model ${model}. Drop one of the conflicting inputs or pass the field explicitly via modelOptions.`,
+    )
+  } else if (urls.length === 1) {
+    fields[field] = urls[0]
+  } else {
+    throw new Error(
+      `fal: model ${model} accepts a single ${what} image via '${field}' (received ${urls.length}).`,
+    )
+  }
+}
+
+interface RoleBuckets {
+  sources: Array<string>
+  masks: Array<string>
+  controls: Array<string>
+  references: Array<string>
+  starts: Array<string>
+  ends: Array<string>
+}
+
+function bucketByRole(
+  imageInputs: ReadonlyArray<ImagePart<MediaInputMetadata>>,
+): RoleBuckets {
+  const buckets: RoleBuckets = {
+    sources: [],
+    masks: [],
+    controls: [],
+    references: [],
+    starts: [],
+    ends: [],
+  }
+  for (const part of imageInputs) {
+    const url = imagePartToUrl(part)
+    const role = part.metadata?.role
+    if (role === 'mask') buckets.masks.push(url)
+    else if (role === 'control') buckets.controls.push(url)
+    else if (role === 'reference' || role === 'character')
+      buckets.references.push(url)
+    else if (role === 'start_frame') buckets.starts.push(url)
+    else if (role === 'end_frame') buckets.ends.push(url)
+    else buckets.sources.push(url)
+  }
+  return buckets
+}
+
+/**
+ * Map the prompt's image parts onto fal.ai image-endpoint fields.
+ *
+ * fal endpoints use different field names for image-conditioned generation
+ * (~80% use `image_url` for single; the rest use `image_urls`,
+ * `reference_image_urls`, `mask_url`, `control_image_url`, etc.). Field
+ * names are resolved per endpoint from the generated
+ * `FAL_IMAGE_FIELD_OVERRIDES` map (derived from the fal SDK's endpoint
+ * types), falling back to the defaults above for endpoints the installed
+ * SDK doesn't know:
+ *
+ * - parts with `metadata.role === 'mask'`      → spec.mask      (single)
+ * - parts with `metadata.role === 'control'`   → spec.control   (single)
+ * - `role === 'reference' | 'character'`       → spec.reference
+ * - `role === 'start_frame' | 'end_frame'`     → treated as sources (frame
+ *   roles only apply to video generation)
+ * - remaining parts                            → spec.single / spec.multi
+ *
+ * Users can always override the resulting field shape via `modelOptions`
+ * (spread before these fields), or pass everything through `modelOptions`
+ * directly when the mapping doesn't match an obscure endpoint.
+ */
+export function mapImageInputsToFalFields<TModel extends FalModel>(
+  model: TModel,
+  imageInputs?: ReadonlyArray<ImagePart<MediaInputMetadata>>,
+): FalImageInputFields<TModel> {
+  if (!imageInputs || imageInputs.length === 0) return {}
+
+  const spec = fieldSpecFor(model)
+  const { sources, masks, controls, references, starts, ends } =
+    bucketByRole(imageInputs)
+  // Frame roles aren't meaningful for image generation; treat as the
+  // primary source. The video mapper handles start/end framing.
+  const allSources = [...sources, ...starts, ...ends]
+
+  if (masks.length > 1) {
+    throw new Error(
+      `fal: only one input with metadata.role === 'mask' is supported per request (received ${masks.length}).`,
+    )
+  }
+  if (controls.length > 1) {
+    throw new Error(
+      `fal: only one input with metadata.role === 'control' is supported per request (received ${controls.length}).`,
+    )
+  }
+
+  const fields: Record<string, unknown> = {}
+  const sourceField = allSources.length > 1 ? spec.multi : spec.single
+  assignField(fields, sourceField, allSources, model, 'source')
+  assignField(fields, spec.reference, references, model, 'reference')
+  assignField(fields, spec.mask, masks, model, 'mask')
+  assignField(fields, spec.control, controls, model, 'control')
+
+  return fields as FalImageInputFields<TModel>
+}
+
+/**
+ * Map the prompt's image parts onto fal.ai video-endpoint fields.
+ *
+ * Video endpoints often expose a start frame as `image_url` (76% of i2v
+ * models) plus an optional `end_image_url`. Multi-reference video models
+ * (Kling O3, Seedance reference-to-video) use `reference_image_urls` or
+ * `image_urls`. Field names resolve through the same generated override
+ * map as the image mapper — e.g. `role: 'start_frame'` lands on `image_url`
+ * for Kling/Veo image-to-video and `first_frame_url` for Pixverse. Mapping:
+ *
+ * - `metadata.role === 'start_frame'`              → spec.start
+ * - `metadata.role === 'end_frame'`                → spec.end
+ * - `metadata.role === 'reference' | 'character'`  → spec.reference
+ * - `metadata.role === 'mask' | 'control'`         → throws (no video routing)
+ * - remaining parts (no role)                      → spec.single / spec.multi
+ */
+export function mapImageInputsToFalVideoFields<TModel extends FalModel>(
+  model: TModel,
+  imageInputs?: ReadonlyArray<ImagePart<MediaInputMetadata>>,
+): FalImageInputFields<TModel> {
+  if (!imageInputs || imageInputs.length === 0) return {}
+
+  const spec = fieldSpecFor(model)
+  const { sources, masks, controls, references, starts, ends } =
+    bucketByRole(imageInputs)
+  // Mask / control roles have no video-specific routing; silently repurposing
+  // them as source frames would hide the problem, so reject them instead.
+  if (masks.length > 0 || controls.length > 0) {
+    const role = masks.length > 0 ? 'mask' : 'control'
+    throw new Error(
+      `fal: metadata.role === '${role}' is not supported for video generation on model ${model}. ` +
+        `Remove the role or pass the field explicitly via modelOptions.`,
+    )
+  }
+
+  if (starts.length > 1) {
+    throw new Error(
+      `fal: only one input with metadata.role === 'start_frame' is supported (received ${starts.length}).`,
+    )
+  }
+  if (ends.length > 1) {
+    throw new Error(
+      `fal: only one input with metadata.role === 'end_frame' is supported (received ${ends.length}).`,
+    )
+  }
+
+  const fields: Record<string, unknown> = {}
+  const sourceField = sources.length > 1 ? spec.multi : spec.single
+  assignField(fields, sourceField, sources, model, 'source')
+  assignField(fields, spec.reference, references, model, 'reference')
+  // Frame roles assign last: when an endpoint routes the start frame to its
+  // generic source field (e.g. Kling image-to-video) and an unroled source
+  // was also provided, assignField rejects the ambiguous combination.
+  assignField(fields, spec.start, starts, model, 'start frame')
+  assignField(fields, spec.end, ends, model, 'end frame')
+
+  return fields as FalImageInputFields<TModel>
+}
+
+/**
+ * Convert a TanStack ImagePart into a string suitable for fal's URL-based
+ * input fields. URL sources pass through; data sources are emitted as a
+ * `data:<mime>;base64,<value>` URI which fal endpoints accept on the wire.
+ */
+function imagePartToUrl(part: ImagePart<MediaInputMetadata>): string {
+  if (part.source.type === 'url') return part.source.value
+  return `data:${part.source.mimeType};base64,${part.source.value}`
+}
diff --git a/packages/ai-fal/src/model-meta.ts b/packages/ai-fal/src/model-meta.ts
index 5aa5367ca..c6f408356 100644
--- a/packages/ai-fal/src/model-meta.ts
+++ b/packages/ai-fal/src/model-meta.ts
@@ -4,6 +4,8 @@
  * These types give you full autocomplete and type safety for any model.
  */
 import type { EndpointTypeMap } from '@fal-ai/client/endpoints'
+import type { MediaPromptModality } from '@tanstack/ai'
+import type { FalImageFieldName } from './image/generated/image-field-overrides'
 
 export type { EndpointTypeMap } from '@fal-ai/client/endpoints'
 
@@ -70,6 +72,32 @@ export type FalModelImageSizeInput<TModel extends string> =
         : never
     : { image_size: string }
 
+/**
+ * Input fields the prompt-part mappers can populate: image conditioning via
+ * the generated `FalImageFieldName` set, video conditioning via
+ * `video_url` / `video_urls` / `reference_video_urls`, audio via `audio_url`.
+ */
+type FalMediaInputFieldName =
+  | FalImageFieldName
+  | 'video_url'
+  | 'video_urls'
+  | 'reference_video_urls'
+  | 'audio_url'
+
+/**
+ * Demote an endpoint input's media-conditioning fields from required to
+ * optional. Image-to-video endpoints declare e.g. `image_url` as a required
+ * input, but with a multimodal `prompt` the start frame usually arrives as a
+ * prompt part — requiring it in `modelOptions` too would force redundancy.
+ * The fields stay passable via `modelOptions` as the documented escape hatch
+ * (and override-wise the mapped prompt-part fields win on conflict).
+ */
+type WithOptionalMediaInputFields<TInput> = Omit<
+  TInput,
+  Extract<keyof TInput, FalMediaInputFieldName>
+> &
+  Partial<Pick<TInput, Extract<keyof TInput, FalMediaInputFieldName>>>
+
 /**
  * Provider options for image generation, excluding fields TanStack AI handles.
  * Use this for the `modelOptions` parameter in image generation.
@@ -78,10 +106,8 @@ export type FalModelImageSizeInput<TModel extends string> =
  * type FluxOptions = FalImageProviderOptions<'fal-ai/flux/dev'>
  * // { num_inference_steps?: number; guidance_scale?: number; seed?: number; ... }
  */
-export type FalImageProviderOptions<TModel extends string> = Omit<
-  FalModelInput<TModel>,
-  'prompt'
->
+export type FalImageProviderOptions<TModel extends string> =
+  WithOptionalMediaInputFields<Omit<FalModelInput<TModel>, 'prompt'>>
 
 /**
  * Extract the video size type supported by a specific fal model.
@@ -118,13 +144,57 @@ export type FalModelVideoSizeInput<TModel extends string> =
         : never
     : { aspect_ratio?: string; resolution?: string }
 
+/**
+ * Prompt input modalities for a fal image endpoint, derived from the SDK's
+ * endpoint input type: an endpoint accepts image prompt parts exactly when
+ * its input declares one of the known image-conditioning fields
+ * (`image_url`, `image_urls`, `mask_url`, …). Endpoints unknown to the
+ * installed SDK are unconstrained.
+ */
+export type FalImagePromptModalitiesFor<TModel extends string> =
+  TModel extends keyof EndpointTypeMap
+    ? ReadonlyArray<
+        Extract<keyof FalModelInput<TModel>, FalImageFieldName> extends never
+          ? never
+          : 'image'
+      >
+    : ReadonlyArray<MediaPromptModality>
+
+/**
+ * Prompt input modalities for a fal video endpoint. Image conditioning is
+ * detected via the same field set as image endpoints; video conditioning via
+ * `video_url` / `video_urls` / `reference_video_urls`; audio conditioning
+ * via `audio_url`. Endpoints unknown to the installed SDK are unconstrained.
+ */
+export type FalVideoPromptModalitiesFor<TModel extends string> =
+  TModel extends keyof EndpointTypeMap
+    ? ReadonlyArray<
+        | (Extract<keyof FalModelInput<TModel>, FalImageFieldName> extends never
+            ? never
+            : 'image')
+        | (Extract<
+            keyof FalModelInput<TModel>,
+            'video_url' | 'video_urls' | 'reference_video_urls'
+          > extends never
+            ? never
+            : 'video')
+        | (Extract<keyof FalModelInput<TModel>, 'audio_url'> extends never
+            ? never
+            : 'audio')
+      >
+    : ReadonlyArray<MediaPromptModality>
+
 /**
  * Provider options for video generation, excluding fields TanStack AI handles.
  * Use this for the `modelOptions` parameter in video generation.
+ *
+ * Media-conditioning fields (start/end frame, reference images, source
+ * video/audio) are optional here even when the endpoint requires them —
+ * they're usually supplied as prompt parts instead.
  */
 export type FalVideoProviderOptions<TModel extends string> =
   TModel extends keyof EndpointTypeMap
-    ? Omit<FalModelInput<TModel>, 'prompt'>
+    ? WithOptionalMediaInputFields<Omit<FalModelInput<TModel>, 'prompt'>>
     : Record<string, unknown>
 
 /**
diff --git a/packages/ai-fal/tests/image-inputs.test.ts b/packages/ai-fal/tests/image-inputs.test.ts
new file mode 100644
index 000000000..ead3d76c2
--- /dev/null
+++ b/packages/ai-fal/tests/image-inputs.test.ts
@@ -0,0 +1,262 @@
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { describe, expect, it } from 'vitest'
+import {
+  mapImageInputsToFalFields,
+  mapImageInputsToFalVideoFields,
+} from '../src/image/image-inputs'
+import { FAL_ENDPOINTS_DTS_SHA256 } from '../src/image/generated/image-field-overrides'
+import type { ImagePart, MediaInputMetadata } from '@tanstack/ai'
+
+/** A model id unknown to the SDK — exercises the default field mapping. */
+const UNKNOWN_MODEL = 'custom-org/not-in-sdk'
+
+function urlPart(
+  value: string,
+  metadata?: MediaInputMetadata,
+): ImagePart<MediaInputMetadata> {
+  return {
+    type: 'image',
+    source: { type: 'url', value },
+    ...(metadata && { metadata }),
+  }
+}
+
+describe('mapImageInputsToFalFields', () => {
+  it('returns an empty object when imageInputs is missing or empty', () => {
+    expect(mapImageInputsToFalFields(UNKNOWN_MODEL, undefined)).toEqual({})
+    expect(mapImageInputsToFalFields(UNKNOWN_MODEL, [])).toEqual({})
+  })
+
+  it('routes a single source to image_url', () => {
+    expect(
+      mapImageInputsToFalFields(UNKNOWN_MODEL, [
+        urlPart('https://example.com/a.png'),
+      ]),
+    ).toEqual({ image_url: 'https://example.com/a.png' })
+  })
+
+  it('routes multiple sources to image_urls', () => {
+    expect(
+      mapImageInputsToFalFields(UNKNOWN_MODEL, [
+        urlPart('https://example.com/a.png'),
+        urlPart('https://example.com/b.png'),
+      ]),
+    ).toEqual({
+      image_urls: ['https://example.com/a.png', 'https://example.com/b.png'],
+    })
+  })
+
+  it('routes role=mask to mask_url alongside the source image_url', () => {
+    expect(
+      mapImageInputsToFalFields(UNKNOWN_MODEL, [
+        urlPart('https://example.com/img.png'),
+        urlPart('https://example.com/mask.png', { role: 'mask' }),
+      ]),
+    ).toEqual({
+      image_url: 'https://example.com/img.png',
+      mask_url: 'https://example.com/mask.png',
+    })
+  })
+
+  it('routes role=reference to reference_image_urls', () => {
+    expect(
+      mapImageInputsToFalFields(UNKNOWN_MODEL, [
+        urlPart('https://example.com/product.png'),
+        urlPart('https://example.com/style.png', { role: 'reference' }),
+        urlPart('https://example.com/character.png', { role: 'character' }),
+      ]),
+    ).toEqual({
+      image_url: 'https://example.com/product.png',
+      reference_image_urls: [
+        'https://example.com/style.png',
+        'https://example.com/character.png',
+      ],
+    })
+  })
+
+  it('routes role=control to control_image_url', () => {
+    expect(
+      mapImageInputsToFalFields(UNKNOWN_MODEL, [
+        urlPart('https://example.com/img.png'),
+        urlPart('https://example.com/depth.png', { role: 'control' }),
+      ]),
+    ).toEqual({
+      image_url: 'https://example.com/img.png',
+      control_image_url: 'https://example.com/depth.png',
+    })
+  })
+
+  it('encodes data sources as data URIs', () => {
+    expect(
+      mapImageInputsToFalFields(UNKNOWN_MODEL, [
+        {
+          type: 'image',
+          source: { type: 'data', value: 'aGVsbG8=', mimeType: 'image/png' },
+        },
+      ]),
+    ).toEqual({ image_url: 'data:image/png;base64,aGVsbG8=' })
+  })
+
+  it('throws when more than one mask is provided', () => {
+    expect(() =>
+      mapImageInputsToFalFields(UNKNOWN_MODEL, [
+        urlPart('https://example.com/m1.png', { role: 'mask' }),
+        urlPart('https://example.com/m2.png', { role: 'mask' }),
+      ]),
+    ).toThrow(/only one input with metadata.role === 'mask'/)
+  })
+
+  describe('generated endpoint overrides', () => {
+    it('routes a single source to image_urls on endpoints without a scalar field', () => {
+      // nano-banana edit has image_urls but no image_url
+      expect(
+        mapImageInputsToFalFields('fal-ai/nano-banana/edit', [
+          urlPart('https://example.com/a.png'),
+        ]),
+      ).toEqual({ image_urls: ['https://example.com/a.png'] })
+    })
+
+    it('merges sources and references when both resolve to the same list field', () => {
+      expect(
+        mapImageInputsToFalFields('fal-ai/nano-banana/edit', [
+          urlPart('https://example.com/product.png'),
+          urlPart('https://example.com/style.png', { role: 'reference' }),
+        ]),
+      ).toEqual({
+        image_urls: [
+          'https://example.com/product.png',
+          'https://example.com/style.png',
+        ],
+      })
+    })
+
+    it('routes role=mask to endpoint-specific mask field names', () => {
+      // gpt-image-1.5 edit uses mask_image_url instead of mask_url
+      expect(
+        mapImageInputsToFalFields('fal-ai/gpt-image-1.5/edit', [
+          urlPart('https://example.com/img.png'),
+          urlPart('https://example.com/mask.png', { role: 'mask' }),
+        ]),
+      ).toEqual({
+        image_urls: ['https://example.com/img.png'],
+        mask_image_url: 'https://example.com/mask.png',
+      })
+    })
+  })
+})
+
+describe('mapImageInputsToFalVideoFields', () => {
+  it('returns empty for missing/empty inputs', () => {
+    expect(mapImageInputsToFalVideoFields(UNKNOWN_MODEL, undefined)).toEqual({})
+    expect(mapImageInputsToFalVideoFields(UNKNOWN_MODEL, [])).toEqual({})
+  })
+
+  it('routes a single positional source to image_url (start frame)', () => {
+    expect(
+      mapImageInputsToFalVideoFields(UNKNOWN_MODEL, [
+        urlPart('https://example.com/start.png'),
+      ]),
+    ).toEqual({ image_url: 'https://example.com/start.png' })
+  })
+
+  it('routes role=start_frame to start_image_url and role=end_frame to end_image_url', () => {
+    expect(
+      mapImageInputsToFalVideoFields(UNKNOWN_MODEL, [
+        urlPart('https://example.com/a.png', { role: 'start_frame' }),
+        urlPart('https://example.com/z.png', { role: 'end_frame' }),
+      ]),
+    ).toEqual({
+      start_image_url: 'https://example.com/a.png',
+      end_image_url: 'https://example.com/z.png',
+    })
+  })
+
+  it('routes role=reference to reference_image_urls', () => {
+    expect(
+      mapImageInputsToFalVideoFields(UNKNOWN_MODEL, [
+        urlPart('https://example.com/start.png'),
+        urlPart('https://example.com/character.png', { role: 'reference' }),
+      ]),
+    ).toEqual({
+      image_url: 'https://example.com/start.png',
+      reference_image_urls: ['https://example.com/character.png'],
+    })
+  })
+
+  it('throws on mask/control roles instead of repurposing them as sources', () => {
+    expect(() =>
+      mapImageInputsToFalVideoFields(UNKNOWN_MODEL, [
+        urlPart('https://example.com/start.png'),
+        urlPart('https://example.com/mask.png', { role: 'mask' }),
+      ]),
+    ).toThrow(/'mask' is not supported for video generation/)
+    expect(() =>
+      mapImageInputsToFalVideoFields(UNKNOWN_MODEL, [
+        urlPart('https://example.com/depth.png', { role: 'control' }),
+      ]),
+    ).toThrow(/'control' is not supported for video generation/)
+  })
+
+  describe('generated endpoint overrides', () => {
+    it('routes role=start_frame to the source field on image-to-video endpoints', () => {
+      // Kling i2v takes the start frame as plain image_url, the end frame
+      // as tail_image_url
+      expect(
+        mapImageInputsToFalVideoFields(
+          'fal-ai/kling-video/v2.5-turbo/pro/image-to-video',
+          [
+            urlPart('https://example.com/start.png', { role: 'start_frame' }),
+            urlPart('https://example.com/end.png', { role: 'end_frame' }),
+          ],
+        ),
+      ).toEqual({
+        image_url: 'https://example.com/start.png',
+        tail_image_url: 'https://example.com/end.png',
+      })
+    })
+
+    it('routes frame roles to first/last frame fields on frame-to-video endpoints', () => {
+      expect(
+        mapImageInputsToFalVideoFields(
+          'fal-ai/veo3.1/first-last-frame-to-video',
+          [
+            urlPart('https://example.com/first.png', { role: 'start_frame' }),
+            urlPart('https://example.com/last.png', { role: 'end_frame' }),
+          ],
+        ),
+      ).toEqual({
+        first_frame_url: 'https://example.com/first.png',
+        last_frame_url: 'https://example.com/last.png',
+      })
+    })
+
+    it('throws when a source and start_frame both resolve to the same scalar field', () => {
+      expect(() =>
+        mapImageInputsToFalVideoFields(
+          'fal-ai/kling-video/v2.5-turbo/pro/image-to-video',
+          [
+            urlPart('https://example.com/source.png'),
+            urlPart('https://example.com/start.png', { role: 'start_frame' }),
+          ],
+        ),
+      ).toThrow(/multiple inputs map to 'image_url'/)
+    })
+  })
+})
+
+describe('generated image-field-overrides artifact', () => {
+  it('matches the installed @fal-ai/client endpoint types', () => {
+    const require = createRequire(import.meta.url)
+    const endpointsJs = require.resolve('@fal-ai/client/endpoints')
+    const endpointsDts = endpointsJs.replace(/\.js$/, '.d.ts')
+    const hash = createHash('sha256')
+      .update(readFileSync(endpointsDts))
+      .digest('hex')
+    expect(
+      hash,
+      'image-field-overrides.ts is stale for the installed @fal-ai/client. Run: pnpm generate:fal-image-fields',
+    ).toBe(FAL_ENDPOINTS_DTS_SHA256)
+  })
+})
diff --git a/packages/ai-fal/tests/video-adapter.test.ts b/packages/ai-fal/tests/video-adapter.test.ts
index 08e1cec06..5a8021d39 100644
--- a/packages/ai-fal/tests/video-adapter.test.ts
+++ b/packages/ai-fal/tests/video-adapter.test.ts
@@ -1,7 +1,18 @@
 import { beforeEach, describe, expect, it, vi } from 'vitest'
 import { generateVideo } from '@tanstack/ai'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
 
 import { falVideo } from '../src/adapters/video'
+import type { FalVideoProviderOptions } from '../src/model-meta'
+
+const testLogger = resolveDebugOption(false)
+
+// Compile-time: the kling i2v endpoint declares `image_url` as a REQUIRED
+// input, but it's demoted to optional in provider options because the start
+// frame usually arrives as a prompt part instead of modelOptions.
+const emptyI2vOptions: FalVideoProviderOptions<'fal-ai/kling-video/v3/pro/image-to-video'> =
+  {}
+void emptyI2vOptions
 
 // Declare mocks at module level
 let mockQueueSubmit: any
@@ -154,6 +165,88 @@ describe('Fal Video Adapter', () => {
     })
   })
 
+  describe('createVideoJob with a multimodal prompt', () => {
+    it('maps prompt media parts onto fal input fields', async () => {
+      mockQueueSubmit.mockResolvedValueOnce({ request_id: 'job-mm' })
+
+      const adapter = createAdapter()
+
+      await adapter.createVideoJob({
+        model: 'fal-ai/veo3/image-to-video',
+        prompt: [
+          { type: 'text', content: 'Slow cinematic push-in' },
+          {
+            type: 'image',
+            source: { type: 'url', value: 'https://example.com/start.png' },
+          },
+          {
+            type: 'video',
+            source: { type: 'url', value: 'https://example.com/ref.mp4' },
+            metadata: { role: 'reference' },
+          },
+          {
+            type: 'audio',
+            source: { type: 'url', value: 'https://example.com/voice.mp3' },
+          },
+        ],
+        logger: testLogger,
+      })
+
+      const [, options] = mockQueueSubmit.mock.calls[0]!
+      expect(options.input).toEqual({
+        prompt: 'Slow cinematic push-in',
+        image_url: 'https://example.com/start.png',
+        reference_video_urls: ['https://example.com/ref.mp4'],
+        audio_url: 'https://example.com/voice.mp3',
+      })
+    })
+
+    it('omits the prompt field for media-only prompts', async () => {
+      mockQueueSubmit.mockResolvedValueOnce({ request_id: 'job-i2v' })
+
+      const adapter = createAdapter()
+
+      await adapter.createVideoJob({
+        model: 'fal-ai/veo3/image-to-video',
+        prompt: [
+          {
+            type: 'image',
+            source: { type: 'url', value: 'https://example.com/start.png' },
+          },
+        ],
+        logger: testLogger,
+      })
+
+      const [, options] = mockQueueSubmit.mock.calls[0]!
+      expect(options.input).toEqual({
+        image_url: 'https://example.com/start.png',
+      })
+    })
+
+    it('throws when more than one audio prompt part is provided', async () => {
+      const adapter = createAdapter()
+
+      await expect(
+        adapter.createVideoJob({
+          model: 'fal-ai/veo3/image-to-video',
+          prompt: [
+            { type: 'text', content: 'x' },
+            {
+              type: 'audio',
+              source: { type: 'url', value: 'https://example.com/a.mp3' },
+            },
+            {
+              type: 'audio',
+              source: { type: 'url', value: 'https://example.com/b.mp3' },
+            },
+          ],
+          logger: testLogger,
+        }),
+      ).rejects.toThrow(/exactly one audio prompt part/)
+      expect(mockQueueSubmit).not.toHaveBeenCalled()
+    })
+  })
+
   describe('getVideoStatus', () => {
     it('returns pending status for queued jobs', async () => {
       mockQueueStatus.mockResolvedValueOnce({
diff --git a/packages/ai-gemini/src/adapters/image.ts b/packages/ai-gemini/src/adapters/image.ts
index 35d32b857..b107df197 100644
--- a/packages/ai-gemini/src/adapters/image.ts
+++ b/packages/ai-gemini/src/adapters/image.ts
@@ -1,4 +1,6 @@
+import { resolveMediaPrompt } from '@tanstack/ai'
 import { BaseImageAdapter } from '@tanstack/ai/adapters'
+import { arrayBufferToBase64 } from '@tanstack/ai-utils'
 import {
   createGeminiClient,
   generateId,
@@ -14,6 +16,7 @@ import {
 } from '../image/image-provider-options'
 import type { GEMINI_IMAGE_MODELS } from '../model-meta'
 import type {
+  GeminiImageModelInputModalitiesByName,
   GeminiImageModelProviderOptionsByName,
   GeminiImageModelSizeByName,
   GeminiImageProviderOptions,
@@ -22,13 +25,18 @@ import type {
   GeneratedImage,
   ImageGenerationOptions,
   ImageGenerationResult,
+  ImagePart,
+  MediaInputMetadata,
+  ResolvedMediaPrompt,
 } from '@tanstack/ai'
 import type {
+  Content,
   GenerateContentConfig,
   GenerateContentResponse,
   GenerateImagesConfig,
   GenerateImagesResponse,
   GoogleGenAI,
+  Part,
 } from '@google/genai'
 import type { GeminiClientConfig } from '../utils'
 
@@ -60,7 +68,8 @@ export class GeminiImageAdapter<
   TModel,
   GeminiImageProviderOptions,
   GeminiImageModelProviderOptionsByName,
-  GeminiImageModelSizeByName
+  GeminiImageModelSizeByName,
+  GeminiImageModelInputModalitiesByName
 > {
   override readonly kind = 'image' as const
   readonly name = 'gemini' as const
@@ -70,6 +79,7 @@ export class GeminiImageAdapter<
     providerOptions: GeminiImageProviderOptions
     modelProviderOptionsByName: GeminiImageModelProviderOptionsByName
     modelSizeByName: GeminiImageModelSizeByName
+    modelInputModalitiesByName: GeminiImageModelInputModalitiesByName
   }
 
   private readonly client: GoogleGenAI
@@ -82,7 +92,7 @@ export class GeminiImageAdapter<
   async generateImages(
     options: ImageGenerationOptions<GeminiImageProviderOptions>,
   ): Promise<ImageGenerationResult> {
-    const { model, prompt, logger } = options
+    const { model, logger } = options
 
     logger.request(
       `activity=generateImage provider=gemini model=${this.model}`,
@@ -93,10 +103,35 @@ export class GeminiImageAdapter<
     )
 
     try {
-      validatePrompt({ prompt, model })
+      const resolved = resolveMediaPrompt(options.prompt)
+
+      // Image-only prompts are allowed (the image inputs carry the intent);
+      // a prompt with neither text nor images is always an error.
+      if (resolved.images.length === 0) {
+        validatePrompt({ prompt: resolved.text, model })
+      }
+
+      if (resolved.videos.length > 0) {
+        throw new Error(
+          `${this.name}.generateImages does not support video prompt parts (model: ${model}).`,
+        )
+      }
+      if (resolved.audios.length > 0) {
+        throw new Error(
+          `${this.name}.generateImages does not support audio prompt parts (model: ${model}).`,
+        )
+      }
 
       if (this.isGeminiImageModel(model)) {
-        return await this.generateWithGeminiApi(options)
+        return await this.generateWithGeminiApi(options, resolved)
+      }
+
+      // Imagen does not accept image inputs — it's strictly text-to-image.
+      if (resolved.images.length > 0) {
+        throw new Error(
+          `${this.name}: model "${model}" (Imagen) does not support image prompt parts. ` +
+            `Use a Gemini-native image model (e.g. gemini-2.5-flash-image, "nano-banana") for image-conditioned generation.`,
+        )
       }
 
       // Imagen models path (generateImages API)
@@ -107,7 +142,7 @@ export class GeminiImageAdapter<
 
       const response = await this.client.models.generateImages({
         model,
-        prompt,
+        prompt: resolved.text,
         config,
       })
 
@@ -127,18 +162,12 @@ export class GeminiImageAdapter<
 
   private async generateWithGeminiApi(
     options: ImageGenerationOptions<GeminiImageProviderOptions>,
+    resolved: ResolvedMediaPrompt,
   ): Promise<ImageGenerationResult> {
-    const { model, prompt, size, numberOfImages, modelOptions } = options
+    const { model, size, numberOfImages, modelOptions } = options
 
     const parsedSize = size ? parseNativeImageSize(size) : undefined
 
-    // The generateContent API has no numberOfImages parameter.
-    // Instead, augment the prompt to request multiple images when needed.
-    const augmentedPrompt =
-      numberOfImages && numberOfImages > 1
-        ? `${prompt} Generate ${numberOfImages} distinct images.`
-        : prompt
-
     // GeminiImageProviderOptions is Imagen-shaped — most fields
     // (personGeneration, safetyFilterLevel, addWatermark, outputMimeType,
     // outputCompressionQuality, guidanceScale, enhancePrompt,
@@ -170,15 +199,105 @@ export class GeminiImageAdapter<
       }),
     }
 
+    const contents = await this.buildContents(resolved, numberOfImages)
+
     const response = await this.client.models.generateContent({
       model,
-      contents: augmentedPrompt,
+      contents,
       config,
     })
 
     return this.transformGeminiResponse(model, response)
   }
 
+  /**
+   * Build the multimodal `contents` payload. Text-only prompts pass through
+   * as a plain string (the SDK accepts it directly); prompts with image
+   * parts become a single user `Content` whose `parts` mirror the prompt's
+   * interleaved order — position is meaningful to Gemini ("not like this
+   * *(image)*, more like this *(image)*").
+   *
+   * The generateContent API has no numberOfImages parameter, so when more
+   * than one image is requested a trailing instruction is appended.
+   */
+  private async buildContents(
+    resolved: ResolvedMediaPrompt,
+    numberOfImages: number | undefined,
+  ): Promise<string | Array<Content>> {
+    const countInstruction =
+      numberOfImages && numberOfImages > 1
+        ? `Generate ${numberOfImages} distinct images.`
+        : undefined
+
+    if (resolved.images.length === 0) {
+      return countInstruction
+        ? `${resolved.text} ${countInstruction}`
+        : resolved.text
+    }
+
+    const parts: Array<Part> = await Promise.all(
+      resolved.parts.map((part) => {
+        if (part.type === 'text') {
+          return Promise.resolve<Part>({ text: part.content })
+        }
+        if (part.type === 'image') {
+          return this.imagePartToGeminiPart(part)
+        }
+        // Video / audio parts were rejected in generateImages above.
+        throw new Error(
+          `gemini: unsupported prompt part type "${part.type}" in image generation.`,
+        )
+      }),
+    )
+    if (countInstruction) {
+      parts.push({ text: countInstruction })
+    }
+    return [{ role: 'user', parts }]
+  }
+
+  private async imagePartToGeminiPart(
+    part: ImagePart<MediaInputMetadata>,
+  ): Promise<Part> {
+    if (part.source.type === 'data') {
+      return {
+        inlineData: {
+          mimeType: part.source.mimeType || 'image/png',
+          data: part.source.value,
+        },
+      }
+    }
+    // For URL sources, prefer passing the URL through as `fileData` when it
+    // looks like a Google Files API URI; otherwise fetch and inline as base64.
+    if (
+      part.source.value.startsWith('gs://') ||
+      /^https?:\/\/generativelanguage\.googleapis\.com\//.test(
+        part.source.value,
+      )
+    ) {
+      return {
+        fileData: {
+          fileUri: part.source.value,
+          ...(part.source.mimeType && { mimeType: part.source.mimeType }),
+        },
+      }
+    }
+    const response = await fetch(part.source.value)
+    if (!response.ok) {
+      throw new Error(
+        `Failed to fetch image input (${response.status} ${response.statusText}): ${part.source.value}`,
+      )
+    }
+    const blob = await response.blob()
+    const buffer = await blob.arrayBuffer()
+    const base64 = arrayBufferToBase64(buffer)
+    return {
+      inlineData: {
+        mimeType: part.source.mimeType || blob.type || 'image/png',
+        data: base64,
+      },
+    }
+  }
+
   private transformGeminiResponse(
     model: string,
     response: GenerateContentResponse,
diff --git a/packages/ai-gemini/src/image/image-provider-options.ts b/packages/ai-gemini/src/image/image-provider-options.ts
index a94f414f7..3779088be 100644
--- a/packages/ai-gemini/src/image/image-provider-options.ts
+++ b/packages/ai-gemini/src/image/image-provider-options.ts
@@ -190,6 +190,18 @@ export type GeminiImageModelSizeByName = {
   [K in Exclude<GeminiImageModels, GeminiNativeImageModels>]: GeminiImageSize
 }
 
+/**
+ * Per-model prompt input modalities. Gemini-native image models accept image
+ * parts in the multimodal prompt (image-conditioned generation via
+ * generateContent); Imagen models are strictly text-to-image, so their
+ * `prompt` is constrained to text at compile time.
+ */
+export type GeminiImageModelInputModalitiesByName = {
+  [K in GeminiNativeImageModels]: readonly ['image']
+} & {
+  [K in Exclude<GeminiImageModels, GeminiNativeImageModels>]: readonly []
+}
+
 /**
  * Valid sizes for Gemini Imagen models
  * Gemini uses aspect ratios, but we map common WIDTHxHEIGHT formats to aspect ratios
diff --git a/packages/ai-gemini/tests/image-adapter.test.ts b/packages/ai-gemini/tests/image-adapter.test.ts
index c2b7db2b0..64d9b0a76 100644
--- a/packages/ai-gemini/tests/image-adapter.test.ts
+++ b/packages/ai-gemini/tests/image-adapter.test.ts
@@ -1,5 +1,6 @@
 import { describe, it, expect, vi } from 'vitest'
 import { generateImage } from '@tanstack/ai'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
 import { GeminiImageAdapter, createGeminiImage } from '../src/adapters/image'
 import {
   parseNativeImageSize,
@@ -662,4 +663,177 @@ describe('Gemini Image Adapter', () => {
       })
     })
   })
+
+  describe('multimodal prompt (image-conditioned generation)', () => {
+    const testLogger = resolveDebugOption(false)
+    const mockImageResponse = {
+      candidates: [
+        {
+          content: {
+            parts: [{ inlineData: { mimeType: 'image/png', data: 'out' } }],
+          },
+        },
+      ],
+    }
+
+    function mockedNativeAdapter() {
+      const mockGenerateContent = vi
+        .fn()
+        .mockResolvedValueOnce(mockImageResponse)
+      const adapter = createGeminiImage(
+        'gemini-3.1-flash-image-preview',
+        'test-api-key',
+      )
+      ;(
+        adapter as unknown as {
+          client: { models: { generateContent: unknown } }
+        }
+      ).client = {
+        models: { generateContent: mockGenerateContent },
+      }
+      return { adapter, mockGenerateContent }
+    }
+
+    it('maps interleaved prompt parts onto multimodal contents in order', async () => {
+      const { adapter, mockGenerateContent } = mockedNativeAdapter()
+
+      await generateImage({
+        adapter,
+        prompt: [
+          { type: 'text', content: 'Not like this' },
+          {
+            type: 'image',
+            source: { type: 'data', value: 'YmFk', mimeType: 'image/jpeg' },
+          },
+          { type: 'text', content: 'more like this' },
+          {
+            type: 'image',
+            // Google Files API URIs pass through as fileData (no fetch).
+            source: {
+              type: 'url',
+              value:
+                'https://generativelanguage.googleapis.com/v1beta/files/abc',
+              mimeType: 'image/png',
+            },
+          },
+        ],
+      })
+
+      expect(mockGenerateContent).toHaveBeenCalledWith({
+        model: 'gemini-3.1-flash-image-preview',
+        contents: [
+          {
+            role: 'user',
+            parts: [
+              { text: 'Not like this' },
+              { inlineData: { mimeType: 'image/jpeg', data: 'YmFk' } },
+              { text: 'more like this' },
+              {
+                fileData: {
+                  fileUri:
+                    'https://generativelanguage.googleapis.com/v1beta/files/abc',
+                  mimeType: 'image/png',
+                },
+              },
+            ],
+          },
+        ],
+        config: { responseModalities: ['TEXT', 'IMAGE'] },
+      })
+    })
+
+    it('fetches arbitrary URL sources and inlines them as base64', async () => {
+      const { adapter, mockGenerateContent } = mockedNativeAdapter()
+      // 'hi' → base64 'aGk='
+      const fetchMock = vi.fn().mockResolvedValue(
+        new Response(new Uint8Array([104, 105]), {
+          headers: { 'content-type': 'image/jpeg' },
+        }),
+      )
+      vi.stubGlobal('fetch', fetchMock)
+
+      try {
+        await generateImage({
+          adapter,
+          prompt: [
+            { type: 'text', content: 'Edit this' },
+            {
+              type: 'image',
+              source: { type: 'url', value: 'https://example.com/photo.jpg' },
+            },
+          ],
+        })
+      } finally {
+        vi.unstubAllGlobals()
+      }
+
+      expect(fetchMock).toHaveBeenCalledWith('https://example.com/photo.jpg')
+      const args = mockGenerateContent.mock.calls[0]![0]
+      expect(args.contents).toEqual([
+        {
+          role: 'user',
+          parts: [
+            { text: 'Edit this' },
+            { inlineData: { mimeType: 'image/jpeg', data: 'aGk=' } },
+          ],
+        },
+      ])
+    })
+
+    it('rejects image prompt parts for Imagen models', async () => {
+      const adapter = createGeminiImage(
+        'imagen-4.0-generate-001',
+        'test-api-key',
+      )
+
+      await expect(
+        adapter.generateImages({
+          model: 'imagen-4.0-generate-001',
+          prompt: [
+            { type: 'text', content: 'Edit this' },
+            {
+              type: 'image',
+              source: { type: 'data', value: 'aGk=', mimeType: 'image/png' },
+            },
+          ],
+          logger: testLogger,
+        }),
+      ).rejects.toThrow(/does not support image prompt parts/)
+    })
+
+    it('rejects video and audio prompt parts', async () => {
+      const adapter = createGeminiImage(
+        'gemini-3.1-flash-image-preview',
+        'test-api-key',
+      )
+
+      await expect(
+        adapter.generateImages({
+          model: 'gemini-3.1-flash-image-preview',
+          prompt: [
+            { type: 'text', content: 'x' },
+            {
+              type: 'video',
+              source: { type: 'url', value: 'https://example.com/v.mp4' },
+            },
+          ],
+          logger: testLogger,
+        }),
+      ).rejects.toThrow(/video prompt parts/)
+
+      await expect(
+        adapter.generateImages({
+          model: 'gemini-3.1-flash-image-preview',
+          prompt: [
+            { type: 'text', content: 'x' },
+            {
+              type: 'audio',
+              source: { type: 'url', value: 'https://example.com/a.mp3' },
+            },
+          ],
+          logger: testLogger,
+        }),
+      ).rejects.toThrow(/audio prompt parts/)
+    })
+  })
 })
diff --git a/packages/ai-grok/src/adapters/image.ts b/packages/ai-grok/src/adapters/image.ts
index 6e88d815e..4a4641dae 100644
--- a/packages/ai-grok/src/adapters/image.ts
+++ b/packages/ai-grok/src/adapters/image.ts
@@ -1,10 +1,13 @@
 import OpenAI from 'openai'
+import { resolveMediaPrompt } from '@tanstack/ai'
 import { BaseImageAdapter } from '@tanstack/ai/adapters'
 import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
 import { buildImagesUsage } from '@tanstack/openai-base'
 import { generateId } from '@tanstack/ai-utils'
 import { getGrokApiKeyFromEnv, withGrokDefaults } from '../utils/client'
 import {
+  isGrokImagineImageModel,
+  parseGrokImagineSize,
   validateImageSize,
   validateNumberOfImages,
   validatePrompt,
@@ -13,10 +16,14 @@ import type {
   GeneratedImage,
   ImageGenerationOptions,
   ImageGenerationResult,
+  ImagePart,
+  MediaInputMetadata,
+  ResolvedMediaPrompt,
 } from '@tanstack/ai'
 import type OpenAI_SDK from 'openai'
 import type { GrokImageModel } from '../model-meta'
 import type {
+  GrokImageModelInputModalitiesByName,
   GrokImageModelProviderOptionsByName,
   GrokImageModelSizeByName,
   GrokImageProviderOptions,
@@ -28,15 +35,58 @@ import type { GrokClientConfig } from '../utils'
  */
 export interface GrokImageConfig extends GrokClientConfig {}
 
+/** Maximum source images accepted by xAI's image edit endpoint. */
+const MAX_EDIT_IMAGES = 3
+
+/**
+ * Maps the generic `size` option onto Imagine API parameters: the
+ * "aspectRatio_resolution" template ("16:9_2k") splits into `aspect_ratio`
+ * and optional `resolution` request fields.
+ */
+function imagineSizeParams(size: string | undefined): {
+  aspect_ratio?: string
+  resolution?: string
+} {
+  if (!size) return {}
+  const parsed = parseGrokImagineSize(size)
+  if (!parsed) return {}
+  return {
+    aspect_ratio: parsed.aspectRatio,
+    ...(parsed.resolution !== undefined && { resolution: parsed.resolution }),
+  }
+}
+
+/**
+ * Convert a TanStack ImagePart to the URL string accepted by xAI's edit
+ * endpoint: public URLs pass through (fetched by xAI's servers), data
+ * sources become base64 data URIs.
+ */
+function imagePartToUrl(part: ImagePart<MediaInputMetadata>): string {
+  if (part.source.type === 'url') return part.source.value
+  return `data:${part.source.mimeType};base64,${part.source.value}`
+}
+
+/** Response shape of xAI's `/v1/images/edits` endpoint. */
+interface GrokImageEditResponse {
+  data?: Array<{
+    url?: string | null
+    b64_json?: string | null
+    mime_type?: string
+  }>
+}
+
 /**
  * Grok Image Generation Adapter
  *
  * Tree-shakeable adapter for Grok image generation functionality.
- * Supports grok-2-image-1212 model.
+ * Supports the legacy grok-2-image-1212 model (text-to-image via the
+ * OpenAI-compat endpoint) and the grok-imagine image models, which also
+ * accept image prompt parts for image-conditioned generation via xAI's
+ * `/v1/images/edits` endpoint (up to 3 source images).
  *
  * Features:
  * - Model-specific type-safe provider options
- * - Size validation per model
+ * - Size / aspect-ratio validation per model
  * - Number of images validation
  */
 export class GrokImageAdapter<
@@ -45,36 +95,67 @@ export class GrokImageAdapter<
   TModel,
   GrokImageProviderOptions,
   GrokImageModelProviderOptionsByName,
-  GrokImageModelSizeByName
+  GrokImageModelSizeByName,
+  GrokImageModelInputModalitiesByName
 > {
   override readonly kind = 'image' as const
   readonly name = 'grok' as const
 
   protected client: OpenAI
+  private readonly clientConfig: GrokImageConfig
 
   constructor(config: GrokImageConfig, model: TModel) {
     super(model, {})
-    this.client = new OpenAI(withGrokDefaults(config))
+    this.clientConfig = withGrokDefaults(config)
+    this.client = new OpenAI(this.clientConfig)
   }
 
   async generateImages(
     options: ImageGenerationOptions<GrokImageProviderOptions>,
   ): Promise<ImageGenerationResult> {
-    const { model, prompt, numberOfImages, size, modelOptions } = options
+    const { model, numberOfImages, size, modelOptions } = options
+
+    const resolved = resolveMediaPrompt(options.prompt)
+    const prompt = resolved.text
+
+    if (resolved.videos.length > 0 || resolved.audios.length > 0) {
+      throw new Error(
+        `grok.generateImages does not support video / audio prompt parts on model ${model}.`,
+      )
+    }
+
+    if (resolved.images.length > 0) {
+      if (!isGrokImagineImageModel(model)) {
+        throw new Error(
+          `grok: model "${model}" does not support image prompt parts. ` +
+            `Image-conditioned generation requires an Imagine API model ` +
+            `('grok-imagine-image' or 'grok-imagine-image-quality').`,
+        )
+      }
+      return await this.editImages(options, resolved)
+    }
 
     validatePrompt({ prompt, model })
     validateImageSize(model, size)
     validateNumberOfImages(model, numberOfImages)
 
-    const resolvedSize = size as OpenAI_SDK.Images.ImageGenerateParams['size']
-    const request: OpenAI_SDK.Images.ImageGenerateParamsNonStreaming = {
+    // grok-imagine models are aspect-ratio sized: the generic `size` option
+    // carries an "aspectRatio_resolution" template (e.g. '16:9_2k', like
+    // Gemini native image models) and maps to the Imagine API's
+    // `aspect_ratio` / `resolution` parameters instead of OpenAI-style `size`.
+    const isImagine = isGrokImagineImageModel(model)
+    const request = {
       model,
       prompt,
       n: numberOfImages ?? 1,
-      ...(resolvedSize !== undefined && { size: resolvedSize }),
+      ...(isImagine
+        ? imagineSizeParams(size)
+        : size !== undefined && {
+            size: size,
+          }),
       stream: false,
       ...modelOptions,
-    }
+    } as OpenAI_SDK.Images.ImageGenerateParamsNonStreaming
 
     try {
       options.logger.request(
@@ -122,6 +203,106 @@ export class GrokImageAdapter<
       throw error
     }
   }
+
+  /**
+   * Image-conditioned generation via xAI's Imagine API.
+   *
+   * The `/v1/images/edits` endpoint takes `application/json` (the OpenAI
+   * SDK's `images.edit()` sends `multipart/form-data`, which xAI rejects),
+   * so this path issues the request directly. One input is sent as
+   * `image: { url }`; multiple inputs (up to 3) as `images: [{ url }, ...]`,
+   * addressed by xAI in the order they are sent. The prompt text is sent
+   * verbatim — no referencing markers are injected.
+   */
+  private async editImages(
+    options: ImageGenerationOptions<GrokImageProviderOptions>,
+    resolved: ResolvedMediaPrompt,
+  ): Promise<ImageGenerationResult> {
+    const { model, numberOfImages, size, modelOptions, logger } = options
+    const prompt = resolved.text
+    const imageInputs = resolved.images
+
+    const unsupportedRole = imageInputs.find(
+      (part) =>
+        part.metadata?.role === 'mask' || part.metadata?.role === 'control',
+    )
+    if (unsupportedRole) {
+      throw new Error(
+        `grok: the Imagine API has no ${unsupportedRole.metadata?.role} input; ` +
+          `only source/reference images are supported.`,
+      )
+    }
+    if (imageInputs.length > MAX_EDIT_IMAGES) {
+      throw new Error(
+        `grok: model "${model}" accepts at most ${MAX_EDIT_IMAGES} source images; received ${imageInputs.length}.`,
+      )
+    }
+
+    validatePrompt({ prompt, model })
+    validateImageSize(model, size)
+    validateNumberOfImages(model, numberOfImages)
+
+    const urls = imageInputs.map((part) => imagePartToUrl(part))
+    const request: Record<string, unknown> = {
+      model,
+      prompt,
+      ...(urls.length === 1
+        ? { image: { url: urls[0] } }
+        : { images: urls.map((url) => ({ url })) }),
+      ...(numberOfImages !== undefined && { n: numberOfImages }),
+      ...imagineSizeParams(size),
+      ...modelOptions,
+    }
+
+    try {
+      logger.request(
+        `activity=image provider=${this.name} model=${model} edit images=${urls.length}`,
+        { provider: this.name, model },
+      )
+
+      const response = await fetch(
+        `${this.clientConfig.baseURL}/images/edits`,
+        {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${this.clientConfig.apiKey}`,
+          },
+          body: JSON.stringify(request),
+        },
+      )
+      if (!response.ok) {
+        const body = await response.text()
+        throw new Error(
+          `grok: image edit request failed (${response.status} ${response.statusText}): ${body}`,
+        )
+      }
+
+      const result = (await response.json()) as GrokImageEditResponse
+      const images: Array<GeneratedImage> = (result.data ?? []).flatMap(
+        (item): Array<GeneratedImage> => {
+          if (item.b64_json) return [{ b64Json: item.b64_json }]
+          if (item.url) return [{ url: item.url }]
+          return []
+        },
+      )
+      if (images.length === 0) {
+        throw new Error('grok: image edit response contained no images')
+      }
+
+      return {
+        id: generateId(this.name),
+        model,
+        images,
+      }
+    } catch (error: unknown) {
+      logger.errors(`${this.name}.generateImages fatal`, {
+        error: toRunErrorPayload(error, `${this.name}.generateImages failed`),
+        source: `${this.name}.generateImages`,
+      })
+      throw error
+    }
+  }
 }
 
 /**
diff --git a/packages/ai-grok/src/image/image-provider-options.ts b/packages/ai-grok/src/image/image-provider-options.ts
index 9b0d9ee59..a43353444 100644
--- a/packages/ai-grok/src/image/image-provider-options.ts
+++ b/packages/ai-grok/src/image/image-provider-options.ts
@@ -10,6 +10,84 @@
  */
 export type GrokImageSize = '1024x1024' | '1536x1024' | '1024x1536'
 
+/**
+ * Aspect ratios accepted by the grok-imagine image models.
+ */
+export type GrokImagineAspectRatio =
+  | '1:1'
+  | '3:4'
+  | '4:3'
+  | '9:16'
+  | '16:9'
+  | '2:3'
+  | '3:2'
+  | '9:19.5'
+  | '19.5:9'
+  | '9:20'
+  | '20:9'
+  | '1:2'
+  | '2:1'
+  | 'auto'
+
+/**
+ * Resolution tiers for the grok-imagine image models.
+ */
+export type GrokImagineResolution = '1k' | '2k'
+
+/**
+ * Size strings for grok-imagine image models. The Imagine API is
+ * aspect-ratio based rather than pixel-size based; like Gemini's native
+ * image models, the generic `size` option uses an
+ * `aspectRatio_resolution` template ("16:9_2k") — the resolution suffix is
+ * optional ("16:9" uses the API default of 1k).
+ */
+export type GrokImagineImageSize =
+  | GrokImagineAspectRatio
+  | `${GrokImagineAspectRatio}_${GrokImagineResolution}`
+
+const GROK_IMAGINE_ASPECT_RATIOS: ReadonlyArray<string> = [
+  '1:1',
+  '3:4',
+  '4:3',
+  '9:16',
+  '16:9',
+  '2:3',
+  '3:2',
+  '9:19.5',
+  '19.5:9',
+  '9:20',
+  '20:9',
+  '1:2',
+  '2:1',
+  'auto',
+]
+
+const GROK_IMAGINE_RESOLUTIONS: ReadonlyArray<string> = ['1k', '2k']
+
+/**
+ * Models served by xAI's Imagine API. They are aspect-ratio sized and
+ * support image-conditioned generation via `/v1/images/edits`; the legacy
+ * grok-2-image-1212 model is pixel-sized and text-to-image only.
+ */
+export function isGrokImagineImageModel(model: string): boolean {
+  return model.startsWith('grok-imagine-image')
+}
+
+/**
+ * Parses a grok-imagine size string into its components.
+ * Format: "aspectRatio" or "aspectRatio_resolution",
+ * e.g. "16:9_2k" → { aspectRatio: "16:9", resolution: "2k" }.
+ * Returns undefined when the string doesn't match the template.
+ */
+export function parseGrokImagineSize(
+  size: string,
+): { aspectRatio: string; resolution?: string } | undefined {
+  const match = size.match(/^([\d.]+:[\d.]+|auto)(?:_(.+))?$/)
+  const [, aspectRatio, resolution] = match ?? []
+  if (aspectRatio === undefined) return undefined
+  return { aspectRatio, ...(resolution !== undefined && { resolution }) }
+}
+
 /**
  * Base provider options for Grok image models
  */
@@ -39,11 +117,37 @@ export interface GrokImageProviderOptions extends GrokImageBaseProviderOptions {
   response_format?: 'url' | 'b64_json'
 }
 
+/**
+ * Provider options for the grok-imagine image models (generation and
+ * image-conditioned editing via xAI's Imagine API).
+ */
+export interface GrokImagineImageProviderOptions extends GrokImageBaseProviderOptions {
+  /**
+   * The format in which generated images are returned.
+   * @default 'url'
+   */
+  response_format?: 'url' | 'b64_json'
+
+  /**
+   * Output resolution.
+   * @default '1k'
+   */
+  resolution?: '1k' | '2k'
+
+  /**
+   * Processing tier for the request.
+   * @default 'default'
+   */
+  service_tier?: 'default' | 'priority'
+}
+
 /**
  * Type-only map from model name to its specific provider options.
  */
 export type GrokImageModelProviderOptionsByName = {
   'grok-2-image-1212': GrokImageProviderOptions
+  'grok-imagine-image': GrokImagineImageProviderOptions
+  'grok-imagine-image-quality': GrokImagineImageProviderOptions
 }
 
 /**
@@ -51,6 +155,19 @@ export type GrokImageModelProviderOptionsByName = {
  */
 export type GrokImageModelSizeByName = {
   'grok-2-image-1212': GrokImageSize
+  'grok-imagine-image': GrokImagineImageSize
+  'grok-imagine-image-quality': GrokImagineImageSize
+}
+
+/**
+ * Per-model prompt input modalities. Imagine API models accept image parts
+ * in the prompt (routed to `/v1/images/edits`, up to 3 images, addressed by
+ * xAI in request order); grok-2-image is text-to-image only.
+ */
+export type GrokImageModelInputModalitiesByName = {
+  'grok-2-image-1212': readonly []
+  'grok-imagine-image': readonly ['image']
+  'grok-imagine-image-quality': readonly ['image']
 }
 
 /**
@@ -71,6 +188,23 @@ export function validateImageSize(
 ): void {
   if (!size) return
 
+  if (isGrokImagineImageModel(model)) {
+    const parsed = parseGrokImagineSize(size)
+    if (
+      !parsed ||
+      !GROK_IMAGINE_ASPECT_RATIOS.includes(parsed.aspectRatio) ||
+      (parsed.resolution !== undefined &&
+        !GROK_IMAGINE_RESOLUTIONS.includes(parsed.resolution))
+    ) {
+      throw new Error(
+        `Size "${size}" is not supported by model "${model}". ` +
+          `Expected an aspect ratio (${GROK_IMAGINE_ASPECT_RATIOS.join(', ')}) ` +
+          `optionally suffixed with a resolution ("16:9_2k"; resolutions: ${GROK_IMAGINE_RESOLUTIONS.join(', ')}).`,
+      )
+    }
+    return
+  }
+
   const validSizes: Record<string, Array<string>> = {
     'grok-2-image-1212': ['1024x1024', '1536x1024', '1024x1536'],
   }
diff --git a/packages/ai-grok/src/model-meta.ts b/packages/ai-grok/src/model-meta.ts
index 5b76aaa10..9047cbfeb 100644
--- a/packages/ai-grok/src/model-meta.ts
+++ b/packages/ai-grok/src/model-meta.ts
@@ -219,6 +219,39 @@ const GROK_2_IMAGE = {
   },
 } as const satisfies ModelMeta
 
+// Imagine API image models. Pricing is per generated image (output only).
+const GROK_IMAGINE_IMAGE = {
+  name: 'grok-imagine-image',
+  supports: {
+    input: ['text', 'image'],
+    output: ['image'],
+  },
+  pricing: {
+    input: {
+      normal: 0,
+    },
+    output: {
+      normal: 0.02,
+    },
+  },
+} as const satisfies ModelMeta
+
+const GROK_IMAGINE_IMAGE_QUALITY = {
+  name: 'grok-imagine-image-quality',
+  supports: {
+    input: ['text', 'image'],
+    output: ['image'],
+  },
+  pricing: {
+    input: {
+      normal: 0,
+    },
+    output: {
+      normal: 0.05,
+    },
+  },
+} as const satisfies ModelMeta
+
 /**
  * Grok Chat Models
  * Based on xAI's available models as of 2025
@@ -349,7 +382,11 @@ export const GROK_COMBINED_TOOLS_AND_SCHEMA_MODELS = new Set<string>([
 /**
  * Grok Image Generation Models
  */
-export const GROK_IMAGE_MODELS = [GROK_2_IMAGE.name] as const
+export const GROK_IMAGE_MODELS = [
+  GROK_2_IMAGE.name,
+  GROK_IMAGINE_IMAGE.name,
+  GROK_IMAGINE_IMAGE_QUALITY.name,
+] as const
 
 // xAI's `/v1/tts` endpoint is endpoint-addressed and does not take a `model`
 // parameter. This synthetic identifier satisfies the SDK's `TTSOptions.model`
diff --git a/packages/ai-grok/tests/grok-adapter.test.ts b/packages/ai-grok/tests/grok-adapter.test.ts
index cf148c3e1..85913339d 100644
--- a/packages/ai-grok/tests/grok-adapter.test.ts
+++ b/packages/ai-grok/tests/grok-adapter.test.ts
@@ -189,6 +189,223 @@ describe('Grok adapters', () => {
         'XAI_API_KEY is required',
       )
     })
+
+    it('maps the size template to aspect_ratio/resolution for imagine models', async () => {
+      const adapter = createGrokImage('grok-imagine-image', 'test-api-key')
+      const mockGenerate = vi.fn().mockResolvedValue({
+        data: [{ url: 'https://example.com/out.png' }],
+      })
+      ;(adapter as any).client = { images: { generate: mockGenerate } }
+
+      await adapter.generateImages({
+        model: 'grok-imagine-image',
+        prompt: 'A skyline',
+        size: '16:9_2k',
+        logger: testLogger,
+      })
+
+      expect(mockGenerate).toHaveBeenCalledWith(
+        expect.objectContaining({
+          model: 'grok-imagine-image',
+          aspect_ratio: '16:9',
+          resolution: '2k',
+        }),
+      )
+      expect(mockGenerate.mock.calls[0]![0]).not.toHaveProperty('size')
+    })
+  })
+
+  describe('Image adapter — image prompt parts (Imagine edits endpoint)', () => {
+    const editResponse = (body: Record<string, unknown>, ok = true) =>
+      vi.fn().mockResolvedValue({
+        ok,
+        status: ok ? 200 : 422,
+        statusText: ok ? 'OK' : 'Unprocessable Entity',
+        json: () => Promise.resolve(body),
+        text: () => Promise.resolve(JSON.stringify(body)),
+      })
+
+    beforeEach(() => {
+      vi.unstubAllGlobals()
+    })
+
+    it('routes a single image part to POST /v1/images/edits with the prompt sent verbatim', async () => {
+      const mockFetch = editResponse({
+        data: [{ url: 'https://example.com/edited.png' }],
+      })
+      vi.stubGlobal('fetch', mockFetch)
+
+      const adapter = createGrokImage('grok-imagine-image', 'test-api-key')
+      const result = await adapter.generateImages({
+        model: 'grok-imagine-image',
+        prompt: [
+          { type: 'text', content: 'Make it a pencil sketch' },
+          {
+            type: 'image',
+            source: { type: 'url', value: 'https://example.com/source.png' },
+          },
+        ],
+        logger: testLogger,
+      })
+
+      expect(mockFetch).toHaveBeenCalledTimes(1)
+      const [url, init] = mockFetch.mock.calls[0]!
+      expect(url).toBe('https://api.x.ai/v1/images/edits')
+      expect(init.headers.Authorization).toBe('Bearer test-api-key')
+      expect(JSON.parse(init.body)).toMatchObject({
+        model: 'grok-imagine-image',
+        prompt: 'Make it a pencil sketch',
+        image: { url: 'https://example.com/source.png' },
+      })
+      expect(result.images).toEqual([{ url: 'https://example.com/edited.png' }])
+    })
+
+    it('flattens interleaved text verbatim — no markers are injected', async () => {
+      const mockFetch = editResponse({ data: [{ b64_json: 'aGVsbG8=' }] })
+      vi.stubGlobal('fetch', mockFetch)
+
+      const adapter = createGrokImage('grok-imagine-image', 'test-api-key')
+      await adapter.generateImages({
+        model: 'grok-imagine-image',
+        prompt: [
+          { type: 'text', content: 'Not like' },
+          {
+            type: 'image',
+            source: { type: 'url', value: 'https://example.com/bad.png' },
+          },
+          { type: 'text', content: 'more like' },
+          {
+            type: 'image',
+            source: { type: 'url', value: 'https://example.com/good.png' },
+          },
+        ],
+        logger: testLogger,
+      })
+
+      const body = JSON.parse(mockFetch.mock.calls[0]![1].body)
+      expect(body.prompt).toBe('Not like\n\nmore like')
+      expect(body.images).toEqual([
+        { url: 'https://example.com/bad.png' },
+        { url: 'https://example.com/good.png' },
+      ])
+    })
+
+    it('passes user-written referencing text through verbatim, sends images[] and maps size', async () => {
+      const mockFetch = editResponse({ data: [{ b64_json: 'aGVsbG8=' }] })
+      vi.stubGlobal('fetch', mockFetch)
+
+      const adapter = createGrokImage(
+        'grok-imagine-image-quality',
+        'test-api-key',
+      )
+      const result = await adapter.generateImages({
+        model: 'grok-imagine-image-quality',
+        prompt: [
+          { type: 'text', content: 'Put <IMAGE_0> in the style of <IMAGE_1>' },
+          {
+            type: 'image',
+            source: { type: 'url', value: 'https://example.com/product.png' },
+          },
+          {
+            type: 'image',
+            source: { type: 'data', value: 'c3R5bGU=', mimeType: 'image/png' },
+          },
+        ],
+        size: '1:1',
+        logger: testLogger,
+      })
+
+      const body = JSON.parse(mockFetch.mock.calls[0]![1].body)
+      expect(body.prompt).toBe('Put <IMAGE_0> in the style of <IMAGE_1>')
+      expect(body.images).toEqual([
+        { url: 'https://example.com/product.png' },
+        { url: 'data:image/png;base64,c3R5bGU=' },
+      ])
+      expect(body.image).toBeUndefined()
+      expect(body.aspect_ratio).toBe('1:1')
+      expect(result.images).toEqual([{ b64Json: 'aGVsbG8=' }])
+    })
+
+    it('throws for image prompt parts on the legacy grok-2 image model', async () => {
+      const adapter = createGrokImage('grok-2-image-1212', 'test-api-key')
+
+      await expect(
+        adapter.generateImages({
+          model: 'grok-2-image-1212',
+          prompt: [
+            { type: 'text', content: 'Edit this' },
+            {
+              type: 'image',
+              source: { type: 'url', value: 'https://example.com/a.png' },
+            },
+          ],
+          logger: testLogger,
+        }),
+      ).rejects.toThrow(/does not support image prompt parts/)
+    })
+
+    it('throws for more than 3 source images', async () => {
+      const adapter = createGrokImage('grok-imagine-image', 'test-api-key')
+      const part = {
+        type: 'image' as const,
+        source: { type: 'url' as const, value: 'https://example.com/a.png' },
+      }
+
+      await expect(
+        adapter.generateImages({
+          model: 'grok-imagine-image',
+          prompt: [
+            { type: 'text', content: 'Combine these' },
+            part,
+            part,
+            part,
+            part,
+          ],
+          logger: testLogger,
+        }),
+      ).rejects.toThrow(/at most 3 source images/)
+    })
+
+    it('throws for mask/control roles (no Imagine API equivalent)', async () => {
+      const adapter = createGrokImage('grok-imagine-image', 'test-api-key')
+
+      await expect(
+        adapter.generateImages({
+          model: 'grok-imagine-image',
+          prompt: [
+            { type: 'text', content: 'Inpaint' },
+            {
+              type: 'image',
+              source: { type: 'url', value: 'https://example.com/m.png' },
+              metadata: { role: 'mask' },
+            },
+          ],
+          logger: testLogger,
+        }),
+      ).rejects.toThrow(/no mask input/)
+    })
+
+    it('throws with response detail on a failed edit request', async () => {
+      vi.stubGlobal(
+        'fetch',
+        editResponse({ error: 'bad image' }, /* ok */ false),
+      )
+
+      const adapter = createGrokImage('grok-imagine-image', 'test-api-key')
+      await expect(
+        adapter.generateImages({
+          model: 'grok-imagine-image',
+          prompt: [
+            { type: 'text', content: 'Edit' },
+            {
+              type: 'image',
+              source: { type: 'url', value: 'https://example.com/a.png' },
+            },
+          ],
+          logger: testLogger,
+        }),
+      ).rejects.toThrow(/image edit request failed \(422/)
+    })
   })
 
   describe('Summarize adapter', () => {
diff --git a/packages/ai-openai/src/adapters/image.ts b/packages/ai-openai/src/adapters/image.ts
index 8e980b3d1..d11a67b67 100644
--- a/packages/ai-openai/src/adapters/image.ts
+++ b/packages/ai-openai/src/adapters/image.ts
@@ -1,9 +1,11 @@
 import OpenAI from 'openai'
+import { resolveMediaPrompt } from '@tanstack/ai'
 import { BaseImageAdapter } from '@tanstack/ai/adapters'
 import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
 import { buildImagesUsage } from '@tanstack/openai-base'
 import { generateId } from '@tanstack/ai-utils'
 import { getOpenAIApiKeyFromEnv } from '../utils/client'
+import { imagePartToFile } from '../image/image-input-to-file'
 import {
   validateImageSize,
   validateNumberOfImages,
@@ -13,16 +15,29 @@ import type {
   GeneratedImage,
   ImageGenerationOptions,
   ImageGenerationResult,
+  ImagePart,
+  MediaInputMetadata,
 } from '@tanstack/ai'
 import type OpenAI_SDK from 'openai'
 import type { OpenAIImageModel } from '../model-meta'
 import type {
+  OpenAIImageModelInputModalitiesByName,
   OpenAIImageModelProviderOptionsByName,
   OpenAIImageModelSizeByName,
   OpenAIImageProviderOptions,
 } from '../image/image-provider-options'
 import type { OpenAIClientConfig } from '../utils/client'
 
+// Per OpenAI docs: dall-e-2 accepts 1 image to `images.edit()`; the
+// gpt-image models accept up to 16; dall-e-3 does not support edit at all.
+const EDIT_MAX_IMAGES: Record<OpenAIImageModel, number> = {
+  'dall-e-2': 1,
+  'gpt-image-1': 16,
+  'gpt-image-1-mini': 16,
+  'gpt-image-2': 16,
+  'dall-e-3': 0,
+}
+
 /**
  * Configuration for OpenAI image adapter
  */
@@ -45,7 +60,8 @@ export class OpenAIImageAdapter<
   TModel,
   OpenAIImageProviderOptions,
   OpenAIImageModelProviderOptionsByName,
-  OpenAIImageModelSizeByName
+  OpenAIImageModelSizeByName,
+  OpenAIImageModelInputModalitiesByName
 > {
   override readonly kind = 'image' as const
   readonly name = 'openai' as const
@@ -60,12 +76,38 @@ export class OpenAIImageAdapter<
   async generateImages(
     options: ImageGenerationOptions<OpenAIImageProviderOptions>,
   ): Promise<ImageGenerationResult> {
-    const { model, prompt, numberOfImages, size, modelOptions } = options
+    const { model, numberOfImages, size, modelOptions } = options
+
+    const resolved = resolveMediaPrompt(options.prompt)
+    const prompt = resolved.text
 
     validatePrompt({ prompt, model })
     validateImageSize(model, size)
     validateNumberOfImages(model, numberOfImages)
 
+    if (resolved.videos.length > 0) {
+      throw new Error(
+        `${this.name}.generateImages does not support video prompt parts (model: ${model}).`,
+      )
+    }
+    if (resolved.audios.length > 0) {
+      throw new Error(
+        `${this.name}.generateImages does not support audio prompt parts (model: ${model}).`,
+      )
+    }
+
+    if (resolved.images.length > 0) {
+      return this.editImages({
+        model: model as OpenAIImageModel,
+        prompt,
+        numberOfImages,
+        size,
+        modelOptions,
+        imageInputs: resolved.images,
+        logger: options.logger,
+      })
+    }
+
     // With exactOptionalPropertyTypes, vendor SDK request shapes reject
     // `T | undefined` in optional fields. Build the request incrementally and
     // only set `size` when it's actually defined.
@@ -108,6 +150,12 @@ export class OpenAIImageAdapter<
         },
       )
 
+      // Surface empty responses (e.g. moderation blocks returning items with
+      // neither b64_json nor url) instead of resolving to `{ images: [] }`.
+      if (images.length === 0) {
+        throw new Error(`${this.name}: image response contained no images`)
+      }
+
       // `ImageGenerationResult.usage` is `usage?: TokenUsage` without
       // `| undefined`, so spread the field only when the model reported usage.
       const usage = buildImagesUsage(response.usage)
@@ -128,6 +176,132 @@ export class OpenAIImageAdapter<
       throw error
     }
   }
+
+  /**
+   * Image-conditioned generation via OpenAI's `images.edit()` endpoint.
+   * dall-e-2 accepts 1 input image; gpt-image-2 / gpt-image-1 /
+   * gpt-image-1-mini accept up to 16; dall-e-3 rejects entirely. A part with
+   * `metadata.role === 'mask'` is routed to the SDK's `mask` field (PNG with
+   * alpha channel).
+   */
+  private async editImages(args: {
+    model: OpenAIImageModel
+    prompt: string
+    numberOfImages?: number
+    size?: string
+    modelOptions?: OpenAIImageProviderOptions
+    imageInputs: ReadonlyArray<ImagePart<MediaInputMetadata>>
+    logger: ImageGenerationOptions<OpenAIImageProviderOptions>['logger']
+  }): Promise<ImageGenerationResult> {
+    const { model, prompt, numberOfImages, size, modelOptions, logger } = args
+    const maxImages = EDIT_MAX_IMAGES[model]
+    if (maxImages === 0) {
+      throw new Error(
+        `${this.name}: model "${model}" does not support image prompt parts. ` +
+          `Use gpt-image-2, gpt-image-1, gpt-image-1-mini, or dall-e-2 for image-conditioned generation.`,
+      )
+    }
+
+    const maskParts = args.imageInputs.filter(
+      (part) => part.metadata?.role === 'mask',
+    )
+    const sourceParts = args.imageInputs.filter(
+      (part) => part.metadata?.role !== 'mask',
+    )
+
+    if (maskParts.length > 1) {
+      throw new Error(
+        `${this.name}: only one input with metadata.role === 'mask' is supported per request.`,
+      )
+    }
+    if (sourceParts.length === 0) {
+      throw new Error(
+        `${this.name}: the prompt contained only mask image parts; at least one source image is required.`,
+      )
+    }
+    if (sourceParts.length > maxImages) {
+      throw new Error(
+        `${this.name}: model "${model}" accepts at most ${maxImages} source image(s); received ${sourceParts.length}.`,
+      )
+    }
+
+    const sourceFiles = await Promise.all(
+      sourceParts.map((part, i) => imagePartToFile(part, `source-${i}`)),
+    )
+    const [firstSourceFile] = sourceFiles
+    const maskFile = maskParts[0]
+      ? await imagePartToFile(maskParts[0], 'mask')
+      : undefined
+
+    // `modelOptions` is typed across all four image models (including dall-e-3's
+    // `quality: 'hd' | 'standard'` which isn't valid for edit). dall-e-3 has
+    // already been rejected above, so any remaining quality value is valid for
+    // the edit endpoint — cast the spread to clear the union mismatch.
+    const request: OpenAI_SDK.Images.ImageEditParamsNonStreaming = {
+      model,
+      prompt,
+      image:
+        firstSourceFile && sourceFiles.length === 1
+          ? firstSourceFile
+          : sourceFiles,
+      n: numberOfImages ?? 1,
+      stream: false,
+      ...((modelOptions ??
+        {}) as Partial<OpenAI_SDK.Images.ImageEditParamsNonStreaming>),
+    }
+    if (size !== undefined) {
+      request.size = size
+    }
+    if (maskFile) {
+      request.mask = maskFile
+    }
+
+    try {
+      logger.request(
+        `activity=imageEdit provider=${this.name} model=${model} n=${request.n ?? 1} size=${request.size ?? 'default'} sources=${sourceFiles.length}${maskFile ? ' mask' : ''}`,
+        { provider: this.name, model },
+      )
+      const response = await this.client.images.edit(request)
+
+      const images: Array<GeneratedImage> = (response.data ?? []).flatMap(
+        (item): Array<GeneratedImage> => {
+          const revisedPromptField =
+            item.revised_prompt !== undefined
+              ? { revisedPrompt: item.revised_prompt }
+              : {}
+          if (item.b64_json) {
+            return [{ b64Json: item.b64_json, ...revisedPromptField }]
+          }
+          if (item.url) {
+            return [{ url: item.url, ...revisedPromptField }]
+          }
+          return []
+        },
+      )
+
+      // Surface empty responses (e.g. moderation blocks returning items with
+      // neither b64_json nor url) instead of resolving to `{ images: [] }`.
+      if (images.length === 0) {
+        throw new Error(`${this.name}: image edit response contained no images`)
+      }
+
+      return {
+        id: generateId(this.name),
+        model,
+        images,
+        ...(() => {
+          const usage = buildImagesUsage(response.usage)
+          return usage ? { usage } : {}
+        })(),
+      }
+    } catch (error: unknown) {
+      logger.errors(`${this.name}.editImages fatal`, {
+        error: toRunErrorPayload(error, `${this.name}.editImages failed`),
+        source: `${this.name}.editImages`,
+      })
+      throw error
+    }
+  }
 }
 
 /**
diff --git a/packages/ai-openai/src/adapters/video.ts b/packages/ai-openai/src/adapters/video.ts
index 6bf4652f8..15bb2a733 100644
--- a/packages/ai-openai/src/adapters/video.ts
+++ b/packages/ai-openai/src/adapters/video.ts
@@ -1,8 +1,10 @@
 import OpenAI from 'openai'
+import { resolveMediaPrompt } from '@tanstack/ai'
 import { BaseVideoAdapter } from '@tanstack/ai/adapters'
 import { toRunErrorPayload } from '@tanstack/ai/adapter-internals'
 import { arrayBufferToBase64 } from '@tanstack/ai-utils'
 import { getOpenAIApiKeyFromEnv } from '../utils/client'
+import { imagePartToFile } from '../image/image-input-to-file'
 import {
   toApiSeconds,
   validateVideoSeconds,
@@ -17,6 +19,7 @@ import type {
 import type OpenAI_SDK from 'openai'
 import type { OpenAIVideoModel } from '../model-meta'
 import type {
+  OpenAIVideoModelInputModalitiesByName,
   OpenAIVideoModelProviderOptionsByName,
   OpenAIVideoModelSizeByName,
   OpenAIVideoProviderOptions,
@@ -67,7 +70,8 @@ export class OpenAIVideoAdapter<
   TModel,
   OpenAIVideoProviderOptions,
   OpenAIVideoModelProviderOptionsByName,
-  OpenAIVideoModelSizeByName
+  OpenAIVideoModelSizeByName,
+  OpenAIVideoModelInputModalitiesByName
 > {
   readonly name = 'openai' as const
 
@@ -92,9 +96,36 @@ export class OpenAIVideoAdapter<
     const seconds = duration ?? modelOptions?.seconds
     validateVideoSeconds(model, seconds)
 
+    const resolved = resolveMediaPrompt(options.prompt)
+
+    if (resolved.videos.length > 0) {
+      throw new Error(
+        `${this.name}.createVideoJob does not support video prompt parts (model: ${model}).`,
+      )
+    }
+    if (resolved.audios.length > 0) {
+      throw new Error(
+        `${this.name}.createVideoJob does not support audio prompt parts (model: ${model}).`,
+      )
+    }
+    if (resolved.images.length > 1) {
+      throw new Error(
+        `${this.name}: Sora accepts at most one input_reference image; received ${resolved.images.length}.`,
+      )
+    }
+
     const request: OpenAI_SDK.Videos.VideoCreateParams = {
       model,
-      prompt: options.prompt,
+      prompt: resolved.text,
+    }
+    const [inputReference] = resolved.images
+    if (inputReference) {
+      // Sora's `input_reference` is a single Uploadable; convert TanStack
+      // ImagePart (URL or base64) → File before handing it to the SDK.
+      request.input_reference = await imagePartToFile(
+        inputReference,
+        'input-reference',
+      )
     }
     // `VideoCreateParams.size` is `size?: VideoSize` (no `| undefined`), so we
     // narrow before assignment instead of casting from a `T | undefined` source.
diff --git a/packages/ai-openai/src/image/image-input-to-file.ts b/packages/ai-openai/src/image/image-input-to-file.ts
new file mode 100644
index 000000000..2074496fd
--- /dev/null
+++ b/packages/ai-openai/src/image/image-input-to-file.ts
@@ -0,0 +1,70 @@
+import { base64ToArrayBuffer } from '@tanstack/ai-utils'
+import type { ImagePart, MediaInputMetadata } from '@tanstack/ai'
+
+const DEFAULT_MIME = 'image/png'
+const MIME_TO_EXT: Record<string, string> = {
+  'image/png': 'png',
+  'image/jpeg': 'jpg',
+  'image/jpg': 'jpg',
+  'image/webp': 'webp',
+  'image/gif': 'gif',
+}
+
+function extForMime(mimeType: string): string {
+  return MIME_TO_EXT[mimeType] ?? mimeType.split('/')[1] ?? 'png'
+}
+
+function ensureFileSupport(): void {
+  if (typeof File === 'undefined') {
+    throw new Error(
+      '`File` is not available in this environment. ' +
+        'Image-conditioned generation requires Node 20+ or a browser context.',
+    )
+  }
+}
+
+/**
+ * Convert a TanStack `ImagePart` into an OpenAI-compatible `File`.
+ *
+ * - `source.type === 'data'`: decode base64 → Buffer → File.
+ * - `source.type === 'url'`: fetch the URL (or parse data: URI) → File.
+ *
+ * The mime type comes from the source when available, else inferred from the
+ * URL extension, else `image/png`.
+ */
+export async function imagePartToFile(
+  part: ImagePart<MediaInputMetadata>,
+  fallbackName: string,
+): Promise<File> {
+  ensureFileSupport()
+
+  if (part.source.type === 'data') {
+    const mimeType = part.source.mimeType || DEFAULT_MIME
+    const bytes = base64ToArrayBuffer(part.source.value)
+    return new File([bytes], `${fallbackName}.${extForMime(mimeType)}`, {
+      type: mimeType,
+    })
+  }
+
+  // URL source — also handles data: URIs uniformly via fetch().
+  const response = await fetch(part.source.value)
+  if (!response.ok) {
+    throw new Error(
+      `Failed to fetch image input (${response.status} ${response.statusText}): ${part.source.value}`,
+    )
+  }
+  const blob = await response.blob()
+  const mimeType =
+    part.source.mimeType || blob.type || inferMimeFromUrl(part.source.value)
+  return new File([blob], `${fallbackName}.${extForMime(mimeType)}`, {
+    type: mimeType,
+  })
+}
+
+function inferMimeFromUrl(url: string): string {
+  const match = url.match(/\.(png|jpe?g|webp|gif)(?:\?|#|$)/i)
+  if (!match || !match[1]) return DEFAULT_MIME
+  const ext = match[1].toLowerCase()
+  if (ext === 'jpg' || ext === 'jpeg') return 'image/jpeg'
+  return `image/${ext}`
+}
diff --git a/packages/ai-openai/src/image/image-provider-options.ts b/packages/ai-openai/src/image/image-provider-options.ts
index d6e221ec3..729b40234 100644
--- a/packages/ai-openai/src/image/image-provider-options.ts
+++ b/packages/ai-openai/src/image/image-provider-options.ts
@@ -199,6 +199,19 @@ export type OpenAIImageModelSizeByName = {
   'dall-e-2': DallE2Size
 }
 
+/**
+ * Per-model prompt input modalities. Models with `images.edit()` support
+ * (gpt-image family, dall-e-2) accept image parts in the prompt;
+ * dall-e-3 has no edit endpoint, so its prompt is text-only at compile time.
+ */
+export type OpenAIImageModelInputModalitiesByName = {
+  'gpt-image-2': readonly ['image']
+  'gpt-image-1': readonly ['image']
+  'gpt-image-1-mini': readonly ['image']
+  'dall-e-3': readonly []
+  'dall-e-2': readonly ['image']
+}
+
 /**
  * Internal options interface for validation
  */
diff --git a/packages/ai-openai/src/video/video-provider-options.ts b/packages/ai-openai/src/video/video-provider-options.ts
index b0f337039..837c2c7b2 100644
--- a/packages/ai-openai/src/video/video-provider-options.ts
+++ b/packages/ai-openai/src/video/video-provider-options.ts
@@ -66,6 +66,17 @@ export type OpenAIVideoModelSizeByName = {
   'sora-2-pro': OpenAIVideoSize
 }
 
+/**
+ * Per-model prompt input modalities. Sora models accept a single image part
+ * in the prompt, mapped to the API's `input_reference` field.
+ *
+ * @experimental Video generation is an experimental feature and may change.
+ */
+export type OpenAIVideoModelInputModalitiesByName = {
+  'sora-2': readonly ['image']
+  'sora-2-pro': readonly ['image']
+}
+
 /**
  * Validate video size for a given model.
  *
diff --git a/packages/ai-openai/tests/image-adapter.test.ts b/packages/ai-openai/tests/image-adapter.test.ts
index 6944c3e02..ffae82297 100644
--- a/packages/ai-openai/tests/image-adapter.test.ts
+++ b/packages/ai-openai/tests/image-adapter.test.ts
@@ -25,6 +25,9 @@ class TestOpenAIImageAdapter<
   spyOnImagesGenerate() {
     return vi.spyOn(this.client.images, 'generate')
   }
+  spyOnImagesEdit() {
+    return vi.spyOn(this.client.images, 'edit')
+  }
 }
 
 describe('OpenAI Image Adapter', () => {
@@ -205,6 +208,24 @@ describe('OpenAI Image Adapter', () => {
       })
     })
 
+    it('throws when the response contains no usable images', async () => {
+      const adapter = new TestOpenAIImageAdapter(
+        { apiKey: 'test-api-key' },
+        'gpt-image-1',
+      )
+      adapter
+        .spyOnImagesGenerate()
+        .mockResolvedValueOnce({ created: 0, data: [{}] })
+
+      await expect(
+        adapter.generateImages({
+          model: 'gpt-image-1',
+          prompt: 'A cat',
+          logger: testLogger,
+        }),
+      ).rejects.toThrow(/image response contained no images/)
+    })
+
     it('generates a unique ID for each response', async () => {
       const mockResponse: OpenAI.Images.ImagesResponse = {
         created: 0,
@@ -234,4 +255,188 @@ describe('OpenAI Image Adapter', () => {
       expect(result2.id).toMatch(/^openai-/)
     })
   })
+
+  describe('multimodal prompt (image-conditioned generation)', () => {
+    const imagesEditResponse: OpenAI.Images.ImagesResponse = {
+      created: 0,
+      data: [{ b64_json: 'edited-base64' }],
+    }
+
+    it('routes to images.edit() for gpt-image-1 when the prompt has image parts', async () => {
+      const adapter = new TestOpenAIImageAdapter(
+        { apiKey: 'test-api-key' },
+        'gpt-image-1',
+      )
+      const editSpy = adapter
+        .spyOnImagesEdit()
+        .mockResolvedValueOnce(imagesEditResponse)
+      const generateSpy = adapter.spyOnImagesGenerate()
+
+      const result = await adapter.generateImages({
+        model: 'gpt-image-1',
+        prompt: [
+          { type: 'text', content: 'Make it cinematic' },
+          {
+            type: 'image',
+            source: {
+              type: 'data',
+              value: 'aGVsbG8=',
+              mimeType: 'image/png',
+            },
+          },
+        ],
+        logger: testLogger,
+      })
+
+      expect(generateSpy).not.toHaveBeenCalled()
+      expect(editSpy).toHaveBeenCalledTimes(1)
+      const editArgs = editSpy.mock.calls[0]![0]
+      expect(editArgs.model).toBe('gpt-image-1')
+      expect(editArgs.prompt).toBe('Make it cinematic')
+      expect(editArgs.image).toBeInstanceOf(File)
+      expect(result.images[0]!.b64Json).toBe('edited-base64')
+    })
+
+    it('rejects dall-e-3 with a clear error when the prompt has image parts', async () => {
+      const adapter = new TestOpenAIImageAdapter(
+        { apiKey: 'test-api-key' },
+        'dall-e-3',
+      )
+
+      await expect(
+        adapter.generateImages({
+          model: 'dall-e-3',
+          prompt: [
+            { type: 'text', content: 'edit' },
+            {
+              type: 'image',
+              source: { type: 'data', value: 'aGk=', mimeType: 'image/png' },
+            },
+          ],
+          logger: testLogger,
+        }),
+      ).rejects.toThrow(/does not support image prompt parts/)
+    })
+
+    it('rejects dall-e-2 when more than one source image is provided', async () => {
+      const adapter = new TestOpenAIImageAdapter(
+        { apiKey: 'test-api-key' },
+        'dall-e-2',
+      )
+
+      await expect(
+        adapter.generateImages({
+          model: 'dall-e-2',
+          prompt: [
+            { type: 'text', content: 'edit' },
+            {
+              type: 'image',
+              source: { type: 'data', value: 'aGk=', mimeType: 'image/png' },
+            },
+            {
+              type: 'image',
+              source: {
+                type: 'data',
+                value: 'YnllCg==',
+                mimeType: 'image/png',
+              },
+            },
+          ],
+          logger: testLogger,
+        }),
+      ).rejects.toThrow(/at most 1 source image/)
+    })
+
+    it('routes metadata.role==="mask" to the mask param', async () => {
+      const adapter = new TestOpenAIImageAdapter(
+        { apiKey: 'test-api-key' },
+        'gpt-image-1',
+      )
+      const editSpy = adapter
+        .spyOnImagesEdit()
+        .mockResolvedValueOnce(imagesEditResponse)
+
+      await adapter.generateImages({
+        model: 'gpt-image-1',
+        prompt: [
+          { type: 'text', content: 'replace masked region' },
+          {
+            type: 'image',
+            source: { type: 'data', value: 'aGk=', mimeType: 'image/png' },
+          },
+          {
+            type: 'image',
+            source: { type: 'data', value: 'bWFzaw==', mimeType: 'image/png' },
+            metadata: { role: 'mask' },
+          },
+        ],
+        logger: testLogger,
+      })
+
+      const editArgs = editSpy.mock.calls[0]![0]
+      expect(editArgs.mask).toBeInstanceOf(File)
+      expect(editArgs.image).toBeInstanceOf(File)
+    })
+
+    it('throws when the edit response contains no usable images', async () => {
+      const adapter = new TestOpenAIImageAdapter(
+        { apiKey: 'test-api-key' },
+        'gpt-image-1',
+      )
+      // Items with neither b64_json nor url (e.g. moderation blocks) must
+      // surface as an error, not resolve to `{ images: [] }`.
+      adapter
+        .spyOnImagesEdit()
+        .mockResolvedValueOnce({ created: 0, data: [{}] })
+
+      await expect(
+        adapter.generateImages({
+          model: 'gpt-image-1',
+          prompt: [
+            { type: 'text', content: 'edit' },
+            {
+              type: 'image',
+              source: { type: 'data', value: 'aGk=', mimeType: 'image/png' },
+            },
+          ],
+          logger: testLogger,
+        }),
+      ).rejects.toThrow(/image edit response contained no images/)
+    })
+
+    it('rejects video or audio prompt parts', async () => {
+      const adapter = new TestOpenAIImageAdapter(
+        { apiKey: 'test-api-key' },
+        'gpt-image-1',
+      )
+
+      await expect(
+        adapter.generateImages({
+          model: 'gpt-image-1',
+          prompt: [
+            { type: 'text', content: 'x' },
+            {
+              type: 'video',
+              source: { type: 'url', value: 'https://example.com/v.mp4' },
+            },
+          ],
+          logger: testLogger,
+        }),
+      ).rejects.toThrow(/video prompt parts/)
+
+      await expect(
+        adapter.generateImages({
+          model: 'gpt-image-1',
+          prompt: [
+            { type: 'text', content: 'x' },
+            {
+              type: 'audio',
+              source: { type: 'url', value: 'https://example.com/a.mp3' },
+            },
+          ],
+          logger: testLogger,
+        }),
+      ).rejects.toThrow(/audio prompt parts/)
+    })
+  })
 })
diff --git a/packages/ai-openai/tests/video-adapter.test.ts b/packages/ai-openai/tests/video-adapter.test.ts
new file mode 100644
index 000000000..5d28241a8
--- /dev/null
+++ b/packages/ai-openai/tests/video-adapter.test.ts
@@ -0,0 +1,114 @@
+import { describe, expect, it, vi } from 'vitest'
+import { resolveDebugOption } from '@tanstack/ai/adapter-internals'
+import { OpenAIVideoAdapter, createOpenaiVideo } from '../src/adapters/video'
+
+const testLogger = resolveDebugOption(false)
+
+/**
+ * Replace the SDK's `videos` client with a mock. `createVideoJob` reaches the
+ * SDK exclusively through `getVideosClient()`, so swapping the `videos`
+ * resource is enough; the adapter's own request assembly stays real.
+ */
+function mockedAdapter() {
+  const adapter = createOpenaiVideo('sora-2', 'test-api-key')
+  const mockCreate = vi.fn().mockResolvedValue({ id: 'video-job-1' })
+  ;(adapter as unknown as { client: { videos: unknown } }).client = {
+    videos: { create: mockCreate },
+  }
+  return { adapter, mockCreate }
+}
+
+describe('OpenAI Video Adapter', () => {
+  it('creates an adapter with the provided API key', () => {
+    const adapter = createOpenaiVideo('sora-2', 'test-api-key')
+    expect(adapter).toBeInstanceOf(OpenAIVideoAdapter)
+    expect(adapter.name).toBe('openai')
+    expect(adapter.model).toBe('sora-2')
+  })
+
+  describe('createVideoJob with a multimodal prompt', () => {
+    it('uploads a single image part as input_reference with verbatim prompt text', async () => {
+      const { adapter, mockCreate } = mockedAdapter()
+
+      const result = await adapter.createVideoJob({
+        model: 'sora-2',
+        prompt: [
+          { type: 'text', content: 'Slow cinematic push-in' },
+          {
+            type: 'image',
+            source: { type: 'data', value: 'aGk=', mimeType: 'image/png' },
+          },
+        ],
+        logger: testLogger,
+      })
+
+      expect(mockCreate).toHaveBeenCalledTimes(1)
+      const request = mockCreate.mock.calls[0]![0]
+      expect(request.model).toBe('sora-2')
+      expect(request.prompt).toBe('Slow cinematic push-in')
+      expect(request.input_reference).toBeInstanceOf(File)
+      expect(result.jobId).toBe('video-job-1')
+      expect(result.model).toBe('sora-2')
+    })
+
+    it('throws when more than one image part is provided', async () => {
+      const { adapter, mockCreate } = mockedAdapter()
+
+      await expect(
+        adapter.createVideoJob({
+          model: 'sora-2',
+          prompt: [
+            { type: 'text', content: 'x' },
+            {
+              type: 'image',
+              source: { type: 'data', value: 'aGk=', mimeType: 'image/png' },
+            },
+            {
+              type: 'image',
+              source: {
+                type: 'data',
+                value: 'YnllCg==',
+                mimeType: 'image/png',
+              },
+            },
+          ],
+          logger: testLogger,
+        }),
+      ).rejects.toThrow(/at most one input_reference image/)
+      expect(mockCreate).not.toHaveBeenCalled()
+    })
+
+    it('rejects video and audio prompt parts', async () => {
+      const { adapter, mockCreate } = mockedAdapter()
+
+      await expect(
+        adapter.createVideoJob({
+          model: 'sora-2',
+          prompt: [
+            { type: 'text', content: 'x' },
+            {
+              type: 'video',
+              source: { type: 'url', value: 'https://example.com/v.mp4' },
+            },
+          ],
+          logger: testLogger,
+        }),
+      ).rejects.toThrow(/video prompt parts/)
+
+      await expect(
+        adapter.createVideoJob({
+          model: 'sora-2',
+          prompt: [
+            { type: 'text', content: 'x' },
+            {
+              type: 'audio',
+              source: { type: 'url', value: 'https://example.com/a.mp3' },
+            },
+          ],
+          logger: testLogger,
+        }),
+      ).rejects.toThrow(/audio prompt parts/)
+      expect(mockCreate).not.toHaveBeenCalled()
+    })
+  })
+})
diff --git a/packages/ai-openrouter/src/adapters/image.ts b/packages/ai-openrouter/src/adapters/image.ts
index 4384713f2..ced370e54 100644
--- a/packages/ai-openrouter/src/adapters/image.ts
+++ b/packages/ai-openrouter/src/adapters/image.ts
@@ -1,4 +1,5 @@
 import { OpenRouter } from '@openrouter/sdk'
+import { resolveMediaPrompt } from '@tanstack/ai'
 import { BaseImageAdapter } from '@tanstack/ai/adapters'
 import {
   getOpenRouterApiKeyFromEnv,
@@ -7,6 +8,7 @@ import {
 import { buildOpenRouterUsage } from '../usage'
 import type { OpenRouterClientConfig } from '../utils'
 import type {
+  OpenRouterImageModelInputModalitiesByName,
   OpenRouterImageModelProviderOptionsByName,
   OpenRouterImageModelSizeByName,
   OpenRouterImageProviderOptions,
@@ -15,6 +17,8 @@ import type {
   GeneratedImage,
   ImageGenerationOptions,
   ImageGenerationResult,
+  ImagePart,
+  MediaInputMetadata,
 } from '@tanstack/ai'
 import type { OPENROUTER_IMAGE_MODELS } from '../model-meta'
 import type { ChatResult } from '@openrouter/sdk/models'
@@ -40,13 +44,24 @@ const SIZE_TO_ASPECT_RATIO: Record<string, string> = {
   '1536x672': '21:9',
 }
 
+/**
+ * Convert a TanStack ImagePart into the URL string accepted by OpenRouter's
+ * `image_url` content parts: public URLs pass through, data sources become
+ * base64 data URIs.
+ */
+function imagePartToUrl(part: ImagePart<MediaInputMetadata>): string {
+  if (part.source.type === 'url') return part.source.value
+  return `data:${part.source.mimeType};base64,${part.source.value}`
+}
+
 export class OpenRouterImageAdapter<
   TModel extends OpenRouterImageModel,
 > extends BaseImageAdapter<
   TModel,
   OpenRouterImageProviderOptions,
   OpenRouterImageModelProviderOptionsByName,
-  OpenRouterImageModelSizeByName
+  OpenRouterImageModelSizeByName,
+  OpenRouterImageModelInputModalitiesByName
 > {
   override readonly kind = 'image' as const
   readonly name = 'openrouter' as const
@@ -65,11 +80,42 @@ export class OpenRouterImageAdapter<
   async generateImages(
     options: ImageGenerationOptions<OpenRouterImageProviderOptions>,
   ): Promise<ImageGenerationResult> {
-    const { model, prompt, numberOfImages, size, modelOptions, logger } =
-      options
+    const resolved = resolveMediaPrompt(options.prompt)
+
+    if (resolved.videos.length > 0 || resolved.audios.length > 0) {
+      throw new Error(
+        `openrouter.generateImages does not support video / audio prompt parts on model ${this.model}.`,
+      )
+    }
+
+    const { model, numberOfImages, size, modelOptions, logger } = options
     // Use provided aspect_ratio or derive from size
     const aspectRatio = size ? SIZE_TO_ASPECT_RATIO[size] : undefined
 
+    // Image-conditioned generation: map the prompt parts 1:1 onto
+    // chat-completions content parts, preserving the interleaved order —
+    // OpenRouter forwards them to the underlying image model (e.g. Gemini
+    // image models), where position is meaningful. Role hints carry no
+    // per-field semantics on this pathway.
+    type ContentItem =
+      | { type: 'text'; text: string }
+      | { type: 'image_url'; imageUrl: { url: string } }
+    const content =
+      resolved.images.length > 0
+        ? resolved.parts.flatMap((part): Array<ContentItem> => {
+            if (part.type === 'text') {
+              return [{ type: 'text', text: part.content }]
+            }
+            if (part.type === 'image') {
+              return [
+                { type: 'image_url', imageUrl: { url: imagePartToUrl(part) } },
+              ]
+            }
+            // Video / audio parts were rejected above.
+            return []
+          })
+        : resolved.text
+
     logger.request(
       `activity=generateImage provider=openrouter model=${this.model}`,
       {
@@ -84,7 +130,7 @@ export class OpenRouterImageAdapter<
         messages: [
           {
             role: 'user',
-            content: prompt,
+            content,
           },
         ],
         modalities: ['image'],
diff --git a/packages/ai-openrouter/src/image/image-provider-options.ts b/packages/ai-openrouter/src/image/image-provider-options.ts
index b8974368f..3c4c00a4a 100644
--- a/packages/ai-openrouter/src/image/image-provider-options.ts
+++ b/packages/ai-openrouter/src/image/image-provider-options.ts
@@ -36,3 +36,13 @@ export type OpenRouterImageModelSizeByName = {
     | '1344×768' // "16:9"
     | '1536×672' // "21:9"
 }
+
+/**
+ * Per-model prompt input modalities. OpenRouter routes image generation
+ * through the chat-completions surface where every listed image model
+ * (Gemini image family, GPT image family) accepts `image_url` content
+ * parts, so image-conditioned prompts are supported across the board.
+ */
+export type OpenRouterImageModelInputModalitiesByName = {
+  [K in (typeof OPENROUTER_IMAGE_MODELS)[number]]: readonly ['image']
+}
diff --git a/packages/ai-openrouter/tests/image-adapter.test.ts b/packages/ai-openrouter/tests/image-adapter.test.ts
index 536e47e7e..4f078fd33 100644
--- a/packages/ai-openrouter/tests/image-adapter.test.ts
+++ b/packages/ai-openrouter/tests/image-adapter.test.ts
@@ -242,6 +242,88 @@ describe('OpenRouter Image Adapter', () => {
     )
   })
 
+  it('maps image prompt parts onto content parts preserving interleaved order', async () => {
+    const mockResponse = createMockImageResponse([
+      { url: 'https://example.com/edited.png' },
+    ])
+
+    mockSend = vi.fn().mockResolvedValueOnce(mockResponse)
+
+    const adapter = createAdapter()
+
+    const result = await adapter.generateImages({
+      model: 'google/gemini-2.5-flash-image',
+      prompt: [
+        {
+          type: 'image',
+          source: { type: 'url', value: 'https://example.com/source.png' },
+        },
+        { type: 'text', content: 'Turn this into a cinematic product photo' },
+        {
+          type: 'image',
+          source: { type: 'data', value: 'c3R5bGU=', mimeType: 'image/png' },
+          metadata: { role: 'reference' },
+        },
+      ],
+      logger: testLogger,
+    })
+
+    const callArgs = mockSend.mock.calls[0]![0].chatRequest
+    expect(callArgs.messages).toEqual([
+      {
+        role: 'user',
+        content: [
+          {
+            type: 'image_url',
+            imageUrl: { url: 'https://example.com/source.png' },
+          },
+          { type: 'text', text: 'Turn this into a cinematic product photo' },
+          {
+            type: 'image_url',
+            imageUrl: { url: 'data:image/png;base64,c3R5bGU=' },
+          },
+        ],
+      },
+    ])
+    expect(result.images).toHaveLength(1)
+  })
+
+  it('keeps a plain string prompt when no image parts are given', async () => {
+    const mockResponse = createMockImageResponse([
+      { url: 'https://example.com/image.png' },
+    ])
+
+    mockSend = vi.fn().mockResolvedValueOnce(mockResponse)
+
+    const adapter = createAdapter()
+    await adapter.generateImages({
+      model: 'google/gemini-2.5-flash-image',
+      prompt: 'A plain prompt',
+      logger: testLogger,
+    })
+
+    const callArgs = mockSend.mock.calls[0]![0].chatRequest
+    expect(callArgs.messages[0].content).toBe('A plain prompt')
+  })
+
+  it('throws for video / audio prompt parts', async () => {
+    const adapter = createAdapter()
+
+    await expect(
+      adapter.generateImages({
+        model: 'google/gemini-2.5-flash-image',
+        prompt: [
+          { type: 'text', content: 'Test' },
+          {
+            type: 'video',
+            source: { type: 'url', value: 'https://example.com/v.mp4' },
+          },
+        ],
+        logger: testLogger,
+      }),
+    ).rejects.toThrow(/does not support video \/ audio prompt parts/)
+  })
+
   it('passes imageConfig correctly', async () => {
     const mockResponse = createMockImageResponse([
       { url: 'https://example.com/image.png' },
diff --git a/packages/ai/skills/ai-core/media-generation/SKILL.md b/packages/ai/skills/ai-core/media-generation/SKILL.md
index 09a552b73..1fe6922f2 100644
--- a/packages/ai/skills/ai-core/media-generation/SKILL.md
+++ b/packages/ai/skills/ai-core/media-generation/SKILL.md
@@ -189,6 +189,103 @@ Result shape: `ImageGenerationResult` with `images` array where each entry
 has `b64Json?`, `url?`, and `revisedPrompt?`. OpenAI image URLs expire
 after 1 hour -- download or display immediately.
 
+#### Image-conditioned generation: multimodal `prompt` parts
+
+Both `generateImage()` and `generateVideo()` accept the `prompt` either as
+a plain string or as an ordered array of content parts (`TextPart` /
+`ImagePart` / `VideoPart` / `AudioPart` — the same shapes used elsewhere in
+TanStack AI). Part order is meaningful: natively multimodal providers
+(Gemini, OpenRouter) receive parts in order; named-field providers (OpenAI,
+fal, xAI) extract media parts and flatten the text. Prompt text is always
+sent verbatim — to reference inputs from the prompt, write the provider's
+own syntax (fal `@Image1`, OpenAI "image 1" prose); the SDK never injects
+or rewrites markers. Each media part may carry an optional
+`metadata.role` hint that adapters use to route the part to the
+provider-specific field. The accepted part types are narrowed per model at
+compile time via the adapter's input-modality map.
+
+```typescript
+import { generateImage } from '@tanstack/ai'
+import { openaiImage } from '@tanstack/ai-openai'
+
+// Image-to-image (OpenAI gpt-image-2 / gpt-image-1, dall-e-2)
+await generateImage({
+  adapter: openaiImage('gpt-image-2'),
+  prompt: [
+    { type: 'text', content: 'Turn this into a cinematic product photo' },
+    { type: 'image', source: { type: 'url', value: 'https://…/product.png' } },
+  ],
+})
+
+// Multi-reference (up to 16 for gpt-image models; up to ~14 for Gemini native
+// — a provider limit, not enforced by the SDK)
+await generateImage({
+  adapter: openaiImage('gpt-image-2'),
+  prompt: [
+    { type: 'text', content: 'Apply the second image as style to the first' },
+    { type: 'image', source: { type: 'url', value: 'https://…/product.png' } },
+    { type: 'image', source: { type: 'url', value: 'https://…/style.png' } },
+  ],
+})
+
+// Inpaint via metadata.role === 'mask' (OpenAI gpt-image models, dall-e-2; fal mask_url)
+await generateImage({
+  adapter: openaiImage('gpt-image-2'),
+  prompt: [
+    { type: 'text', content: 'Replace the masked region with a tree' },
+    { type: 'image', source: { type: 'url', value: photoUrl } },
+    {
+      type: 'image',
+      source: { type: 'url', value: maskUrl },
+      metadata: { role: 'mask' },
+    },
+  ],
+})
+
+// Image-to-video (OpenAI Sora: single input_reference; fal: image_url + optional end_image_url)
+import { generateVideo } from '@tanstack/ai'
+import { falVideo } from '@tanstack/ai-fal'
+
+await generateVideo({
+  adapter: falVideo('fal-ai/kling-video/v3/pro/image-to-video'),
+  prompt: [
+    { type: 'image', source: { type: 'url', value: firstFrameUrl } },
+    { type: 'text', content: 'Slow cinematic push-in' },
+    {
+      type: 'image',
+      source: { type: 'url', value: lastFrameUrl },
+      metadata: { role: 'end_frame' },
+    },
+  ],
+})
+```
+
+**Role hints** (`metadata.role`):
+
+| Role            | Maps to                                                                                               |
+| --------------- | ----------------------------------------------------------------------------------------------------- |
+| `'reference'`   | fal `reference_image_urls`; Gemini multimodal part; positional otherwise                              |
+| `'character'`   | Same as `'reference'`; Veo `referenceImages` slot (planned — no Veo adapter yet)                      |
+| `'mask'`        | OpenAI `mask` (gpt-image-2, gpt-image-1, dall-e-2); fal `mask_url`                                    |
+| `'control'`     | fal `control_image_url` (ControlNet / depth / pose)                                                   |
+| `'start_frame'` | fal `start_image_url` (or the endpoint's field, e.g. `image_url` on Kling i2v); Veo `image` (planned) |
+| `'end_frame'`   | fal `end_image_url` (or e.g. `tail_image_url` / `last_frame_url`); Veo `lastFrame` (planned)          |
+
+**Provider support matrix:**
+
+| Provider   | `generateImage` image parts                                                                                                                                                                              | `generateVideo` image parts                                                                                                                                                                        |
+| ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| OpenAI     | gpt-image-2 / gpt-image-1 / -mini → `images.edit()` (up to 16). dall-e-2 → edit (1). dall-e-3 throws.                                                                                                    | Sora-2 / -pro → `input_reference` (single). Throws if >1.                                                                                                                                          |
+| Gemini     | Native (gemini-\*-flash-image, "nano-banana") → multimodal `contents`. Imagen throws.                                                                                                                    | No native Veo adapter yet — deferred to a follow-up.                                                                                                                                               |
+| fal        | Per-endpoint field names from a generated map (`pnpm generate:fal-image-fields`). Defaults: 1 input → `image_url`; >1 → `image_urls`; roles → `mask_url` / `control_image_url` / `reference_image_urls`. | Per-endpoint map (e.g. Kling i2v start frame → `image_url`). Defaults: 1 input → `image_url`; `start_frame`/`end_frame` → `start_image_url`/`end_image_url`; `reference` → `reference_image_urls`. |
+| Grok       | grok-imagine models → `/v1/images/edits` JSON endpoint (≤3 sources, addressed by xAI in request order; prompt sent verbatim; mask/control throw). grok-2-image-1212 throws.                              | n/a                                                                                                                                                                                                |
+| OpenRouter | Prompt parts map 1:1 onto multimodal `text` / `image_url` content parts, preserving interleaved order.                                                                                                   | n/a                                                                                                                                                                                                |
+| Anthropic  | n/a (no image generation API).                                                                                                                                                                           | n/a                                                                                                                                                                                                |
+
+Video and audio prompt parts follow the same `metadata.role` convention
+for video-to-video and lipsync flows on fal; other providers throw when
+they're passed.
+
 ### 2. Audio Generation (Music, Sound Effects)
 
 Distinct from TTS — `generateAudio()` produces non-speech audio content.
@@ -579,7 +676,54 @@ generateSpeech({
 
 > Source: Gemini TTS adapter validation; CodeRabbit review of PR #463.
 
-### h. LOW: Writing a logging middleware to see media chunks flow through
+### h. HIGH: Passing image prompt parts to a model that doesn't support image-conditioned generation
+
+Not every model accepts image-conditioned prompts. The `prompt` type is
+narrowed per model, so passing an image part to a text-only model
+(dall-e-3, Imagen, grok-2-image) is a **compile-time error**; adapters
+also throw a clear runtime error as a backstop, so users learn at call
+time rather than getting silently wrong output.
+
+```typescript
+// WRONG — dall-e-3 has no edit/inputs API; image parts are a type error
+generateImage({
+  adapter: openaiImage('dall-e-3'),
+  prompt: [
+    { type: 'text', content: 'Edit this' },
+    { type: 'image', source: { type: 'url', value: url } }, // ❌ type error
+  ],
+})
+
+// WRONG — Imagen is text-to-image only; same compile-time rejection
+generateImage({
+  adapter: geminiImage('imagen-4.0-generate-001'),
+  prompt: [
+    { type: 'text', content: 'Edit this' },
+    { type: 'image', source: { type: 'url', value: url } }, // ❌ type error
+  ],
+})
+
+// CORRECT — use a model that supports image-conditioned generation
+generateImage({
+  adapter: openaiImage('gpt-image-2'), // edits up to 16 images
+  prompt: [
+    { type: 'text', content: 'Edit this' },
+    { type: 'image', source: { type: 'url', value: url } },
+  ],
+})
+
+generateImage({
+  adapter: geminiImage('gemini-3.1-flash-image-preview'), // native multimodal
+  prompt: [
+    { type: 'text', content: 'Edit this' },
+    { type: 'image', source: { type: 'url', value: url } },
+  ],
+})
+```
+
+> Source: docs/media/image-generation.md, docs/media/video-generation.md.
+
+### i. LOW: Writing a logging middleware to see media chunks flow through
 
 Every media activity — `generateAudio`, `generateSpeech`,
 `generateTranscription`, `generateImage`, `generateVideo` — accepts the
diff --git a/packages/ai/src/activities/generateImage/adapter.ts b/packages/ai/src/activities/generateImage/adapter.ts
index 532bc7d6d..cbc24b72c 100644
--- a/packages/ai/src/activities/generateImage/adapter.ts
+++ b/packages/ai/src/activities/generateImage/adapter.ts
@@ -1,4 +1,8 @@
-import type { ImageGenerationOptions, ImageGenerationResult } from '../../types'
+import type {
+  ImageGenerationOptions,
+  ImageGenerationResult,
+  ModelInputModalitiesByName,
+} from '../../types'
 
 /**
  * Resolve the size type for a model from the model-size map.
@@ -29,6 +33,8 @@ export interface ImageAdapterConfig {
  * - TProviderOptions: Base provider-specific options (already resolved)
  * - TModelProviderOptionsByName: Map from model name to its specific provider options
  * - TModelSizeByName: Map from model name to its supported sizes
+ * - TModelInputModalitiesByName: Map from model name to the non-text prompt
+ *   modalities it accepts (constrains the `prompt` part types at compile time)
  */
 export interface ImageAdapter<
   TModel extends string = string,
@@ -38,6 +44,8 @@ export interface ImageAdapter<
     string,
     string
   >,
+  TModelInputModalitiesByName extends ModelInputModalitiesByName =
+    ModelInputModalitiesByName,
 > {
   /** Discriminator for adapter kind - used by generate() to determine API shape */
   readonly kind: 'image'
@@ -53,6 +61,7 @@ export interface ImageAdapter<
     providerOptions: TProviderOptions
     modelProviderOptionsByName: TModelProviderOptionsByName
     modelSizeByName: TModelSizeByName
+    modelInputModalitiesByName: TModelInputModalitiesByName
   }
 
   /**
@@ -67,7 +76,7 @@ export interface ImageAdapter<
  * An ImageAdapter with any/unknown type parameters.
  * Useful as a constraint in generic functions and interfaces.
  */
-export type AnyImageAdapter = ImageAdapter<any, any, any, any>
+export type AnyImageAdapter = ImageAdapter<any, any, any, any, any>
 
 /**
  * Abstract base class for image generation adapters.
@@ -83,11 +92,14 @@ export abstract class BaseImageAdapter<
     string,
     string
   >,
+  TModelInputModalitiesByName extends ModelInputModalitiesByName =
+    ModelInputModalitiesByName,
 > implements ImageAdapter<
   TModel,
   TProviderOptions,
   TModelProviderOptionsByName,
-  TModelSizeByName
+  TModelSizeByName,
+  TModelInputModalitiesByName
 > {
   readonly kind = 'image' as const
   abstract readonly name: string
@@ -98,6 +110,7 @@ export abstract class BaseImageAdapter<
     providerOptions: TProviderOptions
     modelProviderOptionsByName: TModelProviderOptionsByName
     modelSizeByName: TModelSizeByName
+    modelInputModalitiesByName: TModelInputModalitiesByName
   }
 
   protected config: ImageAdapterConfig
diff --git a/packages/ai/src/activities/generateImage/index.ts b/packages/ai/src/activities/generateImage/index.ts
index b8d173b09..a1e399533 100644
--- a/packages/ai/src/activities/generateImage/index.ts
+++ b/packages/ai/src/activities/generateImage/index.ts
@@ -8,10 +8,16 @@
 import { aiEventClient } from '@tanstack/ai-event-client'
 import { streamGenerationResult } from '../stream-generation-result.js'
 import { resolveDebugOption } from '../../logger/resolve'
+import { resolveMediaPrompt } from '../../utilities/media-prompt'
 import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
 import type { ImageAdapter } from './adapter'
-import type { ImageGenerationResult, StreamChunk } from '../../types'
+import type {
+  ImageGenerationResult,
+  MediaPrompt,
+  MediaPromptFor,
+  StreamChunk,
+} from '../../types'
 
 // ===========================
 // Activity Kind
@@ -55,6 +61,23 @@ export type ImageSizeForModel<TAdapter, TModel extends string> =
         : string
     : string
 
+/**
+ * Extract the prompt type a model accepts from an ImageAdapter via ~types.
+ * Adapters declare a per-model input-modality map; models in the map get a
+ * `prompt` narrowed to text + their supported part types (text-only models
+ * accept `string | Array<TextPart>`), so unsupported media parts fail at
+ * compile time. Adapters without a map fall back to the full MediaPrompt.
+ */
+export type ImagePromptForModel<TAdapter, TModel extends string> =
+  TAdapter extends ImageAdapter<any, any, any, any, infer ModsByName>
+    ? string extends keyof ModsByName
+      ? // No explicit map - accept the full union
+        MediaPrompt
+      : TModel extends keyof ModsByName
+        ? MediaPromptFor<ModsByName[TModel][number]>
+        : MediaPrompt
+    : MediaPrompt
+
 // ===========================
 // Activity Options Type
 // ===========================
@@ -72,8 +95,16 @@ export type ImageActivityOptions<
 > = {
   /** The image adapter to use (must be created with a model) */
   adapter: TAdapter & { kind: typeof kind }
-  /** Text description of the desired image(s) */
-  prompt: string
+  /**
+   * Description of the desired image(s). Either a plain string, or — for
+   * models that support image-conditioned generation — an ordered array of
+   * content parts interleaving text with image inputs (image-to-image,
+   * reference-guided, edit, multi-reference). Media parts may carry
+   * `metadata.role` (`'reference' | 'mask' | 'control' | 'character'`) to
+   * disambiguate intent. The accepted part types are narrowed per model via
+   * the adapter's input-modality map.
+   */
+  prompt: ImagePromptForModel<TAdapter, TAdapter['model']>
   /** Number of images to generate (default: 1) */
   numberOfImages?: number
   /** Image size in WIDTHxHEIGHT format (e.g., "1024x1024") */
@@ -203,13 +234,26 @@ async function runGenerateImage<
   const startTime = Date.now()
   const logger: InternalLogger = resolveDebugOption(options.debug)
 
+  // Devtools events carry the flattened prompt text plus media-part counts —
+  // the wire payload stays `prompt: string` regardless of the prompt shape.
+  const resolved = resolveMediaPrompt(rest.prompt)
+
   aiEventClient.emit('image:request:started', {
     requestId,
     provider: adapter.name,
     model,
-    prompt: rest.prompt,
+    prompt: resolved.text,
     numberOfImages: rest.numberOfImages,
     size: rest.size,
+    ...(resolved.images.length > 0 && {
+      imageInputCount: resolved.images.length,
+    }),
+    ...(resolved.videos.length > 0 && {
+      videoInputCount: resolved.videos.length,
+    }),
+    ...(resolved.audios.length > 0 && {
+      audioInputCount: resolved.audios.length,
+    }),
     modelOptions: rest.modelOptions,
     timestamp: startTime,
   })
diff --git a/packages/ai/src/activities/generateVideo/adapter.ts b/packages/ai/src/activities/generateVideo/adapter.ts
index a0b4b4389..4f0eaed21 100644
--- a/packages/ai/src/activities/generateVideo/adapter.ts
+++ b/packages/ai/src/activities/generateVideo/adapter.ts
@@ -1,4 +1,5 @@
 import type {
+  ModelInputModalitiesByName,
   VideoGenerationOptions,
   VideoJobResult,
   VideoStatusResult,
@@ -31,6 +32,8 @@ export interface VideoAdapterConfig {
  * - TProviderOptions: Provider-specific options (already resolved)
  * - TModelProviderOptionsByName: Map from model name to its specific provider options
  * - TModelSizeByName: Map from model name to its supported sizes
+ * - TModelInputModalitiesByName: Map from model name to the non-text prompt
+ *   modalities it accepts (constrains the `prompt` part types at compile time)
  */
 export interface VideoAdapter<
   TModel extends string = string,
@@ -40,6 +43,8 @@ export interface VideoAdapter<
     string,
     string
   >,
+  TModelInputModalitiesByName extends ModelInputModalitiesByName =
+    ModelInputModalitiesByName,
 > {
   /** Discriminator for adapter kind - used to determine API shape */
   readonly kind: 'video'
@@ -55,6 +60,7 @@ export interface VideoAdapter<
     providerOptions: TProviderOptions
     modelProviderOptionsByName: TModelProviderOptionsByName
     modelSizeByName: TModelSizeByName
+    modelInputModalitiesByName: TModelInputModalitiesByName
   }
 
   /**
@@ -81,7 +87,7 @@ export interface VideoAdapter<
  * A VideoAdapter with any/unknown type parameters.
  * Useful as a constraint in generic functions and interfaces.
  */
-export type AnyVideoAdapter = VideoAdapter<any, any, any, any>
+export type AnyVideoAdapter = VideoAdapter<any, any, any, any, any>
 
 /**
  * Abstract base class for video generation adapters.
@@ -99,11 +105,14 @@ export abstract class BaseVideoAdapter<
     string,
     string
   >,
+  TModelInputModalitiesByName extends ModelInputModalitiesByName =
+    ModelInputModalitiesByName,
 > implements VideoAdapter<
   TModel,
   TProviderOptions,
   TModelProviderOptionsByName,
-  TModelSizeByName
+  TModelSizeByName,
+  TModelInputModalitiesByName
 > {
   readonly kind = 'video' as const
   abstract readonly name: string
@@ -114,6 +123,7 @@ export abstract class BaseVideoAdapter<
     providerOptions: TProviderOptions
     modelProviderOptionsByName: TModelProviderOptionsByName
     modelSizeByName: TModelSizeByName
+    modelInputModalitiesByName: TModelInputModalitiesByName
   }
 
   protected config: VideoAdapterConfig
diff --git a/packages/ai/src/activities/generateVideo/index.ts b/packages/ai/src/activities/generateVideo/index.ts
index cee2339f7..6b39ef60d 100644
--- a/packages/ai/src/activities/generateVideo/index.ts
+++ b/packages/ai/src/activities/generateVideo/index.ts
@@ -14,6 +14,8 @@ import type { InternalLogger } from '../../logger/internal-logger'
 import type { DebugOption } from '../../logger/types'
 import type { VideoAdapter } from './adapter'
 import type {
+  MediaPrompt,
+  MediaPromptFor,
   StreamChunk,
   VideoJobResult,
   VideoStatusResult,
@@ -49,6 +51,21 @@ export type VideoSizeForAdapter<TAdapter> =
       : string
     : string
 
+/**
+ * Extract the prompt type a model accepts from a VideoAdapter via ~types.
+ * Mirrors `ImagePromptForModel`: models in the adapter's input-modality map
+ * get a `prompt` narrowed to text + their supported part types; adapters
+ * without a map fall back to the full MediaPrompt.
+ */
+export type VideoPromptForAdapter<TAdapter> =
+  TAdapter extends VideoAdapter<infer TModel, any, any, any, infer ModsByName>
+    ? string extends keyof ModsByName
+      ? MediaPrompt
+      : TModel extends keyof ModsByName
+        ? MediaPromptFor<ModsByName[TModel][number]>
+        : MediaPrompt
+    : MediaPrompt
+
 // ===========================
 // Activity Options Types
 
@@ -83,8 +100,16 @@ export type VideoCreateOptions<
 > = VideoActivityBaseOptions<TAdapter> & {
   /** Request type - create a new job (default if not specified) */
   request?: 'create'
-  /** Text description of the desired video */
-  prompt: string
+  /**
+   * Description of the desired video. Either a plain string, or — for models
+   * that support image-conditioned generation — an ordered array of content
+   * parts interleaving text with image inputs. Image parts may carry
+   * `metadata.role` (`'start_frame' | 'end_frame' | 'reference' |
+   * 'character'`) to disambiguate intent; positional fallback otherwise. The
+   * accepted part types are narrowed per model via the adapter's
+   * input-modality map.
+   */
+  prompt: VideoPromptForAdapter<TAdapter>
   /** Video size — format depends on the provider (e.g., "16:9", "1280x720") */
   size?: VideoSizeForAdapter<TAdapter>
   /** Video duration in seconds */
diff --git a/packages/ai/src/client.ts b/packages/ai/src/client.ts
index 0c654252a..75cb2c21d 100644
--- a/packages/ai/src/client.ts
+++ b/packages/ai/src/client.ts
@@ -97,6 +97,10 @@ export type {
   CustomEvent,
   DocumentPart,
   ImagePart,
+  MediaInputMetadata,
+  MediaInputRole,
+  MediaPrompt,
+  MediaPromptPart,
   MessagePart,
   ModelMessage,
   RunErrorEvent,
diff --git a/packages/ai/src/index.ts b/packages/ai/src/index.ts
index c406290ea..359ab9a73 100644
--- a/packages/ai/src/index.ts
+++ b/packages/ai/src/index.ts
@@ -114,6 +114,10 @@ export * from './types'
 // Usage utilities
 export { buildBaseUsage, type BaseUsageInput } from './utilities/usage'
 
+// Media-generation prompt resolution (used by image / video adapters)
+export { resolveMediaPrompt } from './utilities/media-prompt'
+export type { ResolvedMediaPrompt } from './utilities/media-prompt'
+
 // System prompts (type + normaliser used by adapters)
 export type { SystemPrompt, NormalizedSystemPrompt } from './system-prompts'
 export { normalizeSystemPrompts } from './system-prompts'
diff --git a/packages/ai/src/types.ts b/packages/ai/src/types.ts
index 29b1c8032..3748d9842 100644
--- a/packages/ai/src/types.ts
+++ b/packages/ai/src/types.ts
@@ -1463,6 +1463,99 @@ export interface SummarizationResult {
 // Image Generation Types
 // ============================================================================
 
+/**
+ * Optional role hint on a media input part (image / video / audio). Adapters
+ * read `metadata.role` to route the part to the provider-specific request
+ * field — e.g. `'mask'` → OpenAI `mask` / fal `mask_url`, `'end_frame'` → fal
+ * `end_image_url`, `'reference'` → fal `reference_image_urls`. When omitted
+ * the adapter falls back to positional routing.
+ */
+export type MediaInputRole =
+  | 'reference'
+  | 'mask'
+  | 'control'
+  | 'start_frame'
+  | 'end_frame'
+  | 'character'
+
+/**
+ * Metadata convention for image / video / audio inputs to media generation.
+ * Carried on `ImagePart.metadata` / `VideoPart.metadata` / `AudioPart.metadata`
+ * when used as conditioning inputs to `generateImage()` or `generateVideo()`.
+ */
+export interface MediaInputMetadata {
+  /** Optional role hint disambiguating the part's intent for the adapter */
+  role?: MediaInputRole
+  /**
+   * Optional user-defined label for this input (e.g. `'woman-in-red-dress'`).
+   * **Informational only** — adapters never read it and the SDK never
+   * rewrites prompt text based on it. Use it to correlate parts with the
+   * references you write in your prompt using the provider's own syntax
+   * (fal's `@Image1`, OpenAI's "image 1", etc.), or for your own
+   * bookkeeping/logging.
+   */
+  tag?: string
+}
+
+/**
+ * A single part of a multimodal media-generation prompt. Reuses the chat
+ * content-part shapes: text parts carry the instruction, image / video /
+ * audio parts carry conditioning inputs (with an optional
+ * `metadata.role` hint — see {@link MediaInputRole}).
+ */
+export type MediaPromptPart =
+  | TextPart
+  | ImagePart<MediaInputMetadata>
+  | VideoPart<MediaInputMetadata>
+  | AudioPart<MediaInputMetadata>
+
+/**
+ * Prompt accepted by `generateImage()` / `generateVideo()`: a plain string,
+ * or an ordered array of content parts for image-conditioned generation
+ * ("not like this *(image)*, more like this *(image)*"). Part order is
+ * meaningful — adapters with native multimodal prompts (Gemini, OpenRouter)
+ * preserve the interleaving; named-field providers (fal, OpenAI, xAI)
+ * extract the media parts and flatten the text. Text is always sent
+ * verbatim: to reference inputs from the prompt, write the provider's own
+ * syntax yourself (e.g. fal's `@Image1`, OpenAI's "image 1"). An array may
+ * be media-only (e.g. upscalers or pure img2img endpoints that take no
+ * instruction text).
+ */
+export type MediaPrompt = string | Array<MediaPromptPart>
+
+/**
+ * Non-text modalities a media-generation model can accept in its prompt.
+ */
+export type MediaPromptModality = 'image' | 'video' | 'audio'
+
+/** Maps a prompt modality to its content-part type. @internal */
+interface MediaPartByModality {
+  image: ImagePart<MediaInputMetadata>
+  video: VideoPart<MediaInputMetadata>
+  audio: AudioPart<MediaInputMetadata>
+}
+
+/**
+ * Prompt type narrowed to the modalities a specific model supports.
+ * `MediaPromptFor<never>` (a text-only model) is `string | Array<TextPart>`;
+ * `MediaPromptFor<'image'>` additionally admits image parts, etc. Used by
+ * the activity option types together with the adapter's per-model input
+ * modality map so unsupported parts fail at compile time.
+ */
+export type MediaPromptFor<TModalities extends MediaPromptModality = never> =
+  | string
+  | Array<TextPart | MediaPartByModality[TModalities]>
+
+/**
+ * Per-model map from model name to the prompt modalities it accepts, used as
+ * an adapter type parameter (`TModelInputModalitiesByName`). Models absent
+ * from the map fall back to the unconstrained {@link MediaPrompt}.
+ */
+export type ModelInputModalitiesByName = Record<
+  string,
+  ReadonlyArray<MediaPromptModality>
+>
+
 /**
  * Options for image generation.
  * These are the common options supported across providers.
@@ -1473,8 +1566,16 @@ export interface ImageGenerationOptions<
 > {
   /** The model to use for image generation */
   model: string
-  /** Text description of the desired image(s) */
-  prompt: string
+  /**
+   * Description of the desired image(s): a plain string, or an ordered array
+   * of content parts for image-conditioned generation (image-to-image,
+   * reference-guided, edit, multi-reference). Media parts may carry
+   * `metadata.role` to disambiguate intent (mask, control, reference, …).
+   * Adapters map parts onto the provider-native request — e.g. Gemini
+   * multimodal `contents`, OpenAI `images.edit()`, fal `image_url` /
+   * `mask_url` — and throw a clear runtime error for unsupported modalities.
+   */
+  prompt: MediaPrompt
   /** Number of images to generate (default: 1) */
   numberOfImages?: number
   /** Image size in WIDTHxHEIGHT format (e.g., "1024x1024") */
@@ -1595,8 +1696,15 @@ export interface VideoGenerationOptions<
 > {
   /** The model to use for video generation */
   model: string
-  /** Text description of the desired video */
-  prompt: string
+  /**
+   * Description of the desired video: a plain string, or an ordered array of
+   * content parts for image-conditioned generation. Image parts may carry
+   * `metadata.role` (`'start_frame' | 'end_frame' | 'reference' |
+   * 'character'`) to disambiguate intent; adapters route them onto the
+   * provider-native request (e.g. OpenAI Sora `input_reference`, fal
+   * `image_url` / `end_image_url`) and throw at runtime if unsupported.
+   */
+  prompt: MediaPrompt
   /** Video size — format depends on the provider (e.g., "16:9", "1280x720") */
   size?: TSize
   /** Video duration in seconds */
diff --git a/packages/ai/src/utilities/media-prompt.ts b/packages/ai/src/utilities/media-prompt.ts
new file mode 100644
index 000000000..9cefb64ff
--- /dev/null
+++ b/packages/ai/src/utilities/media-prompt.ts
@@ -0,0 +1,86 @@
+import type {
+  AudioPart,
+  ImagePart,
+  MediaInputMetadata,
+  MediaPrompt,
+  MediaPromptPart,
+  TextPart,
+  VideoPart,
+} from '../types'
+
+/**
+ * A {@link MediaPrompt} decomposed into the views adapters consume.
+ *
+ * Adapters with native multimodal prompts (Gemini `contents`, OpenRouter
+ * chat content parts) consume `parts` to preserve interleaving; named-field
+ * providers (fal, OpenAI) consume `text` plus the typed media buckets.
+ *
+ * Prompt text is **never rewritten**: text parts are concatenated verbatim.
+ * Providers that support referencing inputs from the prompt (e.g. fal's
+ * `@Image1`, OpenAI's "image 1" prose) expect the user to write that syntax
+ * themselves — the SDK does not inject or substitute markers.
+ */
+export interface ResolvedMediaPrompt {
+  /**
+   * Text parts concatenated verbatim (paragraph-separated). Empty string
+   * for media-only prompts.
+   */
+  text: string
+  /** The prompt as ordered parts; a string prompt becomes one text part. */
+  parts: Array<MediaPromptPart>
+  /** Image parts in prompt order. */
+  images: Array<ImagePart<MediaInputMetadata>>
+  /** Video parts in prompt order. */
+  videos: Array<VideoPart<MediaInputMetadata>>
+  /** Audio parts in prompt order. */
+  audios: Array<AudioPart<MediaInputMetadata>>
+}
+
+/**
+ * Decompose a {@link MediaPrompt} into flattened text and per-modality part
+ * buckets, preserving prompt order everywhere. This is the single downrev
+ * point from the canonical interleaved prompt shape to the named-field
+ * request shapes most providers expose.
+ */
+export function resolveMediaPrompt(prompt: MediaPrompt): ResolvedMediaPrompt {
+  if (typeof prompt === 'string') {
+    const textPart: TextPart = { type: 'text', content: prompt }
+    return {
+      text: prompt,
+      parts: [textPart],
+      images: [],
+      videos: [],
+      audios: [],
+    }
+  }
+
+  const images: Array<ImagePart<MediaInputMetadata>> = []
+  const videos: Array<VideoPart<MediaInputMetadata>> = []
+  const audios: Array<AudioPart<MediaInputMetadata>> = []
+  const textSegments: Array<string> = []
+
+  for (const part of prompt) {
+    switch (part.type) {
+      case 'text':
+        if (part.content) textSegments.push(part.content)
+        break
+      case 'image':
+        images.push(part)
+        break
+      case 'video':
+        videos.push(part)
+        break
+      case 'audio':
+        audios.push(part)
+        break
+    }
+  }
+
+  return {
+    text: textSegments.join('\n\n'),
+    parts: prompt,
+    images,
+    videos,
+    audios,
+  }
+}
diff --git a/packages/ai/tests/image-per-model-type-safety.test.ts b/packages/ai/tests/image-per-model-type-safety.test.ts
index db67dd048..aeb79d621 100644
--- a/packages/ai/tests/image-per-model-type-safety.test.ts
+++ b/packages/ai/tests/image-per-model-type-safety.test.ts
@@ -169,6 +169,16 @@ type MockImageModelSizeByName = {
   'mock-dall-e-3': MockDallE3Size
 }
 
+/**
+ * Type map: model name -> supported prompt input modalities.
+ * mock-gpt-image-1 accepts image-conditioned prompts; mock-dall-e-3 is
+ * text-to-image only.
+ */
+type MockImageModelInputModalitiesByName = {
+  'mock-gpt-image-1': readonly ['image']
+  'mock-dall-e-3': readonly []
+}
+
 // ===========================
 // Mock Model Definitions
 // ===========================
@@ -199,7 +209,8 @@ class MockImageAdapter<TModel extends MockImageModel> extends BaseImageAdapter<
   TModel,
   MockImageProviderOptions,
   MockImageModelProviderOptionsByName,
-  MockImageModelSizeByName
+  MockImageModelSizeByName,
+  MockImageModelInputModalitiesByName
 > {
   override readonly kind = 'image' as const
   readonly name = 'mock' as const
@@ -850,3 +861,58 @@ describe('Model Size Type Assertions', () => {
     })
   })
 })
+
+describe('Per-model prompt modality type safety', () => {
+  it('allows image parts in the prompt for image-input models', () => {
+    generateImage({
+      adapter: mockImage('mock-gpt-image-1'),
+      prompt: [
+        { type: 'text', content: 'Make it cinematic' },
+        {
+          type: 'image',
+          source: { type: 'url', value: 'https://example.com/ref.png' },
+          metadata: { role: 'reference' },
+        },
+      ],
+    })
+  })
+
+  it('rejects image parts in the prompt for text-only models', () => {
+    generateImage({
+      adapter: mockImage('mock-dall-e-3'),
+      prompt: [
+        { type: 'text', content: 'A cat' },
+        {
+          // @ts-expect-error - mock-dall-e-3 does not accept image prompt parts
+          type: 'image',
+          source: { type: 'url', value: 'https://example.com/ref.png' },
+        },
+      ],
+    })
+  })
+
+  it('rejects video parts for models that only accept image inputs', () => {
+    generateImage({
+      adapter: mockImage('mock-gpt-image-1'),
+      prompt: [
+        { type: 'text', content: 'Animate' },
+        {
+          // @ts-expect-error - mock-gpt-image-1 does not accept video prompt parts
+          type: 'video',
+          source: { type: 'url', value: 'https://example.com/v.mp4' },
+        },
+      ],
+    })
+  })
+
+  it('always accepts plain string prompts', () => {
+    generateImage({
+      adapter: mockImage('mock-gpt-image-1'),
+      prompt: 'A cat',
+    })
+    generateImage({
+      adapter: mockImage('mock-dall-e-3'),
+      prompt: 'A cat',
+    })
+  })
+})
diff --git a/packages/ai/tests/media-prompt.test.ts b/packages/ai/tests/media-prompt.test.ts
new file mode 100644
index 000000000..18bd1dc12
--- /dev/null
+++ b/packages/ai/tests/media-prompt.test.ts
@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+import { resolveMediaPrompt } from '../src/utilities/media-prompt'
+import type { ImagePart, MediaInputMetadata, MediaPromptPart } from '../src'
+
+function image(
+  value: string,
+  role?: NonNullable<MediaInputMetadata['role']>,
+): ImagePart<MediaInputMetadata> {
+  return {
+    type: 'image',
+    source: { type: 'url', value },
+    ...(role && { metadata: { role } }),
+  }
+}
+
+describe('resolveMediaPrompt', () => {
+  it('wraps a string prompt as a single text part', () => {
+    const resolved = resolveMediaPrompt('a cat')
+    expect(resolved.text).toBe('a cat')
+    expect(resolved.parts).toEqual([{ type: 'text', content: 'a cat' }])
+    expect(resolved.images).toEqual([])
+    expect(resolved.videos).toEqual([])
+    expect(resolved.audios).toEqual([])
+  })
+
+  it('buckets media parts by modality in prompt order', () => {
+    const parts: Array<MediaPromptPart> = [
+      image('https://a.png'),
+      { type: 'text', content: 'animate this' },
+      { type: 'video', source: { type: 'url', value: 'https://v.mp4' } },
+      { type: 'audio', source: { type: 'url', value: 'https://a.mp3' } },
+      image('https://b.png', 'end_frame'),
+    ]
+    const resolved = resolveMediaPrompt(parts)
+    expect(resolved.text).toBe('animate this')
+    expect(resolved.parts).toBe(parts)
+    expect(resolved.images.map((p) => p.source.value)).toEqual([
+      'https://a.png',
+      'https://b.png',
+    ])
+    expect(resolved.images[1]?.metadata?.role).toBe('end_frame')
+    expect(resolved.videos).toHaveLength(1)
+    expect(resolved.audios).toHaveLength(1)
+  })
+
+  it('joins multiple text parts with paragraph breaks', () => {
+    const resolved = resolveMediaPrompt([
+      { type: 'text', content: 'first' },
+      image('https://a.png'),
+      { type: 'text', content: 'second' },
+    ])
+    expect(resolved.text).toBe('first\n\nsecond')
+  })
+
+  it('returns empty text for media-only prompts', () => {
+    const resolved = resolveMediaPrompt([image('https://a.png')])
+    expect(resolved.text).toBe('')
+    expect(resolved.images).toHaveLength(1)
+  })
+
+  it('skips empty text parts', () => {
+    const resolved = resolveMediaPrompt([
+      { type: 'text', content: '' },
+      { type: 'text', content: 'real' },
+    ])
+    expect(resolved.text).toBe('real')
+  })
+
+  it('never rewrites text — provider referencing syntax passes through verbatim', () => {
+    const resolved = resolveMediaPrompt([
+      {
+        type: 'text',
+        content: 'Put @Image1 next to <IMAGE_0> from image 1',
+      },
+      image('https://a.png'),
+    ])
+    expect(resolved.text).toBe('Put @Image1 next to <IMAGE_0> from image 1')
+  })
+})
diff --git a/scripts/generate-fal-image-field-map.ts b/scripts/generate-fal-image-field-map.ts
new file mode 100644
index 000000000..297819fe8
--- /dev/null
+++ b/scripts/generate-fal-image-field-map.ts
@@ -0,0 +1,359 @@
+/**
+ * Generates the fal image-conditioning field-override map from the
+ * `EndpointTypeMap` types shipped with `@fal-ai/client`.
+ *
+ * fal endpoints use inconsistent field names for image-conditioned
+ * generation (`image_url` vs `image_urls` vs `first_frame_url` vs
+ * `mask_image_url`, ...). The runtime mapper in
+ * `packages/ai-fal/src/image/image-inputs.ts` applies a default
+ * field per input role; this script walks every endpoint's input type with
+ * the TypeScript checker and records, per role, the field the endpoint
+ * actually accepts whenever it differs from that default. Endpoints that
+ * match the defaults (the vast majority) are omitted, keeping the shipped
+ * artifact small.
+ *
+ * The emitted file type-checks each recorded field name against
+ * `EndpointTypeMap` via `satisfies` (a type-only import, erased at runtime),
+ * so a fal SDK bump that renames a field fails `tsc` until this script is
+ * re-run. A unit test compares the recorded endpoints.d.ts hash against the
+ * installed SDK to catch staleness.
+ *
+ * Usage:
+ *   pnpm tsx scripts/generate-fal-image-field-map.ts          # regenerate
+ *   pnpm tsx scripts/generate-fal-image-field-map.ts --check  # CI staleness check
+ */
+
+import { createHash } from 'node:crypto'
+import { readFileSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import ts from 'typescript'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const ROOT = resolve(__dirname, '..')
+const FAL_PKG = resolve(ROOT, 'packages/ai-fal')
+const ENDPOINTS_DTS = resolve(
+  FAL_PKG,
+  'node_modules/@fal-ai/client/src/types/endpoints.d.ts',
+)
+const CLIENT_PKG_JSON = resolve(
+  FAL_PKG,
+  'node_modules/@fal-ai/client/package.json',
+)
+const OUT_FILE = resolve(
+  FAL_PKG,
+  'src/image/generated/image-field-overrides.ts',
+)
+
+// ---------------------------------------------------------------------------
+// Role classification
+// ---------------------------------------------------------------------------
+
+/**
+ * Routing roles used by the runtime mapper. `single` / `multi` cover unroled
+ * source images; the rest correspond to `MediaInputRole` values.
+ */
+type RoleKey =
+  | 'single'
+  | 'multi'
+  | 'mask'
+  | 'control'
+  | 'reference'
+  | 'start'
+  | 'end'
+
+/**
+ * Default field per role — must stay in sync with `DEFAULT_FIELDS` in
+ * image-inputs.ts. An override is only emitted when the chosen candidate
+ * differs from this default.
+ */
+const DEFAULTS: Record<RoleKey, string> = {
+  single: 'image_url',
+  multi: 'image_urls',
+  mask: 'mask_url',
+  control: 'control_image_url',
+  reference: 'reference_image_urls',
+  start: 'start_image_url',
+  end: 'end_image_url',
+}
+
+/**
+ * Candidate fields per role, in priority order. The first candidate present
+ * on the endpoint's input type wins. Names here are deliberately
+ * conservative: only fields whose semantics unambiguously match the role.
+ *
+ * `start` / `end` are only consumed by the video mapper (the image mapper
+ * treats those roles as plain sources), so they are only computed for
+ * endpoints whose output contains video — that's also why `image_url` is a
+ * valid `start` candidate: on image-to-video endpoints the source image IS
+ * the start frame.
+ */
+const CANDIDATES: Record<RoleKey, Array<string>> = {
+  single: [
+    'image_url',
+    'input_image_url',
+    'image_data_url',
+    'image_urls',
+    'input_image_urls',
+  ],
+  multi: [
+    'image_urls',
+    'input_image_urls',
+    'ref_image_urls',
+    'reference_image_urls',
+  ],
+  mask: ['mask_url', 'mask_image_url'],
+  control: ['control_image_url'],
+  reference: [
+    'reference_image_urls',
+    'ref_image_urls',
+    'reference_image_url',
+    'image_urls',
+    'input_image_urls',
+  ],
+  start: ['start_image_url', 'first_frame_url', 'first_image_url', 'image_url'],
+  end: ['end_image_url', 'last_frame_url', 'last_image_url', 'tail_image_url'],
+}
+
+/** Roles only meaningful for endpoints that produce video. */
+const VIDEO_ONLY_ROLES = new Set<RoleKey>(['start', 'end'])
+
+/**
+ * Fields that take an array of images. The runtime mapper wraps/refuses
+ * values based on this same set (`LIST_FIELDS` in image-inputs.ts); the
+ * generator asserts the actual types agree so the two never drift.
+ */
+const LIST_FIELDS = new Set([
+  'image_urls',
+  'input_image_urls',
+  'ref_image_urls',
+  'reference_image_urls',
+])
+
+// ---------------------------------------------------------------------------
+// Type extraction
+// ---------------------------------------------------------------------------
+
+interface EndpointFields {
+  /** All input field names for this endpoint */
+  fields: Set<string>
+  /** Field name -> whether the field accepts an array */
+  isList: Map<string, boolean>
+  /** Whether the endpoint's output contains video */
+  producesVideo: boolean
+}
+
+function extractEndpointInputs(): Map<string, EndpointFields> {
+  const program = ts.createProgram([ENDPOINTS_DTS], {
+    target: ts.ScriptTarget.ES2022,
+    skipLibCheck: true,
+  })
+  const checker = program.getTypeChecker()
+  const source = program.getSourceFile(ENDPOINTS_DTS)
+  if (!source) throw new Error(`Could not load ${ENDPOINTS_DTS}`)
+
+  let mapType: ts.Type | undefined
+  source.forEachChild((node) => {
+    if (
+      ts.isTypeAliasDeclaration(node) &&
+      node.name.text === 'EndpointTypeMap'
+    ) {
+      mapType = checker.getTypeAtLocation(node.name)
+    }
+  })
+  if (!mapType) throw new Error('EndpointTypeMap not found in endpoints.d.ts')
+
+  const endpoints = new Map<string, EndpointFields>()
+  for (const endpoint of mapType.getProperties()) {
+    const endpointType = checker.getTypeOfSymbol(endpoint)
+    const inputSymbol = endpointType.getProperty('input')
+    if (!inputSymbol) continue
+    const inputType = checker.getTypeOfSymbol(inputSymbol)
+
+    const fields = new Set<string>()
+    const isList = new Map<string, boolean>()
+    for (const field of inputType.getProperties()) {
+      const name = field.getName()
+      fields.add(name)
+      const fieldType = checker.getTypeOfSymbol(field)
+      isList.set(name, typeAcceptsArray(checker, fieldType))
+    }
+
+    const outputSymbol = endpointType.getProperty('output')
+    const producesVideo = outputSymbol
+      ? checker
+          .getTypeOfSymbol(outputSymbol)
+          .getProperties()
+          .some((p) => p.getName() === 'video' || p.getName() === 'videos')
+      : false
+
+    endpoints.set(endpoint.getName(), { fields, isList, producesVideo })
+  }
+  return endpoints
+}
+
+function typeAcceptsArray(checker: ts.TypeChecker, type: ts.Type): boolean {
+  const parts = type.isUnion() ? type.types : [type]
+  return parts.some((part) => checker.isArrayLikeType(part))
+}
+
+// ---------------------------------------------------------------------------
+// Override computation
+// ---------------------------------------------------------------------------
+
+const ROLE_ORDER: Array<RoleKey> = [
+  'single',
+  'multi',
+  'mask',
+  'control',
+  'reference',
+  'start',
+  'end',
+]
+
+function computeOverrides(
+  endpoints: Map<string, EndpointFields>,
+): Map<string, Partial<Record<RoleKey, string>>> {
+  const overrides = new Map<string, Partial<Record<RoleKey, string>>>()
+
+  for (const [endpointId, { fields, isList, producesVideo }] of endpoints) {
+    const entry: Partial<Record<RoleKey, string>> = {}
+    for (const role of ROLE_ORDER) {
+      if (VIDEO_ONLY_ROLES.has(role) && !producesVideo) continue
+      const chosen = CANDIDATES[role].find((candidate) => fields.has(candidate))
+      if (!chosen || chosen === DEFAULTS[role]) continue
+
+      // Arity sanity check: the runtime mapper decides array-wrapping from
+      // the static LIST_FIELDS set, so the actual type must agree.
+      const actualIsList = isList.get(chosen) ?? false
+      const assumedIsList = LIST_FIELDS.has(chosen)
+      if (actualIsList !== assumedIsList) {
+        throw new Error(
+          `Arity mismatch for ${endpointId}.${chosen}: type says ` +
+            `${actualIsList ? 'array' : 'scalar'} but LIST_FIELDS assumes ` +
+            `${assumedIsList ? 'array' : 'scalar'}. Update LIST_FIELDS here ` +
+            `and LIST_FIELDS in image-inputs.ts.`,
+        )
+      }
+      entry[role] = chosen
+    }
+    if (Object.keys(entry).length > 0) overrides.set(endpointId, entry)
+  }
+  return overrides
+}
+
+// ---------------------------------------------------------------------------
+// Emission
+// ---------------------------------------------------------------------------
+
+function render(
+  overrides: Map<string, Partial<Record<RoleKey, string>>>,
+): string {
+  const clientVersion = (
+    JSON.parse(readFileSync(CLIENT_PKG_JSON, 'utf8')) as { version: string }
+  ).version
+  const dtsHash = createHash('sha256')
+    .update(readFileSync(ENDPOINTS_DTS))
+    .digest('hex')
+
+  const sortedIds = [...overrides.keys()].sort()
+  const entries = sortedIds
+    .map((id) => {
+      const entry = overrides.get(id)!
+      const pairs = ROLE_ORDER.filter((role) => entry[role]).map(
+        (role) => `${role}: '${entry[role]}'`,
+      )
+      return `  '${id}': { ${pairs.join(', ')} },`
+    })
+    .join('\n')
+
+  // Union of every field name the runtime mapper may emit: the per-role
+  // defaults plus every field referenced by an override.
+  const fieldNames = new Set<string>(Object.values(DEFAULTS))
+  for (const entry of overrides.values()) {
+    for (const field of Object.values(entry)) fieldNames.add(field)
+  }
+  const fieldNameUnion = [...fieldNames]
+    .sort()
+    .map((name) => `  | '${name}'`)
+    .join('\n')
+
+  return `/* eslint-disable */
+// ---------------------------------------------------------------------------
+// AUTO-GENERATED — do not edit by hand.
+//
+// Generated from @fal-ai/client@${clientVersion} EndpointTypeMap by
+// scripts/generate-fal-image-field-map.ts. Regenerate after bumping
+// @fal-ai/client:
+//
+//   pnpm tsx scripts/generate-fal-image-field-map.ts
+//
+// Maps fal endpoint ids to the image-conditioning input fields they accept
+// whenever those differ from the defaults in image-inputs.ts. Endpoints
+// matching the defaults are omitted. The \`satisfies\` clause below checks
+// every field name against the SDK's endpoint input types at compile time
+// (type-only import — nothing from endpoints.d.ts is shipped at runtime).
+// ---------------------------------------------------------------------------
+import type { EndpointTypeMap } from '@fal-ai/client/endpoints'
+
+/** sha256 of the endpoints.d.ts this file was generated from. */
+export const FAL_ENDPOINTS_DTS_SHA256 =
+  '${dtsHash}'
+
+/** Every input field name the image-input mappers may emit. */
+export type FalImageFieldName =
+${fieldNameUnion}
+
+/**
+ * Per-role input-field overrides. Roles: \`single\` / \`multi\` route unroled
+ * source images; the rest mirror \`MediaInputRole\` (\`start\` / \`end\` map the
+ * \`start_frame\` / \`end_frame\` roles).
+ */
+export interface FalImageFieldOverride {
+  single?: string
+  multi?: string
+  mask?: string
+  control?: string
+  reference?: string
+  start?: string
+  end?: string
+}
+
+type InputFieldOf<K extends keyof EndpointTypeMap> = Extract<
+  keyof EndpointTypeMap[K]['input'],
+  string
+>
+
+export const FAL_IMAGE_FIELD_OVERRIDES = {
+${entries}
+} as const satisfies {
+  [K in keyof EndpointTypeMap]?: {
+    [Role in keyof FalImageFieldOverride]?: InputFieldOf<K>
+  }
+}
+`
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+const endpoints = extractEndpointInputs()
+const overrides = computeOverrides(endpoints)
+const output = render(overrides)
+
+if (process.argv.includes('--check')) {
+  const current = readFileSync(OUT_FILE, 'utf8')
+  if (current !== output) {
+    console.error(
+      'image-field-overrides.ts is stale. Run: pnpm tsx scripts/generate-fal-image-field-map.ts',
+    )
+    process.exit(1)
+  }
+  console.log('image-field-overrides.ts is up to date.')
+} else {
+  writeFileSync(OUT_FILE, output)
+  console.log(
+    `Wrote ${overrides.size} endpoint overrides (of ${endpoints.size} endpoints) to ${OUT_FILE}`,
+  )
+}
diff --git a/testing/e2e/README.md b/testing/e2e/README.md
index ab0f13479..c75fc5f7f 100644
--- a/testing/e2e/README.md
+++ b/testing/e2e/README.md
@@ -30,6 +30,8 @@ Each test iterates over supported providers using `providersFor('feature')`:
 | summarize                | 6         | `tests/summarize.spec.ts`                |
 | summarize-stream         | 6         | `tests/summarize-stream.spec.ts`         |
 | image-gen                | 7         | `tests/image-gen.spec.ts`                |
+| image-to-image           | 1         | `tests/image-to-image.spec.ts`           |
+| image-to-video           | 1         | `tests/image-to-video.spec.ts`           |
 | tts                      | 3         | `tests/tts.spec.ts`                      |
 | transcription            | 3         | `tests/transcription.spec.ts`            |
 | audio-gen                | 1         | `tests/audio-gen.spec.ts`                |
diff --git a/testing/e2e/fixtures/image-to-image/basic.json b/testing/e2e/fixtures/image-to-image/basic.json
new file mode 100644
index 000000000..7f0836f34
--- /dev/null
+++ b/testing/e2e/fixtures/image-to-image/basic.json
@@ -0,0 +1,14 @@
+{
+  "fixtures": [
+    {
+      "match": {
+        "userMessage": "add a tree to this product photo"
+      },
+      "response": {
+        "image": {
+          "url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg=="
+        }
+      }
+    }
+  ]
+}
diff --git a/testing/e2e/global-setup.ts b/testing/e2e/global-setup.ts
index f869df01a..c1eed2859 100644
--- a/testing/e2e/global-setup.ts
+++ b/testing/e2e/global-setup.ts
@@ -92,6 +92,19 @@ function registerMediaFixtures(mock: LLMock) {
     },
   })
 
+  // Image-to-video: the Sora adapter uploads the image part as
+  // `input_reference`, which makes the OpenAI SDK switch to a multipart
+  // POST /v1/videos. aimock 1.29 extracts the `prompt` form field from
+  // multipart bodies, so matching works the same as the JSON case above.
+  mock.onVideo('animate this product photo', {
+    video: {
+      url: 'https://example.com/product-animated.mp4',
+      duration: 5,
+      id: 'video-job-i2v-e2e',
+      status: 'completed',
+    },
+  })
+
   // ElevenLabs music (/v1/music/*) and SFX (/v1/sound-generation) are
   // covered natively by aimock 1.17 — fixtures live under
   // fixtures/audio-gen/ and fixtures/sound-effects/ and are loaded by the
diff --git a/testing/e2e/src/components/ImageGenUI.tsx b/testing/e2e/src/components/ImageGenUI.tsx
index b0286cff6..93cec8b7c 100644
--- a/testing/e2e/src/components/ImageGenUI.tsx
+++ b/testing/e2e/src/components/ImageGenUI.tsx
@@ -5,7 +5,7 @@ import {
   fetchHttpStream,
 } from '@tanstack/ai-react'
 import { generateImageFn } from '@/lib/server-functions'
-import type { ImageGenerationResult } from '@tanstack/ai'
+import type { ImageGenerationResult, MediaPrompt } from '@tanstack/ai'
 import type { Mode, Provider } from '@/lib/types'
 
 interface ImageGenUIProps {
@@ -13,6 +13,24 @@ interface ImageGenUIProps {
   mode: Mode
   testId?: string
   aimockPort?: number
+  /** Show a file input and send the prompt as multimodal parts (image-to-image). */
+  withImageInput?: boolean
+}
+
+function fileToBase64(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader()
+    reader.onload = () => {
+      const result = reader.result
+      if (typeof result !== 'string') {
+        reject(new Error('Unexpected FileReader result'))
+        return
+      }
+      resolve(result.split(',')[1] ?? '')
+    }
+    reader.onerror = () => reject(new Error('Failed to read file'))
+    reader.readAsDataURL(file)
+  })
 }
 
 export function ImageGenUI({
@@ -20,8 +38,10 @@ export function ImageGenUI({
   mode,
   testId,
   aimockPort,
+  withImageInput,
 }: ImageGenUIProps) {
   const [prompt, setPrompt] = useState('')
+  const [imageFile, setImageFile] = useState<File | null>(null)
 
   const connectionOptions = () => {
     const body = { provider, numberOfImages: 1, testId, aimockPort }
@@ -33,7 +53,7 @@ export function ImageGenUI({
       return { connection: fetchHttpStream('/api/image/stream'), body }
     }
     return {
-      fetcher: async (input: { prompt: string }) => {
+      fetcher: async (input: { prompt: MediaPrompt }) => {
         return generateImageFn({
           data: {
             prompt: input.prompt,
@@ -50,6 +70,23 @@ export function ImageGenUI({
   const { generate, result, isLoading, error, status } =
     useGenerateImage(connectionOptions())
 
+  const handleGenerate = async () => {
+    if (!imageFile) {
+      await generate({ prompt })
+      return
+    }
+    const base64 = await fileToBase64(imageFile)
+    await generate({
+      prompt: [
+        { type: 'text', content: prompt },
+        {
+          type: 'image',
+          source: { type: 'data', value: base64, mimeType: imageFile.type },
+        },
+      ],
+    })
+  }
+
   return (
     <div className="p-4 space-y-4">
       <div className="flex gap-2">
@@ -63,13 +100,22 @@ export function ImageGenUI({
         />
         <button
           data-testid="generate-button"
-          onClick={() => generate({ prompt })}
+          onClick={handleGenerate}
           disabled={!prompt.trim() || isLoading}
           className="px-4 py-2 bg-orange-500 text-white rounded text-sm font-medium disabled:opacity-50"
         >
           Generate
         </button>
       </div>
+      {withImageInput && (
+        <input
+          data-testid="image-input"
+          type="file"
+          accept="image/*"
+          onChange={(e) => setImageFile(e.target.files?.[0] ?? null)}
+          className="text-sm text-gray-400"
+        />
+      )}
       <div data-testid="generation-status">
         {status === 'idle'
           ? 'idle'
diff --git a/testing/e2e/src/components/VideoGenUI.tsx b/testing/e2e/src/components/VideoGenUI.tsx
index be5be8923..85f94ee83 100644
--- a/testing/e2e/src/components/VideoGenUI.tsx
+++ b/testing/e2e/src/components/VideoGenUI.tsx
@@ -5,6 +5,7 @@ import {
   fetchHttpStream,
 } from '@tanstack/ai-react'
 import { generateVideoFn } from '@/lib/server-functions'
+import type { MediaPrompt } from '@tanstack/ai'
 import type { Mode, Provider } from '@/lib/types'
 import type { VideoGenerateResult } from '@tanstack/ai-client'
 
@@ -13,6 +14,24 @@ interface VideoGenUIProps {
   mode: Mode
   testId?: string
   aimockPort?: number
+  /** Show a file input and send the prompt as multimodal parts (image-to-video). */
+  withImageInput?: boolean
+}
+
+function fileToBase64(file: File): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader()
+    reader.onload = () => {
+      const result = reader.result
+      if (typeof result !== 'string') {
+        reject(new Error('Unexpected FileReader result'))
+        return
+      }
+      resolve(result.split(',')[1] ?? '')
+    }
+    reader.onerror = () => reject(new Error('Failed to read file'))
+    reader.readAsDataURL(file)
+  })
 }
 
 export function VideoGenUI({
@@ -20,8 +39,10 @@ export function VideoGenUI({
   mode,
   testId,
   aimockPort,
+  withImageInput,
 }: VideoGenUIProps) {
   const [prompt, setPrompt] = useState('')
+  const [imageFile, setImageFile] = useState<File | null>(null)
 
   const connectionOptions = () => {
     const body = { provider, testId, aimockPort }
@@ -33,7 +54,7 @@ export function VideoGenUI({
       return { connection: fetchHttpStream('/api/video/stream'), body }
     }
     return {
-      fetcher: async (input: { prompt: string }) => {
+      fetcher: async (input: { prompt: MediaPrompt }) => {
         return generateVideoFn({
           data: { prompt: input.prompt, provider, aimockPort, testId },
         }) as Promise<VideoGenerateResult>
@@ -44,6 +65,23 @@ export function VideoGenUI({
   const { generate, result, videoStatus, isLoading, error, status } =
     useGenerateVideo(connectionOptions())
 
+  const handleGenerate = async () => {
+    if (!imageFile) {
+      await generate({ prompt })
+      return
+    }
+    const base64 = await fileToBase64(imageFile)
+    await generate({
+      prompt: [
+        { type: 'text', content: prompt },
+        {
+          type: 'image',
+          source: { type: 'data', value: base64, mimeType: imageFile.type },
+        },
+      ],
+    })
+  }
+
   return (
     <div className="p-4 space-y-4">
       <div className="flex gap-2">
@@ -57,13 +95,22 @@ export function VideoGenUI({
         />
         <button
           data-testid="generate-button"
-          onClick={() => generate({ prompt })}
+          onClick={handleGenerate}
           disabled={!prompt.trim() || isLoading}
           className="px-4 py-2 bg-orange-500 text-white rounded text-sm font-medium disabled:opacity-50"
         >
           Generate
         </button>
       </div>
+      {withImageInput && (
+        <input
+          data-testid="image-input"
+          type="file"
+          accept="image/*"
+          onChange={(e) => setImageFile(e.target.files?.[0] ?? null)}
+          className="text-sm text-gray-400"
+        />
+      )}
       <div data-testid="generation-status">
         {status === 'idle'
           ? 'idle'
diff --git a/testing/e2e/src/lib/feature-support.ts b/testing/e2e/src/lib/feature-support.ts
index 6d6b950bd..b4e85a715 100644
--- a/testing/e2e/src/lib/feature-support.ts
+++ b/testing/e2e/src/lib/feature-support.ts
@@ -178,11 +178,26 @@ export const matrix: Record<Feature, Set<Provider>> = {
   ]),
   // Gemini excluded: aimock doesn't mock Gemini's Imagen predict endpoint format
   'image-gen': new Set(['openai', 'grok']),
+  // image-to-image (image parts in the generateImage prompt). aimock 1.29
+  // mocks OpenAI's multipart `/v1/images/edits` (matches on the `prompt` form
+  // field, ignores the binary image/mask fields), so the OpenAI route runs
+  // end-to-end. Other providers route to endpoints aimock doesn't mock yet
+  // (Gemini multimodal `generateContent`, xAI's JSON `/v1/images/edits`,
+  // OpenRouter multimodal chat content parts, fal endpoint-specific input
+  // fields) — their mapping is covered by unit tests. Add them here when
+  // aimock support lands.
+  'image-to-image': new Set(['openai']),
   'audio-gen': new Set(['gemini', 'elevenlabs']),
   'sound-effects': new Set(['elevenlabs']),
   tts: new Set(['openai', 'grok', 'elevenlabs']),
   transcription: new Set(['openai', 'grok', 'elevenlabs']),
   'video-gen': new Set(['openai']),
+  // image-to-video (image parts in the generateVideo prompt). aimock 1.29's
+  // `/v1/videos` handler parses Sora's multipart upload (the SDK switches to
+  // multipart when `input_reference` carries a File) and matches on the
+  // `prompt` form field, so the OpenAI/Sora route runs end-to-end. fal's
+  // endpoint-specific fields remain unit-test-only.
+  'image-to-video': new Set(['openai']),
   // Only Gemini currently surfaces a first-class stateful conversation API via
   // the adapter (geminiTextInteractions, behind @tanstack/ai-gemini/experimental).
   'stateful-interactions': new Set(['gemini']),
diff --git a/testing/e2e/src/lib/features.ts b/testing/e2e/src/lib/features.ts
index 446859ce6..032720468 100644
--- a/testing/e2e/src/lib/features.ts
+++ b/testing/e2e/src/lib/features.ts
@@ -103,6 +103,10 @@ export const featureConfigs: Record<Feature, FeatureConfig> = {
     tools: [],
     modelOptions: {},
   },
+  'image-to-image': {
+    tools: [],
+    modelOptions: {},
+  },
   'audio-gen': {
     tools: [],
     modelOptions: {},
@@ -123,6 +127,10 @@ export const featureConfigs: Record<Feature, FeatureConfig> = {
     tools: [],
     modelOptions: {},
   },
+  'image-to-video': {
+    tools: [],
+    modelOptions: {},
+  },
   'stateful-interactions': {
     tools: [],
     modelOptions: {},
diff --git a/testing/e2e/src/lib/server-functions.ts b/testing/e2e/src/lib/server-functions.ts
index 03132c193..20faeb7b4 100644
--- a/testing/e2e/src/lib/server-functions.ts
+++ b/testing/e2e/src/lib/server-functions.ts
@@ -7,6 +7,7 @@ import {
   generateVideo,
   getVideoJobStatus,
 } from '@tanstack/ai'
+import type { MediaPrompt } from '@tanstack/ai'
 import type { Feature, Provider } from '@/lib/types'
 import {
   createAudioAdapter,
@@ -19,13 +20,17 @@ import {
 export const generateImageFn = createServerFn({ method: 'POST' })
   .inputValidator(
     (data: {
-      prompt: string
+      prompt: MediaPrompt
       provider: Provider
       numberOfImages?: number
       aimockPort?: number
       testId?: string
     }) => {
-      if (!data.prompt.trim()) throw new Error('Prompt is required')
+      const isEmpty =
+        typeof data.prompt === 'string'
+          ? !data.prompt.trim()
+          : data.prompt.length === 0
+      if (isEmpty) throw new Error('Prompt is required')
       if (!data.provider) throw new Error('Provider is required')
       return data
     },
@@ -133,12 +138,16 @@ export const generateAudioFn = createServerFn({ method: 'POST' })
 export const generateVideoFn = createServerFn({ method: 'POST' })
   .inputValidator(
     (data: {
-      prompt: string
+      prompt: MediaPrompt
       provider: Provider
       aimockPort?: number
       testId?: string
     }) => {
-      if (!data.prompt.trim()) throw new Error('Prompt is required')
+      const isEmpty =
+        typeof data.prompt === 'string'
+          ? !data.prompt.trim()
+          : data.prompt.length === 0
+      if (isEmpty) throw new Error('Prompt is required')
       if (!data.provider) throw new Error('Provider is required')
       return data
     },
diff --git a/testing/e2e/src/lib/types.ts b/testing/e2e/src/lib/types.ts
index 018e7744f..dcade6b1f 100644
--- a/testing/e2e/src/lib/types.ts
+++ b/testing/e2e/src/lib/types.ts
@@ -31,11 +31,13 @@ export type Feature =
   | 'summarize'
   | 'summarize-stream'
   | 'image-gen'
+  | 'image-to-image'
   | 'audio-gen'
   | 'sound-effects'
   | 'tts'
   | 'transcription'
   | 'video-gen'
+  | 'image-to-video'
   | 'stateful-interactions'
 
 export const ALL_PROVIDERS: Provider[] = [
@@ -70,10 +72,12 @@ export const ALL_FEATURES: Feature[] = [
   'summarize',
   'summarize-stream',
   'image-gen',
+  'image-to-image',
   'audio-gen',
   'sound-effects',
   'tts',
   'transcription',
   'video-gen',
+  'image-to-video',
   'stateful-interactions',
 ]
diff --git a/testing/e2e/src/routes/$provider/$feature.tsx b/testing/e2e/src/routes/$provider/$feature.tsx
index ea080c4fc..b1fe5b40f 100644
--- a/testing/e2e/src/routes/$provider/$feature.tsx
+++ b/testing/e2e/src/routes/$provider/$feature.tsx
@@ -42,9 +42,11 @@ export const Route = createFileRoute('/$provider/$feature')({
 
 const MEDIA_FEATURES = new Set<Feature>([
   'image-gen',
+  'image-to-image',
   'tts',
   'transcription',
   'video-gen',
+  'image-to-video',
   'audio-gen',
   'sound-effects',
 ])
@@ -132,6 +134,16 @@ function MediaFeature({
           aimockPort={aimockPort}
         />
       )
+    case 'image-to-image':
+      return (
+        <ImageGenUI
+          provider={provider}
+          mode={mode}
+          testId={testId}
+          aimockPort={aimockPort}
+          withImageInput
+        />
+      )
     case 'tts':
       return (
         <TTSUI
@@ -159,6 +171,16 @@ function MediaFeature({
           aimockPort={aimockPort}
         />
       )
+    case 'image-to-video':
+      return (
+        <VideoGenUI
+          provider={provider}
+          mode={mode}
+          testId={testId}
+          aimockPort={aimockPort}
+          withImageInput
+        />
+      )
     case 'audio-gen':
     case 'sound-effects':
       return (
diff --git a/testing/e2e/src/routes/api.image.stream.ts b/testing/e2e/src/routes/api.image.stream.ts
index abcf2c280..bd65b9756 100644
--- a/testing/e2e/src/routes/api.image.stream.ts
+++ b/testing/e2e/src/routes/api.image.stream.ts
@@ -1,6 +1,7 @@
 import { createFileRoute } from '@tanstack/react-router'
 import { generateImage, toHttpResponse } from '@tanstack/ai'
 import { createImageAdapter } from '@/lib/media-providers'
+import type { MediaPrompt } from '@tanstack/ai'
 import type { Provider } from '@/lib/types'
 
 export const Route = createFileRoute('/api/image/stream')({
@@ -13,7 +14,7 @@ export const Route = createFileRoute('/api/image/stream')({
         const data = body.forwardedProps ?? body.data ?? body
         const { prompt, provider, numberOfImages, testId, aimockPort } =
           data as {
-            prompt: string
+            prompt: MediaPrompt
             provider: Provider
             numberOfImages?: number
             testId?: string
diff --git a/testing/e2e/src/routes/api.image.ts b/testing/e2e/src/routes/api.image.ts
index 8fb9829ac..d8b455a63 100644
--- a/testing/e2e/src/routes/api.image.ts
+++ b/testing/e2e/src/routes/api.image.ts
@@ -1,6 +1,7 @@
 import { createFileRoute } from '@tanstack/react-router'
 import { generateImage, toServerSentEventsResponse } from '@tanstack/ai'
 import { createImageAdapter } from '@/lib/media-providers'
+import type { MediaPrompt } from '@tanstack/ai'
 import type { Provider } from '@/lib/types'
 
 export const Route = createFileRoute('/api/image')({
@@ -13,7 +14,7 @@ export const Route = createFileRoute('/api/image')({
         const data = body.forwardedProps ?? body.data ?? body
         const { prompt, provider, numberOfImages, testId, aimockPort } =
           data as {
-            prompt: string
+            prompt: MediaPrompt
             provider: Provider
             numberOfImages?: number
             testId?: string
diff --git a/testing/e2e/src/routes/api.video.stream.ts b/testing/e2e/src/routes/api.video.stream.ts
index 33643bd02..88eb1a189 100644
--- a/testing/e2e/src/routes/api.video.stream.ts
+++ b/testing/e2e/src/routes/api.video.stream.ts
@@ -1,6 +1,7 @@
 import { createFileRoute } from '@tanstack/react-router'
 import { generateVideo, toHttpResponse } from '@tanstack/ai'
 import { createVideoAdapter } from '@/lib/media-providers'
+import type { MediaPrompt } from '@tanstack/ai'
 import type { Provider } from '@/lib/types'
 
 export const Route = createFileRoute('/api/video/stream')({
@@ -12,7 +13,7 @@ export const Route = createFileRoute('/api/video/stream')({
         const body = await request.json()
         const data = body.forwardedProps ?? body.data ?? body
         const { prompt, provider, testId, aimockPort } = data as {
-          prompt: string
+          prompt: MediaPrompt
           provider: Provider
           testId?: string
           aimockPort?: number
diff --git a/testing/e2e/src/routes/api.video.ts b/testing/e2e/src/routes/api.video.ts
index e50d9cb87..a9b0903ec 100644
--- a/testing/e2e/src/routes/api.video.ts
+++ b/testing/e2e/src/routes/api.video.ts
@@ -1,6 +1,7 @@
 import { createFileRoute } from '@tanstack/react-router'
 import { generateVideo, toServerSentEventsResponse } from '@tanstack/ai'
 import { createVideoAdapter } from '@/lib/media-providers'
+import type { MediaPrompt } from '@tanstack/ai'
 import type { Provider } from '@/lib/types'
 
 export const Route = createFileRoute('/api/video')({
@@ -12,7 +13,7 @@ export const Route = createFileRoute('/api/video')({
         const body = await request.json()
         const data = body.forwardedProps ?? body.data ?? body
         const { prompt, provider, testId, aimockPort } = data as {
-          prompt: string
+          prompt: MediaPrompt
           provider: Provider
           testId?: string
           aimockPort?: number
diff --git a/testing/e2e/tests/image-to-image.spec.ts b/testing/e2e/tests/image-to-image.spec.ts
new file mode 100644
index 000000000..e4608d6af
--- /dev/null
+++ b/testing/e2e/tests/image-to-image.spec.ts
@@ -0,0 +1,105 @@
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { test, expect } from './fixtures'
+import {
+  fillPrompt,
+  clickGenerate,
+  waitForGenerationComplete,
+  featureUrl,
+} from './helpers'
+import { providersFor } from './test-matrix'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const testImagePath = path.resolve(__dirname, '../test-assets/guitar-shop.png')
+
+// Image-conditioned generation: the prompt is sent as multimodal parts
+// (text + attached image). For OpenAI this routes generateImage() to the
+// multipart /v1/images/edits endpoint instead of /v1/images/generations,
+// exercising the imagePartToFile upload path end-to-end.
+for (const provider of providersFor('image-to-image')) {
+  test.describe(`${provider} -- image-to-image`, () => {
+    test('sse -- edits an image via SSE connection', async ({
+      page,
+      request,
+      testId,
+      aimockPort,
+    }) => {
+      await page.goto(
+        featureUrl(provider, 'image-to-image', testId, aimockPort, 'sse'),
+      )
+      // Cold vite compiles of this route can delay hydration past fillPrompt's
+      // fallback; wait for the page to settle before interacting.
+      await page.waitForLoadState('networkidle')
+      await fillPrompt(page, 'add a tree to this product photo')
+      await page.getByTestId('image-input').setInputFiles(testImagePath)
+      await clickGenerate(page)
+      await waitForGenerationComplete(page)
+      const images = page.getByTestId('generated-image')
+      await expect(images).toHaveCount(1)
+
+      // The fixture matches on prompt text regardless of endpoint, so also
+      // prove the adapter routed to the multipart edits endpoint (and didn't
+      // silently drop the image part and call /v1/images/generations).
+      const journalRes = await request.get(
+        `http://127.0.0.1:${aimockPort}/v1/_requests`,
+      )
+      const entries = (await journalRes.json()) as Array<{
+        path?: string
+        body?: unknown
+      }>
+      const editEntry = entries.find(
+        (e) =>
+          e.path === '/v1/images/edits' &&
+          JSON.stringify(e.body ?? '').includes(
+            'add a tree to this product photo',
+          ),
+      )
+      expect(editEntry).toBeTruthy()
+    })
+
+    test('http-stream -- edits an image via HTTP stream', async ({
+      page,
+      testId,
+      aimockPort,
+    }) => {
+      await page.goto(
+        featureUrl(
+          provider,
+          'image-to-image',
+          testId,
+          aimockPort,
+          'http-stream',
+        ),
+      )
+      // Cold vite compiles of this route can delay hydration past fillPrompt's
+      // fallback; wait for the page to settle before interacting.
+      await page.waitForLoadState('networkidle')
+      await fillPrompt(page, 'add a tree to this product photo')
+      await page.getByTestId('image-input').setInputFiles(testImagePath)
+      await clickGenerate(page)
+      await waitForGenerationComplete(page)
+      const images = page.getByTestId('generated-image')
+      await expect(images).toHaveCount(1)
+    })
+
+    test('fetcher -- edits an image via server function', async ({
+      page,
+      testId,
+      aimockPort,
+    }) => {
+      await page.goto(
+        featureUrl(provider, 'image-to-image', testId, aimockPort, 'fetcher'),
+      )
+      // Cold vite compiles of this route can delay hydration past fillPrompt's
+      // fallback; wait for the page to settle before interacting.
+      await page.waitForLoadState('networkidle')
+      await fillPrompt(page, 'add a tree to this product photo')
+      await page.getByTestId('image-input').setInputFiles(testImagePath)
+      await clickGenerate(page)
+      await waitForGenerationComplete(page)
+      const images = page.getByTestId('generated-image')
+      await expect(images).toHaveCount(1)
+    })
+  })
+}
diff --git a/testing/e2e/tests/image-to-video.spec.ts b/testing/e2e/tests/image-to-video.spec.ts
new file mode 100644
index 000000000..951067953
--- /dev/null
+++ b/testing/e2e/tests/image-to-video.spec.ts
@@ -0,0 +1,103 @@
+import path from 'path'
+import { fileURLToPath } from 'url'
+import { test, expect } from './fixtures'
+import {
+  fillPrompt,
+  clickGenerate,
+  waitForGenerationComplete,
+  featureUrl,
+} from './helpers'
+import { providersFor } from './test-matrix'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+const testImagePath = path.resolve(__dirname, '../test-assets/guitar-shop.png')
+
+// Image-to-video: the prompt is sent as multimodal parts (text + attached
+// image). For OpenAI/Sora the image part is uploaded as `input_reference`,
+// which switches the SDK to a multipart POST /v1/videos — exercising the
+// imagePartToFile conversion and job polling flow end-to-end.
+for (const provider of providersFor('image-to-video')) {
+  test.describe(`${provider} -- image-to-video`, () => {
+    test('sse -- animates an image via SSE connection', async ({
+      page,
+      request,
+      testId,
+      aimockPort,
+    }) => {
+      await page.goto(
+        featureUrl(provider, 'image-to-video', testId, aimockPort, 'sse'),
+      )
+      // Cold vite compiles of this route can delay hydration past fillPrompt's
+      // fallback; wait for the page to settle before interacting.
+      await page.waitForLoadState('networkidle')
+      await fillPrompt(page, 'animate this product photo')
+      await page.getByTestId('image-input').setInputFiles(testImagePath)
+      await clickGenerate(page)
+      await waitForGenerationComplete(page, 60_000)
+      const video = page.getByTestId('generated-video')
+      await expect(video).toBeVisible()
+
+      // Prove the multipart POST /v1/videos round-tripped with the prompt
+      // text intact — the SDK switches to multipart when `input_reference`
+      // carries a File, and aimock extracts `prompt` from the form data.
+      const journalRes = await request.get(
+        `http://127.0.0.1:${aimockPort}/v1/_requests`,
+      )
+      const entries = (await journalRes.json()) as Array<{
+        path?: string
+        body?: unknown
+      }>
+      const videoEntry = entries.find(
+        (e) =>
+          e.path === '/v1/videos' &&
+          JSON.stringify(e.body ?? '').includes('animate this product photo'),
+      )
+      expect(videoEntry).toBeTruthy()
+    })
+
+    test('http-stream -- animates an image via HTTP stream', async ({
+      page,
+      testId,
+      aimockPort,
+    }) => {
+      await page.goto(
+        featureUrl(
+          provider,
+          'image-to-video',
+          testId,
+          aimockPort,
+          'http-stream',
+        ),
+      )
+      // Cold vite compiles of this route can delay hydration past fillPrompt's
+      // fallback; wait for the page to settle before interacting.
+      await page.waitForLoadState('networkidle')
+      await fillPrompt(page, 'animate this product photo')
+      await page.getByTestId('image-input').setInputFiles(testImagePath)
+      await clickGenerate(page)
+      await waitForGenerationComplete(page, 60_000)
+      const video = page.getByTestId('generated-video')
+      await expect(video).toBeVisible()
+    })
+
+    test('fetcher -- animates an image via server function', async ({
+      page,
+      testId,
+      aimockPort,
+    }) => {
+      await page.goto(
+        featureUrl(provider, 'image-to-video', testId, aimockPort, 'fetcher'),
+      )
+      // Cold vite compiles of this route can delay hydration past fillPrompt's
+      // fallback; wait for the page to settle before interacting.
+      await page.waitForLoadState('networkidle')
+      await fillPrompt(page, 'animate this product photo')
+      await page.getByTestId('image-input').setInputFiles(testImagePath)
+      await clickGenerate(page)
+      await waitForGenerationComplete(page, 60_000)
+      const video = page.getByTestId('generated-video')
+      await expect(video).toBeVisible()
+    })
+  })
+}