クイックスタート使用例

モデルと LoRA を探して使う

API から PixAI モデルマーケットを検索し、ベースモデルに合う LoRA を見つけ、トリガーワードとサイズを確認して画像を生成します。

PixAI モデルマーケットにあるすべてのモデルと LoRA は、API から利用できます。このガイドでは、LoRA を検索し、ベースモデルに合うことを確認してから、その LoRA で画像を生成します。

ベースURL: https://api.pixai.art/v2。モデル関連のエンドポイントは API キーなしでも使えますが、アカウントで表示されるのと同じモデルを取得するには Authorization: Bearer YOUR_API_KEY を付けてください。匿名での検索はより厳しくフィルタリングされます。画像の生成には必ず API キーが必要です。PixAI APIを使用するには?をご参照ください。

生成エンドポイントが受け取るのはバージョン ID です。検索結果の id はモデル ID なので、代わりに latestAvailableVersionId を渡してください。

手順

ベースモデルを選ぶ

推奨モデルから選ぶか、usageType=MODEL でベースモデルを検索します。バージョンを取得してタイプを確認してください。LoRA はこのタイプに合っている必要があります。

curl https://api.pixai.art/v2/generation-model-version/1861558740588989558
{
  "id": "1861558740588989558",
  "modelId": "1861558737426484240",
  "modelTitle": "Haruka v2",
  "modelType": "SDXL_MODEL",
  "status": "available"
}

Haruka v2 は SDXL_MODEL なので、SDXL 用の LoRA を使えます。

LoRA を検索する

usageType=LORA、keyword、そして loraBaseModelTypes にベースモデルのタイプを指定して検索します。

curl "https://api.pixai.art/v2/generation-model/search?usageType=LORA&keyword=watercolor&loraBaseModelTypes=SDXL_MODEL&size=5" \
  -H "Authorization: Bearer $PIXAI_API_KEY"

data の各要素が 1 つのモデルです。必要なフィールドは次のとおりです。

{
  "id": "1682965664660673855",
  "title": "Anime Watercolor style XL",
  "type": "MULTI_LORA",
  "loraBaseModelTypes": ["SDXL_MODEL"],
  "permittedUse": "PERSONAL",
  "latestAvailableVersionId": "1682965664694228288",
  "latestAvailableVersion": {
    "id": "1682965664694228288",
    "loraBaseModelType": "SDXL_MODEL",
    "extra": { "triggerWords": "watercolor (medium), (watercolor)" }
  }
}

結果は関連度と人気順に並びます。hasMore が true の間は offset と size でページを送ります。商用利用が可能なライセンスが必要な場合は permittedUse=COMMERCIAL を追加してください。

バージョンが合うか確認する

loraBaseModelTypes は LoRA のすべてのバージョンを対象にしているため、最新バージョンが別のベースモデル用である場合があります。latestAvailableVersion.loraBaseModelType がベースモデルのタイプと一致するか確認してください。一致しない場合は、そのタイプに対応するモデルのバージョンを新しい順に一覧表示し、最初の id を使います。

curl "https://api.pixai.art/v2/generation-model/1682965664660673855/versions?baseModelType=SDXL_MODEL"

トリガーワードは extra.triggerWords にあります。triggerWords で独自に指定しない限り、API が自動でプロンプトに追加します。

サイズを選ぶ

aspectRatio と size はすべてのモデルで使えます。width と height を正確に指定する場合は、ベースモデルが受け付けるサイズを取得してください。

curl https://api.pixai.art/v2/generation-model/1861558740588989558/size-config

ranges の各要素には、minWidth〜maxWidth、minHeight〜maxHeight、幅と高さがその倍数でなければならない step、そしてすぐに使える presets が含まれます。accessStatus: "membership_required" の要素には、上位のメンバーシッププランが必要です。

LoRA で画像を生成する

LoRA のバージョン ID を loras[].modelId に、0〜1 の weight とともに指定します。

curl -X POST https://api.pixai.art/v2/image/create \
  -H "Authorization: Bearer $PIXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelVersionId": "1861558740588989558",
    "prompt": "1girl, solo, straw hat, sunflower field, summer, blue sky",
    "aspectRatio": "2:3",
    "loras": [
      { "modelId": "1682965664694228288", "weight": 0.8 }
    ]
  }'

その後、最初のAPIリクエストと同じように、GET /v2/task/{id} をポーリングして結果をダウンロードします。

LoRA はメンバーシップなしで最大 3 個、メンバーシップがあれば最大 15 個まで組み合わせられます。上限を超えると 403 LORA_NUM_EXCEEDED が返ります。weight を高くするほど LoRA の効果が強くなります。

まとめて実行するスクリプト

Haruka v2 に合う LoRA を検索し、その LoRA で画像を生成します。事前に環境変数 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']}"}
BASE_VERSION = "1861558740588989558"  # Haruka v2


def get(path, **params):
    resp = requests.get(f"{API}{path}", headers=HEADERS, params=params)
    resp.raise_for_status()
    return resp.json()


base = get(f"/generation-model-version/{BASE_VERSION}")
base_type = base["modelType"]

results = get(
    "/generation-model/search",
    usageType="LORA",
    keyword="watercolor",
    loraBaseModelTypes=base_type,
    size=10,
)["data"]

lora = None
for model in results:
    latest = model.get("latestAvailableVersion") or {}
    if latest.get("loraBaseModelType") == base_type:
        lora = latest
        break
if lora is None:
    raise SystemExit(f"No LoRA for {base_type} in the first page of results")
print("Using", lora["modelTitle"], lora["id"], "trigger words:", lora["extra"].get("triggerWords"))

resp = requests.post(
    f"{API}/image/create",
    headers=HEADERS,
    json={
        "modelVersionId": BASE_VERSION,
        "prompt": "1girl, solo, straw hat, sunflower field, summer, blue sky",
        "aspectRatio": "2:3",
        "loras": [{"modelId": lora["id"], "weight": 0.8}],
    },
)
resp.raise_for_status()
task = resp.json()

while task["status"] in ("waiting", "running"):
    time.sleep(2)
    resp = requests.get(f"{API}/task/{task['id']}", headers=HEADERS)
    if resp.status_code == 404:  # 作成直後のタスクは一時的に 404 を返すことがあります。ポーリングを続けます。
        continue
    resp.raise_for_status()
    task = resp.json()

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

with open("lora.webp", "wb") as f:
    f.write(requests.get(task["outputs"]["mediaUrls"][0]).content)

Node.js 20 以降で、lora.mjs として保存します。

import { 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',
};
const BASE_VERSION = '1861558740588989558'; // Haruka v2

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

const base = await call(`/generation-model-version/${BASE_VERSION}`);
const query = new URLSearchParams({
  usageType: 'LORA',
  keyword: 'watercolor',
  loraBaseModelTypes: base.modelType,
  size: '10',
});
const { data } = await call(`/generation-model/search?${query}`);
const lora = data
  .map((model) => model.latestAvailableVersion)
  .find((version) => version?.loraBaseModelType === base.modelType);
if (!lora) throw new Error(`No LoRA for ${base.modelType} in the first page of results`);
console.log('Using', lora.modelTitle, lora.id, 'trigger words:', lora.extra?.triggerWords);

let task = await call('/image/create', {
  method: 'POST',
  body: JSON.stringify({
    modelVersionId: BASE_VERSION,
    prompt: '1girl, solo, straw hat, sunflower field, summer, blue sky',
    aspectRatio: '2:3',
    loras: [{ modelId: lora.id, weight: 0.8 }],
  }),
});
while (task.status === 'waiting' || task.status === 'running') {
  await new Promise((resolve) => setTimeout(resolve, 2000));
  task = (await poll(task.id)) ?? task;
}
if (task.status !== 'completed') {
  throw new Error(`Task ended as ${task.status}: ${JSON.stringify(task.taskStatusMsgI18n)}`);
}

const image = await fetch(task.outputs.mediaUrls[0]);
await writeFile('lora.webp', Buffer.from(await image.arrayBuffer()));

リファレンス