クイックスタート使用例

画像から動画を生成

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

生成されたメディアは永続的に保存されません。タスクが完了したら早めに動画をダウンロードしてください。

オプション

フィールド説明
modeltbkv1.0.1 が最新の Tsubaki 動画モデル、tbkv1.0 がその前のバージョンです。
lastFrameMediaId動画の最後のフレームになる画像です。最初のフレームと同じ画像を送るとループ動画になります。
duration5〜15 の整数(秒)。デフォルトは 5 です。
modebasic(デフォルト)または 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()));

リファレンス