> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/mcp/recipes/image-to-video.md).

# Turn a product photo into video

Ask your agent to animate a product photo with FLORA MCP, from a public image URL or from an image already on a FLORA canvas.

Give your agent a product photo and a motion brief, and [FLORA MCP](https://flora.ai/mcp) returns a short video clip on your canvas. Use this recipe when the video starts from an existing image; to make a video from text alone, use [Generate an image or video](https://docs.flora.ai/mcp/recipes/generate.md).

**Works in:** Claude · Claude Code · ChatGPT · Codex · Cursor

**You need:** a connected client and about $0.71 per 5-second clip (Kling 3.0 Pro at 1080p)

**Use when:** you have a photo (a URL, an uploaded file, or an image node on a canvas) and want it to move.

**Don't use when:** you want a still image (use [generate](https://docs.flora.ai/mcp/recipes/generate.md)), or your team has a saved motion Technique (use [run a Technique](https://docs.flora.ai/mcp/recipes/run-a-technique.md)).

**Which Kling:** when you say "Kling", this recipe uses Kling 3.0 Pro (`i2v-kling-v3-pro`). Other Kling versions and their IDs are in [Model names to IDs](https://docs.flora.ai/mcp/recipes/generate.md#model-names-to-ids).

## Ask your agent

> Use FLORA to turn this product photo into a 5-second video: slow push-in, soft morning light, steam rising from the mug. Use Kling 3.0 Pro and put it in my "Mug launch" project. Show me the cost first and wait for my OK. Photo: \[paste the image URL or attach the photo]

<a href="https://claude.ai/new?q=Use%20FLORA%20to%20turn%20this%20product%20photo%20into%20a%205-second%20video%3A%20slow%20push-in%2C%20soft%20morning%20light%2C%20steam%20rising%20from%20the%20mug.%20Use%20Kling%203.0%20Pro%20and%20put%20it%20in%20my%20%22Mug%20launch%22%20project.%20Show%20me%20the%20cost%20first%20and%20wait%20for%20my%20OK.%20Photo%3A%20%5Bpaste%20the%20image%20URL%20or%20attach%20the%20photo%5D" class="button primary">Open in Claude</a> <a href="https://chatgpt.com/?q=Use%20FLORA%20to%20turn%20this%20product%20photo%20into%20a%205-second%20video%3A%20slow%20push-in%2C%20soft%20morning%20light%2C%20steam%20rising%20from%20the%20mug.%20Use%20Kling%203.0%20Pro%20and%20put%20it%20in%20my%20%22Mug%20launch%22%20project.%20Show%20me%20the%20cost%20first%20and%20wait%20for%20my%20OK.%20Photo%3A%20%5Bpaste%20the%20image%20URL%20or%20attach%20the%20photo%5D" class="button secondary">Open in ChatGPT</a>

## What the agent does

There are two paths. Pick by where the photo lives.

| The photo is…                                                               | Path                                              | Tools                                                |
| --------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------- |
| A public HTTPS URL, a file shared in the chat, or an uploaded asset's `url` | [1. Photo URL](#path-1-a-photo-url)               | `flora_create_generations`                           |
| An image node already on a FLORA canvas                                     | [2. Canvas image](#path-2-an-image-on-the-canvas) | `flora_add_to_canvas`, then `flora_run_canvas_nodes` |

{% hint style="warning" %}
`flora_create_generations` does not take canvas images as video input. Passing `reference_node_ids` with a video model returns an `input_validation_error` (HTTP 400). Use one of the two paths below instead.
{% endhint %}

{% hint style="warning" %}
**Cost rule.** Price first: call `flora_create_generations` with `quote: true` and show the user the cost in US dollars. Run the same request without `quote` only after they approve. On `insufficient_credits` or any `BILLING_*` error, stop and pass the message on. Don't retry. Check balance and spend with `flora_get_usage`. A failed run isn't charged; a retry is a new run and is billed again.
{% endhint %}

{% hint style="info" %}
**Polling rule.** Save every `run_id`. Wait at least 15 seconds between polls, or 2 seconds per run for bigger batches (40 seconds for 20 runs). Then read every `run_id` in one `flora_list_generations` call (up to 20 per call). For example: `flora_list_generations({"run_ids": ["run_a", "run_b"]})`. For Technique runs, also pass `"technique_id"`. Polling faster returns `429` or cooldown errors with `retry_after_seconds`.
{% endhint %}

### Before either path: find the workspace and project

1. **`flora_list_workspaces`**. If it returns `current_workspace_id`, use that workspace. If several come back and none is current, the agent names them and asks which one to bill.
2. **`flora_list_projects`** with that `workspace_id` (and `query` to match a name such as "Mug launch"), or **`flora_create_project`** to make one:

   ```json
   {
     "workspace_id": "ws_123",
     "name": "Mug launch"
   }
   ```

   Either way the agent now has the `project_id` (for example `prj_abc`) that both paths need. For path 2, the project is the one whose canvas holds the image.

### Path 1: a photo URL

1. **`flora_list_models`** with the video model's `model_id`, to read its image field. Image-to-video models name it in `params`: most take one image as `image_url`; a few take several as `image_urls`. Use exactly the name it reports.

   ```json
   { "model_id": "i2v-kling-v3-pro" }
   ```

   For Kling 3.0 Pro the response lists `image_url`, `duration` (`"3"` to `"15"`, default `"5"`) and `resolution` (`"1080p"` or `"4k"`).
2. **`flora_create_generations`** with `quote: true` to price it, then again without `quote` once you approve. The photo URL goes in `params`:

   ```json
   {
     "generations": [
       {
         "project_id": "prj_abc",
         "type": "video",
         "prompt": "Slow push-in on the mug, soft morning light, a thin curl of steam rising, camera stays level",
         "model": "i2v-kling-v3-pro",
         "params": {
           "image_url": "https://media.flora.ai/…/mug.jpg",
           "duration": "5",
           "resolution": "1080p"
         }
       }
     ]
   }
   ```

   The quote (the same call with `"quote": true` at the top level) starts nothing and returns one entry per item, without a `run_id`:

   ```json
   {
     "generations": [
       {
         "index": 0,
         "ok": true,
         "type": "generation_quote",
         "model": { "model_id": "i2v-kling-v3-pro" },
         "estimated_cost": 0.7056,
         "currency": "USD",
         "is_estimate": true,
         "quoted_at": "2026-10-11T18:00:00Z",
         "expires_at": "2026-10-11T18:05:00Z",
         "assumptions": []
       }
     ]
   }
   ```

   `estimated_cost` is in US dollars for these exact `params`; the agent shows it to you and waits. `assumptions` lists anything the estimate had to assume. Quotes expire after 5 minutes (`expires_at`), so after a long pause the agent quotes again. The quote is an estimate, not a price lock. Without `quote`, the same call returns a `run_id`, `node_id`, `canvas_url`, `project_id`, `poll_url`, a `charged_cost` estimate in US dollars and `estimated_seconds` (for Kling 3.0 Pro image-to-video, about 255, a little over 4 minutes). Use `estimated_seconds` to decide when to make the first poll.

   Any public `https://` URL that serves the image file directly works here; generations have no FLORA host allowlist (unlike Technique inputs). FLORA hands the URL to the model provider, which downloads it, so a host that blocks outside requests (login walls, hotlink protection, 401/403/404) makes the run fail. For those, or for a photo on your computer, upload it first with [Upload your own images, video and files](https://docs.flora.ai/mcp/recipes/upload-files.md) and use the asset's `url` (on `media.flora.ai`, which always works).
3. **`flora_list_generations`**, following the polling rule, with the `run_id` from the create response:

   ```json
   { "run_ids": ["run_…"] }
   ```

   The finished clip is in `outputs[].url`, and a video node appears on the canvas.

### Path 2: an image on the canvas

1. **`flora_get_canvas`** to find the image node's short ID (for example `n7`).
2. **Price it.** `flora_run_canvas_nodes` starts billing immediately and has no quote step. The agent quotes the same model with `flora_create_generations` and `quote: true`, putting the image's output URL from `flora_get_canvas` in `image_url`, or reads `estimated_cost_usd` for default settings from `flora_list_models`. Then it waits for your OK.
3. **`flora_add_to_canvas`** to add a video node wired to the image. The `ref` is your own handle for this call; `connect` draws the edge that feeds the image into the video model. Don't put the image URL in `params`; the edge supplies it.

   ```json
   {
     "project_id": "prj_abc",
     "idempotency_key": "mug-clip-1",
     "add": [
       {
         "ref": "clip",
         "type": "video",
         "prompt": "Slow push-in on the mug, soft morning light, a thin curl of steam rising, camera stays level",
         "model": "i2v-kling-v3-pro",
         "params": { "duration": "5", "resolution": "1080p" }
       }
     ],
     "connect": [
       { "from": "n7", "to": "clip" }
     ]
   }
   ```

   The response's `created` map gives the new node's real IDs:

   ```json
   {
     "created": {
       "clip": { "id": "n15", "node_id": "3c1e9b2a-5d7f-4e8a-9b0c-1d2e3f4a5b6c" }
     }
   }
   ```

   Adding the node does not run it.
4. **`flora_run_canvas_nodes`** with the short ID from `created` (never your `ref`):

   ```json
   {
     "project_id": "prj_abc",
     "node_ids": ["n15"]
   }
   ```

   Each entry in `runs` has `status: "started"` and a `run_id`, or `status: "skipped"` and a `reason` such as `no_model_configured`. Skipped nodes are not charged.
5. **`flora_list_generations`**, following the polling rule, with the `run_id` from the `runs` entry:

   ```json
   { "run_ids": ["run_…"] }
   ```

To animate several canvas images, add one video node per image in a single `flora_add_to_canvas` call, then run all their short IDs in one `flora_run_canvas_nodes` call (up to 50).

## How long it takes

Video takes minutes, not seconds. Most video models take 2 to 5 minutes, and the slowest take up to about 26 minutes. Read `estimated_seconds` in `flora_list_models` for the model you picked: Kling 3.0 Pro estimates about 4 minutes for image-to-video. While a clip renders, poll every 30 to 60 seconds; faster polling doesn't make it finish sooner.

## Check it worked

* The run reaches `status: "completed"` with an `outputs[].url` of type `videoUrl`.
* On the canvas, the video node sits next to the source image (path 2 also shows the edge between them).

## If it fails

| Symptom                                                  | Cause                                                                                             | Fix                                                                                   |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| `input_validation_error` from `flora_create_generations` | `reference_node_ids` was passed with a video model                                                | Use path 1 (URL in `image_url`) or path 2 (video node plus `flora_run_canvas_nodes`). |
| `skipped` with `node_not_found`                          | A `ref` was passed to `flora_run_canvas_nodes`                                                    | Pass the short ID or `node_id` from the `created` map.                                |
| Only the first of several photos was used                | The model takes one image (`image_url`); FLORA folds an `image_urls` list down to its first entry | Pass one photo, or use a model whose `flora_list_models` entry lists `image_urls`.    |
| Error fetching the image URL                             | The host blocks outside requests, or the URL is a web page                                        | Upload the file with `flora_create_asset` and use the returned `url`.                 |
| Polls return `429` or `retry_after_seconds`              | Polling too often                                                                                 | Wait the stated time; video needs no more than one poll every 30 to 60 seconds.       |

Shapes for every argument are in the tools reference: [`flora_add_to_canvas`](https://docs.flora.ai/mcp/tools/canvas.md#flora_add_to_canvas), [`flora_run_canvas_nodes`](https://docs.flora.ai/mcp/tools/canvas.md#flora_run_canvas_nodes) and [`flora_create_generations`](https://docs.flora.ai/mcp/tools/generations.md#flora_create_generations).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flora.ai/mcp/recipes/image-to-video.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
