---
title: "Image to Video"
description: "Turn a still image into a video clip with the PixAI API. Upload or reuse an image, set the first and last frame, add sound, and download the MP4."
canonical: "https://platform.pixai.art/en/docs/quick-start/examples/image-to-video"
last-updated: "2026-11-17"
---

# Image to Video

Turn a still image into a video clip with the PixAI API. Upload or reuse an image, set the first and last frame, add sound, and download the MP4.





`POST /v2/frame-video/create` animates an image with PixAI's Tsubaki video model. The clip starts on the image you give it and, if you send a second image, ends on that one. Use it to bring an illustration to life, to make a transition between two images, or to make a loop.

Base URL: `https://api.pixai.art/v2`. Send `Authorization: Bearer YOUR_API_KEY` with every request; see [How can I use PixAI API?](/en/docs/quick-start/enroll-in-api) to get a key.

<Callout type="info">
  Image-to-video needs a PixAI membership. Credits are charged when the task is created, and a video takes a few minutes to finish.
</Callout>

Steps [#steps]

<div className="fd-steps">
  <div className="fd-step">
    Get a media ID for the image [#get-a-media-id-for-the-image-step]

    Video frames are media IDs. An image you generated with the API already has one: it is in `outputs.mediaIds` of the finished task, so you can skip to the next step.

    To use your own file, upload it in three calls. First ask for an upload URL:

    ```bash
    curl -X POST https://api.pixai.art/v2/media/image/upload-url \
      -H "Authorization: Bearer $PIXAI_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{}'
    ```

    ```json
    {
      "uploadUrl": "https://...",
      "externalId": "3f2b8c1e-6a4d-4f6e-9b1a-2c7d5e8f9a01"
    }
    ```

    `PUT` the raw bytes of the file to `uploadUrl` with its real `Content-Type`, not as a multipart form:

    ```bash
    curl -X PUT "UPLOAD_URL" \
      -H "Content-Type: image/png" \
      --data-binary @first-frame.png
    ```

    Then register the upload. The `id` in the response is the media ID:

    ```bash
    curl -X POST https://api.pixai.art/v2/media/image/register \
      -H "Authorization: Bearer $PIXAI_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"externalId": "3f2b8c1e-6a4d-4f6e-9b1a-2c7d5e8f9a01"}'
    ```
  </div>

  <div className="fd-step">
    Create the video task [#create-the-video-task-step]

    Send the media ID as `firstFrameMediaId`, and say in `prompt` what should happen:

    ```bash
    curl -X POST https://api.pixai.art/v2/frame-video/create \
      -H "Authorization: Bearer $PIXAI_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "model": "tbkv1.0.1",
        "firstFrameMediaId": "MEDIA_ID",
        "prompt": "she turns around and smiles, hair blowing in the wind",
        "duration": 5
      }'
    ```

    The response is a task with `status: "waiting"`. Keep its `id`.
  </div>

  <div className="fd-step">
    Wait for the task to finish [#wait-for-the-task-to-finish-step]

    Poll `GET /v2/task/{id}` every few seconds until `status` is `completed`, `failed` or `cancelled`:

    ```bash
    curl https://api.pixai.art/v2/task/TASK_ID \
      -H "Authorization: Bearer $PIXAI_API_KEY"
    ```

    A finished video task has the video in `outputs.videoMediaId`. `outputs.mediaIds` holds only its poster image.

    ```json
    {
      "id": "TASK_ID",
      "status": "completed",
      "taskKind": "i2v-inhouse",
      "outputs": {
        "videoMediaId": "VIDEO_MEDIA_ID",
        "mediaIds": ["POSTER_MEDIA_ID"]
      }
    }
    ```
  </div>

  <div className="fd-step">
    Download the video [#download-the-video-step]

    Resolve the video's media ID with `GET /v2/media/batch` and download its `fileUrl`, an MP4:

    ```bash
    curl "https://api.pixai.art/v2/media/batch?ids=VIDEO_MEDIA_ID" \
      -H "Authorization: Bearer $PIXAI_API_KEY"
    curl -L "FILE_URL" -o video.mp4
    ```

    <Callout type="warn">
      Generated media is not kept forever. Download the video soon after the task finishes.
    </Callout>
  </div>
</div>

Options [#options]

| Field              | What it does                                                                                                   |
| :----------------- | :------------------------------------------------------------------------------------------------------------- |
| `model`            | `tbkv1.0.1` is the latest Tsubaki video model; `tbkv1.0` is the previous one.                                  |
| `lastFrameMediaId` | The image the clip ends on. Send the first frame again to make a loop.                                         |
| `duration`         | 5 to 15 whole seconds. Defaults to 5.                                                                          |
| `mode`             | `basic` (default) or `professional`, which adds a 1080p upscale on `tbkv1.0.1` and costs more.                 |
| `generateAudio`    | Whether to generate a soundtrack. Defaults to `true`.                                                          |
| `audioLanguage`    | The language of speech in the soundtrack: `english`, `japanese`, `korean`, `chinese`, or `none` for no speech. |

The video keeps the first frame's aspect ratio. A frame owned by another user is refused with `400 INVALID_REFERENCE_MEDIA`.

<Callout type="info">
  To make a new shot that draws on several images, video clips or audio instead of starting on an exact frame, use [`POST /v2/reference-video/create`](/en/docs/api-v2/video/createReferenceVideo). It also offers other video models, such as Seedance 2 and Vidu.
</Callout>

Full script [#full-script]

Upload a local image, animate it, and save the MP4. Set `PIXAI_API_KEY` in your environment first.

<Tabs items="['Python', 'JavaScript']">
  <Tab value="Python">
    With `requests` installed:

    ```python
    import os
    import time

    import requests

    API = "https://api.pixai.art/v2"
    HEADERS = {"Authorization": f"Bearer {os.environ['PIXAI_API_KEY']}"}


    def upload_image(path, content_type="image/png"):
        """Upload a local image and return its media ID."""
        target = requests.post(f"{API}/media/image/upload-url", headers=HEADERS, json={})
        target.raise_for_status()
        target = target.json()
        with open(path, "rb") as f:
            put = requests.put(target["uploadUrl"], data=f, headers={"Content-Type": content_type})
        put.raise_for_status()
        media = requests.post(
            f"{API}/media/image/register",
            headers=HEADERS,
            json={"externalId": target["externalId"]},
        )
        media.raise_for_status()
        return media.json()["id"]


    def wait_for(task_id, interval=5):
        """Poll a task until it finishes and return it."""
        while True:
            resp = requests.get(f"{API}/task/{task_id}", headers=HEADERS)
            if resp.status_code != 404:  # A new task can answer 404 for a moment. Keep polling.
                resp.raise_for_status()
                task = resp.json()
                if task["status"] not in ("waiting", "running"):
                    return task
            time.sleep(interval)


    first_frame = upload_image("first-frame.png")

    resp = requests.post(
        f"{API}/frame-video/create",
        headers=HEADERS,
        json={
            "model": "tbkv1.0.1",
            "firstFrameMediaId": first_frame,
            "prompt": "she turns around and smiles, hair blowing in the wind",
            "duration": 5,
        },
    )
    resp.raise_for_status()
    task = wait_for(resp.json()["id"])

    if task["status"] != "completed":
        raise SystemExit(f"Task ended as {task['status']}: {task.get('taskStatusMsgI18n')}")

    video_id = task["outputs"]["videoMediaId"]
    media = requests.get(f"{API}/media/batch", headers=HEADERS, params={"ids": video_id})
    media.raise_for_status()
    video = next(m for m in media.json() if m["id"] == video_id)

    with open("video.mp4", "wb") as f:
        f.write(requests.get(video["fileUrl"]).content)
    ```
  </Tab>

  <Tab value="JavaScript">
    For Node.js 20 or later, saved as `video.mjs`:

    ```js
    import { readFile, writeFile } from 'node:fs/promises';

    const API = 'https://api.pixai.art/v2';
    const HEADERS = {
      Authorization: `Bearer ${process.env.PIXAI_API_KEY}`,
      'Content-Type': 'application/json',
    };

    async function call(path, init = {}) {
      const res = await fetch(`${API}${path}`, { headers: HEADERS, ...init });
      if (!res.ok) throw new Error(`${path}: ${res.status} ${await res.text()}`);
      return res.json();
    }

    // A task can answer 404 for a moment right after it is created: keep polling.
    async function poll(taskId) {
      const res = await fetch(`${API}/task/${taskId}`, { headers: HEADERS });
      if (res.status === 404) return null;
      if (!res.ok) throw new Error(`/task/${taskId}: ${res.status} ${await res.text()}`);
      return res.json();
    }

    async function uploadImage(path, contentType = 'image/png') {
      const { uploadUrl, externalId } = await call('/media/image/upload-url', {
        method: 'POST',
        body: '{}',
      });
      const put = await fetch(uploadUrl, {
        method: 'PUT',
        headers: { 'Content-Type': contentType },
        body: await readFile(path),
      });
      if (!put.ok) throw new Error(`upload: ${put.status}`);
      const media = await call('/media/image/register', {
        method: 'POST',
        body: JSON.stringify({ externalId }),
      });
      return media.id;
    }

    async function waitFor(taskId, interval = 5000) {
      for (;;) {
        const task = await poll(taskId);
        if (task && task.status !== 'waiting' && task.status !== 'running') return task;
        await new Promise((resolve) => setTimeout(resolve, interval));
      }
    }

    const firstFrame = await uploadImage('first-frame.png');

    const created = await call('/frame-video/create', {
      method: 'POST',
      body: JSON.stringify({
        model: 'tbkv1.0.1',
        firstFrameMediaId: firstFrame,
        prompt: 'she turns around and smiles, hair blowing in the wind',
        duration: 5,
      }),
    });
    const task = await waitFor(created.id);
    if (task.status !== 'completed') {
      throw new Error(`Task ended as ${task.status}: ${JSON.stringify(task.taskStatusMsgI18n)}`);
    }

    const videoId = task.outputs.videoMediaId;
    const media = await call(`/media/batch?ids=${videoId}`);
    const video = media.find((m) => m.id === videoId);
    const file = await fetch(video.fileUrl);
    await writeFile('video.mp4', Buffer.from(await file.arrayBuffer()));
    ```
  </Tab>
</Tabs>

Reference [#reference]

* [Create an image-to-video task](/en/docs/api-v2/video/createFrameVideo)
* [Get an upload URL for an image](/en/docs/api-v2/media/getImageUploadUrl)
* [Get a task](/en/docs/api-v2/task/getTask)
* [Get media URLs by ID](/en/docs/api-v2/media/batchGetMedia)
