クイックスタート

最初のAPIリクエスト

タスクの送信、ステータスの確認、画像のダウンロードまで、PixAI API への最初のリクエストをステップごとに説明します。

ベースURL: https://api.pixai.art/v2

認証: すべてのリクエストに Authorization: Bearer YOUR_API_KEY ヘッダーを追加してください。APIキーの取得方法はPixAI APIを使用するには?をご参照ください。

手順

タスクを送信する

POST /image/create を送信します。必須フィールドは modelVersionId と prompt です。

curl -X POST https://api.pixai.art/v2/image/create \
  -H "Authorization: Bearer $PIXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelVersionId": "2024383379556065549",
    "prompt": "An anime girl with long green hair in a white sundress, standing in a sunflower field at golden hour and holding a straw hat, with summer clouds and a seaside town behind her, cinematic lighting, detailed background",
    "aspectRatio": "3:5"
  }'

レスポンス:

{
  "id": "TASK_ID",
  "status": "waiting",
  "createdAt": "2026-03-04T04:32:10.635Z",
  "updatedAt": "2026-03-04T04:32:10.635Z",
  "outputs": {
    "mediaIds": [],
    "mediaUrls": []
  }
}

レスポンス内の id を控えておいてください。これが次のステップで使用する TASK_ID です。

modelVersionId は PixAI のモデルバージョン URL(https://pixai.art/model/<id>/<modelVersionId>)の最後のセグメントです。推奨モデルはモデル一覧をご参照ください。

ステータスを確認する

status が終了状態になるまで繰り返します。作成直後は一時的に 404 が返ることがありますが、そのままポーリングを続けてください。

curl https://api.pixai.art/v2/task/TASK_ID \
  -H "Authorization: Bearer $PIXAI_API_KEY"
ステータス意味
waitingタスクはキュー待ち中
running生成処理中
completed完了、出力が利用可能
failed生成に失敗
cancelledタスクがキャンセルされた

completed の場合、outputs.mediaUrls に画像 URL が含まれます。

{
  "id": "TASK_ID",
  "status": "completed",
  "taskKind": "t2i",
  "createdAt": "2026-03-04T04:32:10.635Z",
  "updatedAt": "2026-03-04T04:32:41.902Z",
  "outputs": {
    "seed": "12345",
    "mediaIds": ["MEDIA_ID"],
    "mediaUrls": ["MEDIA_URL"]
  }
}

ポーリングは 1.5秒 に1回以下にしてください。再試行時はエクスポネンシャル・バックオフを使用してください。各アカウントでは waiting 状態のタスクを同時に最大10件まで持てます(running のタスクは数えません)。詳細は制限事項をご参照ください。

画像をダウンロードする

curl -L "MEDIA_URL" -o output.webp
# またはメディア ID から URL を取得(画像は `urls` の `PUBLIC`、動画は `fileUrl`):
curl "https://api.pixai.art/v2/media/batch?ids=MEDIA_ID"

生成された画像は 永続的に保存されません。タスクが完了したらすぐにダウンロードしてください。

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

作成・ポーリング・保存を Python で行う例です。requests をインストールし、API キーを PIXAI_API_KEY に設定してください。

import os
import time

import requests

API = "https://api.pixai.art/v2"
HEADERS = {"Authorization": f"Bearer {os.environ['PIXAI_API_KEY']}"}

resp = requests.post(
    f"{API}/image/create",
    headers=HEADERS,
    json={
        "modelVersionId": "2024383379556065549",  # Tsubaki.3
        "prompt": (
            "An anime girl with long green hair in a white sundress, standing in a sunflower field "
            "at golden hour and holding a straw hat, with summer clouds and a seaside town behind her, "
            "cinematic lighting, detailed background"
        ),
        "aspectRatio": "3:5",
    },
)
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')}")

for i, url in enumerate(task["outputs"]["mediaUrls"]):
    if url:
        image = requests.get(url)
        image.raise_for_status()
        with open(f"output-{i}.webp", "wb") as f:
            f.write(image.content)

次のステップ

  • モデル — 利用可能なモデルを確認
  • Webhook — ポーリングなしでタスクの更新を受け取る
  • 使用例 — 画像から動画の生成、キャラクターの一貫性、インペイント、LoRA の完全なスクリプト