# An image-to-video API to animate a product photo

> Submit a product photo to an image-to-video job API to render smooth 720p promotional clips with permanent file storage on a single API key.

**The best way to animate a product photo with an API is to submit an asynchronous video job to `POST /v1/ai/jobs` specifying your source image link, a prompt describing the movement, and a video model like `vibiz/video`.** thelastapi provides a unified media gateway where you can animate static product shots into six-second 720p MP4 clips or call advanced models by id on a single balance. Every rendered video is saved automatically to your project's permanent file storage, so you can display animations across your storefront without running separate asset hosting pipelines.

This guide walks through using the image-to-video API, choosing between model tiers, and managing generated animation files.

## Why use an image-to-video API for product marketing?

Static product photography often struggles to convey texture, scale, and lighting in online storefronts. Converting those stills into short animations—such as a 360-degree turntable rotation, steam rising from coffee beans, or dynamic studio lighting sweeping across a watch face—improves engagement and conversion rates.

Using a unified media API for product animation provides three main benefits over separate vendor accounts:

- **Single authentication and balance.** Video models are compute-heavy and normally require separate accounts, minimum top-up commitments, and bespoke client libraries. With thelastapi, you call image, video, and language models with one account key or project key.
- **Automated permanent hosting.** Video generation produces heavy MP4 files. Most inference endpoints return temporary download links that expire within minutes. thelastapi automatically saves every generated video into your project's [Files](https://thelastapi.dev/docs/files) store with a permanent URL.
- **Model variety without refactoring.** You can prototype with the default `vibiz/video` tier or specify exact lab models (such as Kling, Seedance, Veo, Hailuo, or Wan) using the exact same request structure.

To explore the entire media lineup, see our overview of [one API for image, video and voice AI models](https://thelastapi.dev/blog/one-api-image-video-voice-models).

## How image-to-video works: jobs, models, and aspect ratios

Video synthesis takes time. Rather than maintaining an open HTTP connection for tens of seconds, video generation runs asynchronously via the `/v1/ai/jobs` endpoint. You submit a job, receive an immediate `202 Accepted` response with a job ID, and poll the job until its status is complete.

### Built-in models vs. models by ID

You have two ways to pick a video model on the [AI gateway](https://thelastapi.dev/docs/ai):

1. **The default thelastapi model (`vibiz/video`):** This model runs LTX-2.5 Fast (Lightricks). It generates 6-second clips at 720p resolution with sound, priced at $0.54 per video. It accepts a text prompt, an optional `image_url` for image-to-video animation, and an aspect ratio.
2. **Specialized media models by ID:** You can query the catalog for video models from labs like Kling, Seedance, Veo, Hailuo, or Wan using `GET /v1/ai/media-models`. These models run by their specific identifier (such as `kling-video/v2.1/master/image-to-video`) and accept custom parameters inside a `model_input` block.

| Model identifier | Underlying engine | Capabilities | Price |
| --- | --- | --- | --- |
| `vibiz/video` | LTX-2.5 Fast (Lightricks) | 6-second clips at 720p with sound, text-to-video or image-to-video | $0.54 per video |
| `kling-video/v2.1/master/image-to-video` | Kling | Configurable duration, high-fidelity motion | Live catalog price |
| Seedance / Veo / Hailuo / Wan | Lab models by ID | Cinematic, motion-heavy product animations | Live catalog price |

### Supported aspect ratios

Product videos require different dimensions depending on where they will be embedded:

- `16:9`: Standard widescreen, ideal for desktop web banners and product detail hero sections.
- `9:16`: Vertical format, ideal for mobile commerce, stories, and social feed ads.

Note that if you pass `1:1`, the API maps the output to `16:9`.

## Animating a product photo from the command line

You can test product animations directly in your terminal using the `vibiz` CLI.

First, upload your high-resolution product still to your project's file storage:

```bash
vibiz files upload sneakers.png --folder products
```

This returns a permanent public URL, such as `https://thelastapi.dev/f/Qm9x.../sneakers.png`. Now pass that URL to the `vibiz video` command with an animation prompt:

```bash
vibiz video "Smooth cinematic camera rotation around the running shoe, studio lighting reflections" \
  --from-image https://thelastapi.dev/f/Qm9x.../sneakers.png \
  --aspect 9:16 \
  -o sneaker-animation.mp4
```

The CLI submits the job, tracks its status until rendering finishes, and writes the resulting MP4 directly to your local disk.

## Animating product photos in code

To integrate automated video generation into an inventory management pipeline, backend worker, or e-commerce catalog, use the HTTP API or the `@vibiz/app` SDK.

### Step 1: Submit the video generation job

Make a `POST` request to `https://thelastapi.dev/v1/ai/jobs`. Provide the target model, the source `image_url`, the desired aspect ratio, and a descriptive prompt:

```bash
curl https://thelastapi.dev/v1/ai/jobs \
  -H "Authorization: Bearer $VIBIZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "video",
    "model": "vibiz/video",
    "input": {
      "prompt": "Camera slowly dollies forward as warm golden hour sunlight glints across the glass perfume bottle",
      "image_url": "https://thelastapi.dev/f/Qm9x.../perfume.png",
      "aspect_ratio": "16:9"
    }
  }'
```

The server returns `202 Accepted` with a job payload:

```json
{
  "id": "job_01k8v92j...",
  "status": "pending",
  "type": "video",
  "model": "vibiz/video",
  "created_at": "2026-10-28T14:20:00.000Z"
}
```

### Step 2: Poll for completion

Poll the job endpoint using the returned ID:

```bash
curl https://thelastapi.dev/v1/ai/jobs/job_01k8v92j... \
  -H "Authorization: Bearer $VIBIZ_API_KEY"
```

Once the job status changes to `completed`, the response includes the file metadata and a permanent asset link inside `output.data[0]`:

```json
{
  "id": "job_01k8v92j...",
  "status": "completed",
  "output": {
    "data": [
      {
        "url": "https://thelastapi.dev/f/abc123xyz.../2026-10-28-camera-slowly-dollies.mp4",
        "file_id": "file_01k8v98...",
        "file_url": "https://thelastapi.dev/f/abc123xyz.../2026-10-28-camera-slowly-dollies.mp4"
      }
    ]
  },
  "cost_micro_usd": 540000
}
```

Because this call ran under a project, `url` is a permanent link and `expires_at` is `null`.

### Calling custom video models with Node.js

If you want to use a specific model like Kling, inspect the catalog using `GET /v1/ai/media-models?q=kling` or `vibiz.ai.mediaModels({ q: 'kling' })` to view pricing and parameters, then use the SDK to run the job:

```ts
import { vibiz } from '@vibiz/app';

const job = await vibiz.ai.jobs.create({
  type: 'video',
  model: 'kling-video/v2.1/master/image-to-video',
  input: {
    prompt: 'Gentle studio spotlight movement revealing watch dial texture',
    image_url: 'https://thelastapi.dev/f/Qm9x.../luxury-watch.png',
    model_input: {
      duration: '10'
    }
  }
});

console.log('Video job created:', job.id);
```

The gateway accepts up to 16 KB of model-specific arguments inside `model_input`, letting you adjust parameters like duration while billing directly against your account credits.

## Preparing the source still before animation

Image-to-video models work best when the source still is sharp and correctly framed. If your raw product image has unwanted clutter or poor background contrast, you can clean it up before passing it to the video engine.

You can edit the photo programmatically using `POST /v1/ai/images/generations` with `vibiz/image` (Nano Banana 2) or `vibiz/image-text` (GPT-5.4 Image 2). Pass the raw image URL in the `image_url` field and describe the changes you need:

```bash
vibiz image "Place this watch on a minimalist dark slate pedestal with soft rim lighting" \
  --from-image https://thelastapi.dev/f/Qm9x.../raw-watch.png \
  -o prepared-watch.png
```

Learn more about source image transformations in our guide on [an AI photo editing API that starts from your photo](https://thelastapi.dev/blog/ai-photo-editing-api-reference-image), or explore generation prompts in [an image generation API for developers: Nano Banana and GPT Image on one key](https://thelastapi.dev/blog/image-generation-api-developers).

## Storing and serving product videos

Handling video assets usually involves moving files between rendering services, storage buckets, and content distribution networks. With thelastapi, this process is automated:

- **Saved upon generation:** Every video created by `vibiz/video` or third-party video models is saved directly to your project's [Files](https://thelastapi.dev/docs/files) store.
- **Permanent, guess-proof URLs:** Public file URLs use random 32-character keys (`https://thelastapi.dev/f/<key>/<name>.mp4`). They do not expire, require no authentication headers, and can be embedded directly in storefront HTML:
  ```html
  <video autoplay loop muted playsinline src="https://thelastapi.dev/f/abc123xyz.../sneaker.mp4"></video>
  ```
- **Byte seeking:** Files are served with `Accept-Ranges: bytes` and `Content-Disposition: inline`, allowing browsers to smoothly stream and seek within MP4 clips.
- **CLI management:** You can inspect or search recent product video generations at any time:
  ```bash
  vibiz files latest --type video
  vibiz files search "sneakers"
  ```

Calls made with a development key save assets to your project's development Files environment, while calls made with production keys save directly to production.

## Next steps

To start animating your product catalog, initialize a project with AI enabled:

```bash
vibiz init "Product Studio" --resources ai
vibiz dev
```

Inspect `GET /v1/ai/media-models` to explore available video engines, upload your first product still with `vibiz files upload`, and submit an animation job using the `vibiz video` command.

## Frequently asked questions

### How much does it cost to animate a photo using the default video model?

The default `vibiz/video` tier runs LTX-2.5 Fast (Lightricks) and costs $0.54 per video for a 6-second, 720p clip with sound. Specialized third-party models run at their live catalog rate.

### Do generated video links expire?

Videos generated with a project API key are saved permanently in project Files and do not expire. Calls made under an account key without an associated project return temporary URLs that expire after 24 hours.

### What aspect ratios are supported for product video animations?

Video generation supports `16:9` widescreen and `9:16` vertical formats. If you request a `1:1` aspect ratio, the API returns a `16:9` video.

### Can I use specialized video models like Kling with the same API?

Yes. You can find model identifiers with `GET /v1/ai/media-models?q=kling` and pass names like `kling-video/v2.1/master/image-to-video` into `POST /v1/ai/jobs` with custom parameters in `model_input`.

### What happens if an image-to-video job fails?

If a provider is unreachable or rejects the input, the API returns a structured error code such as `provider_unavailable` or `invalid_request` with details, and charges are not deducted for unfulfilled runs.

---

Published 2026-11-15 · https://thelastapi.dev/blog/image-to-video-api-product-animation
