PixAI APIの仕様書

2025年8月8日

PixAI API 画像生成仕様書

基本情報

ベースURL: https://platform.pixai.art/
認証方式: Bearer Token認証
データ形式: JSON
処理方式: 非同期処理

認証

API Key の取得と設定

PixAI Platformのプロフィール編集ページでAPI Keyを作成・管理
全てのAPIリクエストのAuthorizationヘッダーに設定

Authorization: Bearer YOUR_API_KEY

認証エラー

401 Unauthorized: 無効な認証情報
403 Forbidden: 権限不足
404 Not Found: トークンなしまたは権限不足

画像生成の流れ（非同期処理）

PixAI APIの画像生成は以下の2ステップで構成されます：

タスク作成: POST /task で画像生成タスクを作成
状況確認: GET /task/{taskId} で定期的に生成状況を確認

フロー図

[クライアント] → POST /task → [PixAI API] → タスクID返却
      ↓
[定期ポーリング] → GET /task/{taskId} → 状況確認
      ↓
[完了時] → mediaUrls から画像取得

エンドポイント詳細

1. 画像生成タスクの作成

エンドポイント: POST /task

目的: 新しい画像生成タスクを開始します。このAPIは即座にタスクIDを返し、実際の画像生成は非同期で実行されます。

リクエスト

必須パラメータ:

parameters (object): 画像生成パラメータ
prompts (string, ≤4096文字): 生成したい画像の説明
modelId (string): 使用するモデルのID

主要オプションパラメータ:

negativePrompts (string, ≤4096文字): 避けたい要素の説明
width (integer, 1-10240): 画像の幅
height (integer, 1-10240): 画像の高さ
samplingSteps (integer, 1-50): サンプリングステップ数（デフォルト: 20-25）
cfgScale (number, ≤100): CFGスケール（デフォルト: 6）
seed (number): シード値
batchSize (number, 1-4): 一度に生成する画像数
mediaId / mediaUrl (string): img2img用の参照画像
controlNets (array): ControlNet設定
lora (object): LoRAモデル設定
callbackUrl (string): タスク状況更新の通知URL

レスポンス (200 OK)

{
  "id": "task_id_string",
  "status": "waiting",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "outputs": null
}

エラーレスポンス

422 Validation Exception: パラメータ検証エラー
429 Too Many Requests: リクエスト制限超過

2. タスク状況の確認

エンドポイント: GET /task/{taskId}

目的: 指定されたタスクIDの詳細情報と生成状況を取得します。画像生成完了まで定期的にポーリングする必要があります。

パラメータ

パスパラメータ:

taskId (integer, required): 取得するタスクのID

レスポンス (200 OK)

{
  "id": "task_id_string",
  "status": "completed",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:10Z",
  "outputs": {
    "mediaIds": ["media_id_1", "media_id_2"],
    "mediaUrls": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg"
    ]
  }
}

タスクステータス

waiting: タスクが待機中
running: 画像生成実行中
completed: 生成完了（画像取得可能）
cancelled: タスクがキャンセルされた
failed: 生成に失敗

エラーレスポンス

404 Task Not Found: 指定されたタスクIDが存在しない

重要な注意事項

画像の保持期間

⚠️ 重要: 生成された画像は永続的に保持されません。

画像は一時的にのみ利用可能
mediaUrlsから可能な限り早く画像をダウンロード
配列内の一部の画像が利用できない場合、nullで置き換えられる可能性

ポーリング推奨間隔

初回確認: タスク作成から5-10秒後
継続確認: 5-15秒間隔
タイムアウト: 5-10分程度を目安

実装例

Python実装例

import requests
import time
import json

class PixAIClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://platform.pixai.art"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }

    def create_generation_task(self, prompt, **kwargs):
        """画像生成タスクを作成"""
        payload = {
            "parameters": {
                "prompts": prompt,
                "modelId": kwargs.get("model_id", "default_model"),
                "width": kwargs.get("width", 512),
                "height": kwargs.get("height", 512),
                "samplingSteps": kwargs.get("sampling_steps", 25),
                "cfgScale": kwargs.get("cfg_scale", 6),
                "batchSize": kwargs.get("batch_size", 1)
            }
        }

        # オプションパラメータの追加
        if "negative_prompts" in kwargs:
            payload["parameters"]["negativePrompts"] = kwargs["negative_prompts"]
        if "seed" in kwargs:
            payload["parameters"]["seed"] = kwargs["seed"]

        response = requests.post(
            f"{self.base_url}/task",
            headers=self.headers,
            json=payload
        )

        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"タスク作成失敗: {response.status_code} - {response.text}")

    def get_task_status(self, task_id):
        """タスクの状況を確認"""
        response = requests.get(
            f"{self.base_url}/task/{task_id}",
            headers=self.headers
        )

        if response.status_code == 200:
            return response.json()
        elif response.status_code == 404:
            raise Exception(f"タスクが見つかりません: {task_id}")
        else:
            raise Exception(f"状況確認失敗: {response.status_code} - {response.text}")

    def wait_for_completion(self, task_id, timeout=600, poll_interval=10):
        """タスク完了まで待機"""
        start_time = time.time()

        while time.time() - start_time < timeout:
            task_info = self.get_task_status(task_id)
            status = task_info["status"]

            print(f"タスク状況: {status}")

            if status == "completed":
                return task_info
            elif status == "failed":
                raise Exception("画像生成に失敗しました")
            elif status == "cancelled":
                raise Exception("タスクがキャンセルされました")

            time.sleep(poll_interval)

        raise Exception(f"タイムアウト: {timeout}秒以内に完了しませんでした")

    def generate_image(self, prompt, **kwargs):
        """画像生成の完全なフロー"""
        # 1. タスク作成
        task_result = self.create_generation_task(prompt, **kwargs)
        task_id = task_result["id"]
        print(f"タスク作成完了: {task_id}")

        # 2. 完了まで待機
        completed_task = self.wait_for_completion(task_id)

        # 3. 画像URLを取得
        media_urls = completed_task["outputs"]["mediaUrls"]
        valid_urls = [url for url in media_urls if url is not None]

        return {
            "task_id": task_id,
            "image_urls": valid_urls,
            "media_ids": completed_task["outputs"]["mediaIds"]
        }

# 使用例
if __name__ == "__main__":
    client = PixAIClient("YOUR_API_KEY")

    try:
        result = client.generate_image(
            prompt="a beautiful sunset over mountains",
            negative_prompts="blurry, low quality",
            width=768,
            height=768,
            sampling_steps=30,
            cfg_scale=7
        )

        print("生成完了!")
        for i, url in enumerate(result["image_urls"]):
            print(f"画像 {i+1}: {url}")

    except Exception as e:
        print(f"エラー: {e}")

トラブルシューティング

よくある問題と解決方法

1. 認証エラー (401/403)

原因:

API Keyが無効または期限切れ
API Keyの権限不足

解決方法:

API Keyを再確認・再生成
プロフィール設定で権限を確認

2. タスクが完了しない

原因:

サーバー負荷が高い
複雑なプロンプトで処理時間が長い
システム障害

解決方法:

タイムアウト時間を延長
プロンプトを簡素化
時間を置いて再試行

3. 画像URLがnull

原因:

画像生成に部分的に失敗
画像の保持期間が過ぎた
サーバー側の一時的な問題

解決方法:

有効なURLのみを使用
即座に画像をダウンロード
必要に応じて再生成

4. レート制限エラー (429)

原因:

API呼び出し頻度が高すぎる
同時リクエスト数が多すぎる

解決方法:

リクエスト間隔を調整
指数バックオフで再試行
並列処理数を制限

デバッグのためのログ出力

import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def debug_api_call(response, endpoint):
    logger.info(f"API呼び出し: {endpoint}")
    logger.info(f"ステータスコード: {response.status_code}")
    logger.info(f"レスポンスヘッダー: {dict(response.headers)}")
    if response.status_code != 200:
        logger.error(f"エラーレスポンス: {response.text}")

別データ

Markdown

## 基本情報

- **ベースURL**: `https://platform.pixai.art/`
- **認証方式**: Bearer Token認証
- **データ形式**: JSON
- **処理方式**: 非同期処理

## 認証

### API Key の取得と設定

1. PixAI Platformのプロフィール編集ページでAPI Keyを作成・管理
2. 全てのAPIリクエストのAuthorizationヘッダーに設定

```http
Authorization: Bearer YOUR_API_KEY
```

### 認証エラー

- **401 Unauthorized**: 無効な認証情報
- **403 Forbidden**: 権限不足
- **404 Not Found**: トークンなしまたは権限不足



## 画像生成の流れ（非同期処理）

PixAI APIの画像生成は以下の2ステップで構成されます：

1. **タスク作成**: `POST /task` で画像生成タスクを作成
2. **状況確認**: `GET /task/{taskId}` で定期的に生成状況を確認

### フロー図

```
[クライアント] → POST /task → [PixAI API] → タスクID返却
      ↓
[定期ポーリング] → GET /task/{taskId} → 状況確認
      ↓
[完了時] → mediaUrls から画像取得
```

## エンドポイント詳細

### 1. 画像生成タスクの作成

**エンドポイント**: `POST /task`

**目的**: 新しい画像生成タスクを開始します。このAPIは即座にタスクIDを返し、実際の画像生成は非同期で実行されます。

#### リクエスト

**必須パラメータ**:
- `parameters` (object): 画像生成パラメータ
  - `prompts` (string, ≤4096文字): 生成したい画像の説明
  - `modelId` (string): 使用するモデルのID

**主要オプションパラメータ**:
- `negativePrompts` (string, ≤4096文字): 避けたい要素の説明
- `width` (integer, 1-10240): 画像の幅
- `height` (integer, 1-10240): 画像の高さ
- `samplingSteps` (integer, 1-50): サンプリングステップ数（デフォルト: 20-25）
- `cfgScale` (number, ≤100): CFGスケール（デフォルト: 6）
- `seed` (number): シード値
- `batchSize` (number, 1-4): 一度に生成する画像数
- `mediaId` / `mediaUrl` (string): img2img用の参照画像
- `controlNets` (array): ControlNet設定
- `lora` (object): LoRAモデル設定
- `callbackUrl` (string): タスク状況更新の通知URL

#### レスポンス (200 OK)

```json
{
  "id": "task_id_string",
  "status": "waiting",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z",
  "outputs": null
}
```

#### エラーレスポンス

- **422 Validation Exception**: パラメータ検証エラー
- **429 Too Many Requests**: リクエスト制限超過


### 2. タスク状況の確認

**エンドポイント**: `GET /task/{taskId}`

**目的**: 指定されたタスクIDの詳細情報と生成状況を取得します。画像生成完了まで定期的にポーリングする必要があります。

#### パラメータ

**パスパラメータ**:
- `taskId` (integer, required): 取得するタスクのID

#### レスポンス (200 OK)

```json
{
  "id": "task_id_string",
  "status": "completed",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:10Z",
  "outputs": {
    "mediaIds": ["media_id_1", "media_id_2"],
    "mediaUrls": [
      "https://example.com/image1.jpg",
      "https://example.com/image2.jpg"
    ]
  }
}
```

#### タスクステータス

- `waiting`: タスクが待機中
- `running`: 画像生成実行中
- `completed`: 生成完了（画像取得可能）
- `cancelled`: タスクがキャンセルされた
- `failed`: 生成に失敗

#### エラーレスポンス

- **404 Task Not Found**: 指定されたタスクIDが存在しない

## 重要な注意事項

### 画像の保持期間

⚠️ **重要**: 生成された画像は永続的に保持されません。

- 画像は一時的にのみ利用可能
- `mediaUrls`から可能な限り早く画像をダウンロード
- 配列内の一部の画像が利用できない場合、`null`で置き換えられる可能性

### ポーリング推奨間隔

- 初回確認: タスク作成から5-10秒後
- 継続確認: 5-15秒間隔
- タイムアウト: 5-10分程度を目安


## 実装例

### Python実装例

```python
import requests
import time
import json

class PixAIClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://platform.pixai.art"
        self.headers = {
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        }
    
    def create_generation_task(self, prompt, **kwargs):
        """画像生成タスクを作成"""
        payload = {
            "parameters": {
                "prompts": prompt,
                "modelId": kwargs.get("model_id", "default_model"),
                "width": kwargs.get("width", 512),
                "height": kwargs.get("height", 512),
                "samplingSteps": kwargs.get("sampling_steps", 25),
                "cfgScale": kwargs.get("cfg_scale", 6),
                "batchSize": kwargs.get("batch_size", 1)
            }
        }
        
        # オプションパラメータの追加
        if "negative_prompts" in kwargs:
            payload["parameters"]["negativePrompts"] = kwargs["negative_prompts"]
        if "seed" in kwargs:
            payload["parameters"]["seed"] = kwargs["seed"]
        
        response = requests.post(
            f"{self.base_url}/task",
            headers=self.headers,
            json=payload
        )
        
        if response.status_code == 200:
            return response.json()
        else:
            raise Exception(f"タスク作成失敗: {response.status_code} - {response.text}")
    
    def get_task_status(self, task_id):
        """タスクの状況を確認"""
        response = requests.get(
            f"{self.base_url}/task/{task_id}",
            headers=self.headers
        )
        
        if response.status_code == 200:
            return response.json()
        elif response.status_code == 404:
            raise Exception(f"タスクが見つかりません: {task_id}")
        else:
            raise Exception(f"状況確認失敗: {response.status_code} - {response.text}")
    
    def wait_for_completion(self, task_id, timeout=600, poll_interval=10):
        """タスク完了まで待機"""
        start_time = time.time()
        
        while time.time() - start_time < timeout:
            task_info = self.get_task_status(task_id)
            status = task_info["status"]
            
            print(f"タスク状況: {status}")
            
            if status == "completed":
                return task_info
            elif status == "failed":
                raise Exception("画像生成に失敗しました")
            elif status == "cancelled":
                raise Exception("タスクがキャンセルされました")
            
            time.sleep(poll_interval)
        
        raise Exception(f"タイムアウト: {timeout}秒以内に完了しませんでした")
    
    def generate_image(self, prompt, **kwargs):
        """画像生成の完全なフロー"""
        # 1. タスク作成
        task_result = self.create_generation_task(prompt, **kwargs)
        task_id = task_result["id"]
        print(f"タスク作成完了: {task_id}")
        
        # 2. 完了まで待機
        completed_task = self.wait_for_completion(task_id)
        
        # 3. 画像URLを取得
        media_urls = completed_task["outputs"]["mediaUrls"]
        valid_urls = [url for url in media_urls if url is not None]
        
        return {
            "task_id": task_id,
            "image_urls": valid_urls,
            "media_ids": completed_task["outputs"]["mediaIds"]
        }

# 使用例
if __name__ == "__main__":
    client = PixAIClient("YOUR_API_KEY")
    
    try:
        result = client.generate_image(
            prompt="a beautiful sunset over mountains",
            negative_prompts="blurry, low quality",
            width=768,
            height=768,
            sampling_steps=30,
            cfg_scale=7
        )
        
        print("生成完了!")
        for i, url in enumerate(result["image_urls"]):
            print(f"画像 {i+1}: {url}")
            
    except Exception as e:
        print(f"エラー: {e}")
```

## トラブルシューティング

### よくある問題と解決方法

#### 1. 認証エラー (401/403)

**原因**:
- API Keyが無効または期限切れ
- API Keyの権限不足

**解決方法**:
- API Keyを再確認・再生成
- プロフィール設定で権限を確認

#### 2. タスクが完了しない

**原因**:
- サーバー負荷が高い
- 複雑なプロンプトで処理時間が長い
- システム障害

**解決方法**:
- タイムアウト時間を延長
- プロンプトを簡素化
- 時間を置いて再試行

#### 3. 画像URLがnull

**原因**:
- 画像生成に部分的に失敗
- 画像の保持期間が過ぎた
- サーバー側の一時的な問題

**解決方法**:
- 有効なURLのみを使用
- 即座に画像をダウンロード
- 必要に応じて再生成

#### 4. レート制限エラー (429)

**原因**:
- API呼び出し頻度が高すぎる
- 同時リクエスト数が多すぎる

**解決方法**:
- リクエスト間隔を調整
- 指数バックオフで再試行
- 並列処理数を制限

### デバッグのためのログ出力

```python
import logging

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

def debug_api_call(response, endpoint):
    logger.info(f"API呼び出し: {endpoint}")
    logger.info(f"ステータスコード: {response.status_code}")
    logger.info(f"レスポンスヘッダー: {dict(response.headers)}")
    if response.status_code != 200:
        logger.error(f"エラーレスポンス: {response.text}")
```

よかったらシェアしてね！

URLをコピーしました！

URLをコピーしました！