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.pngThen 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.mp4Generated media is not kept forever. Download the video soon after the task finishes.
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.
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
Limits
Learn about PixAI API limits: the cap on tasks waiting in the queue, polling guidance, and features not supported yet.
Consistent Characters
Keep an anime character the same across images with the PixAI API. Pass up to three reference images to Tsubaki.3 and say in the prompt what to take from each.