最初の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)