Quick StartExamples

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? to get a key.

Image-to-video needs a PixAI membership. Credits are charged when the task is created, and a video takes a few minutes to finish.

Steps

Get a media ID for the image

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:

curl -X POST https://api.pixai.art/v2/media/image/upload-url \
  -H "Authorization: Bearer $PIXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
{
  "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:

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:

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"}'

Create the video task

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

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.

Wait for the task to finish

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

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.

{
  "id": "TASK_ID",
  "status": "completed",
  "taskKind": "i2v-inhouse",
  "outputs": {
    "videoMediaId": "VIDEO_MEDIA_ID",
    "mediaIds": ["POSTER_MEDIA_ID"]
  }
}

Download the video

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

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

Generated media is not kept forever. Download the video soon after the task finishes.

Options

FieldWhat it does
modeltbkv1.0.1 is the latest Tsubaki video model; tbkv1.0 is the previous one.
lastFrameMediaIdThe image the clip ends on. Send the first frame again to make a loop.
duration5 to 15 whole seconds. Defaults to 5.
modebasic (default) or professional, which adds a 1080p upscale on tbkv1.0.1 and costs more.
generateAudioWhether to generate a soundtrack. Defaults to true.
audioLanguageThe 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.

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. It also offers other video models, such as Seedance 2 and Vidu.

Full script

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

With requests installed:

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)

For Node.js 20 or later, saved as video.mjs:

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()));

Reference