画像から動画を生成
PixAI API で 1 枚の画像を動画にします。画像のアップロードまたは再利用、最初と最後のフレームの指定、音声の追加、MP4 のダウンロードまでを説明します。
POST /v2/frame-video/create は、PixAI の Tsubaki 動画モデルで画像を動かします。動画は指定した画像から始まり、2 枚目の画像を送るとその画像で終わります。イラストに動きをつける、2 枚の画像をつなぐトランジションを作る、ループ動画を作る、といった用途に使えます。
ベースURL: https://api.pixai.art/v2。すべてのリクエストに Authorization: Bearer YOUR_API_KEY を付けてください。API キーの取得方法はPixAI APIを使用するには?をご参照ください。
画像から動画の生成には PixAI メンバーシップが必要です。クレジットはタスクの作成時に消費され、動画の完成までには数分かかります。
手順
画像のメディア ID を用意する
動画のフレームはメディア ID で指定します。API で生成した画像にはすでにメディア ID があります。完了したタスクの outputs.mediaIds に含まれているので、次のステップに進んでください。
手元のファイルを使う場合は、3 回の呼び出しでアップロードします。まずアップロード 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"
}ファイルの生のバイト列を、実際の Content-Type を付けて uploadUrl に PUT します。マルチパートフォームでは送らないでください。
curl -X PUT "UPLOAD_URL" \
-H "Content-Type: image/png" \
--data-binary @first-frame.png続いてアップロードを登録します。レスポンスの id がメディア 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"}'動画タスクを作成する
メディア ID を firstFrameMediaId に指定し、prompt で動きの内容を記述します。
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
}'レスポンスは status: "waiting" のタスクです。id を控えておいてください。
タスクの完了を待つ
status が completed、failed、cancelled のいずれかになるまで、数秒おきに GET /v2/task/{id} をポーリングします。
curl https://api.pixai.art/v2/task/TASK_ID \
-H "Authorization: Bearer $PIXAI_API_KEY"完了した動画タスクでは、動画は outputs.videoMediaId に入ります。outputs.mediaIds にはポスター画像だけが入ります。
{
"id": "TASK_ID",
"status": "completed",
"taskKind": "i2v-inhouse",
"outputs": {
"videoMediaId": "VIDEO_MEDIA_ID",
"mediaIds": ["POSTER_MEDIA_ID"]
}
}動画をダウンロードする
GET /v2/media/batch で動画のメディア ID を解決し、fileUrl(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生成されたメディアは永続的に保存されません。タスクが完了したら早めに動画をダウンロードしてください。
オプション
| フィールド | 説明 |
|---|---|
model | tbkv1.0.1 が最新の Tsubaki 動画モデル、tbkv1.0 がその前のバージョンです。 |
lastFrameMediaId | 動画の最後のフレームになる画像です。最初のフレームと同じ画像を送るとループ動画になります。 |
duration | 5〜15 の整数(秒)。デフォルトは 5 です。 |
mode | basic(デフォルト)または professional。professional は tbkv1.0.1 で 1080p へのアップスケールが加わり、消費クレジットが増えます。 |
generateAudio | 音声を生成するかどうか。デフォルトは true です。 |
audioLanguage | 音声に含まれるセリフの言語: english、japanese、korean、chinese、またはセリフなしの none。 |
動画は最初のフレームのアスペクト比を維持します。他のユーザーが所有するフレームを指定すると 400 INVALID_REFERENCE_MEDIA で拒否されます。
特定のフレームから始めるのではなく、複数の画像・動画・音声を参照して新しいショットを作るには、POST /v2/reference-video/create を使います。Seedance 2 や Vidu など、ほかの動画モデルも利用できます。
まとめて実行するスクリプト
手元の画像をアップロードして動画にし、MP4 を保存します。事前に環境変数 PIXAI_API_KEY を設定してください。
requests をインストールしてください。
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"):
"""手元の画像をアップロードし、メディア 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):
"""タスクが終了するまでポーリングし、タスクを返す。"""
while True:
resp = requests.get(f"{API}/task/{task_id}", headers=HEADERS)
if resp.status_code != 404: # 作成直後のタスクは一時的に 404 を返すことがあります。ポーリングを続けます。
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)Node.js 20 以降で、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();
}
// 作成直後のタスクは一時的に 404 を返すことがあるため、ポーリングを続けます。
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()));