---
title: "画像生成タスクの作成"
description: "簡略化された v2 API で非同期の画像生成タスクを開始します。レスポンスには作成されたタスクの ID が含まれます。"
canonical: "https://platform.pixai.art/ja/docs/api-v2/image/createImage"
last-updated: "2026-11-16"
---

# 画像生成タスクの作成

簡略化された v2 API で非同期の画像生成タスクを開始します。レスポンスには作成されたタスクの ID が含まれます。



v2 API は `aspectRatio`（アスペクト比）、`mode`（品質モード）、名前付き `style` プリセットなど、ユーザーフレンドリーなパラメータを提供します。v1 の生ピクセル寸法や内部パラメータ名を置き換えます。

## POST https://api.pixai.art/v2/image/create

Authentication: send your API key as `Authorization: Bearer <API key>`.

Machine-readable OpenAPI spec: https://platform.pixai.art/openapi-spec.v2.ja.yaml

### Request body (`application/json`)

- `modelVersionId` (string, required)
  生成に使用するモデルバージョンの一意の識別子です。非推奨の `modelId` フィールドの代替として推奨されます。

  modelVersionId の見つけ方:
  1. PixAI のモデルページを開きます。
  2. 使用したいモデルバージョンをクリックします。
  3. URL の末尾のパスセグメントをコピーします。これが modelVersionId です。

  URL 例: `https://pixai.art/model/<id>-<slug>/<modelVersionId>` → modelVersionId は `<modelVersionId>` です。
  Example: `"1983308862240288769"`.
- `modelId` (string, optional, deprecated)
  生成に使用するモデルバージョンの一意の識別子です。PixAI のモデルバージョンの URL から取得します。

  modelId の見つけ方:
  1. PixAI のモデルページを開きます。
  2. 使用したいモデルバージョンをクリックします。
  3. URL の末尾のパスセグメントをコピーします。これが modelId です。

  URL 例: `https://pixai.art/model/<id>-<slug>/<modelVersionId>` → modelId は `<modelVersionId>` です。
  Note: 代わりに `modelVersionId` を使用してください。`modelId` は名前が紛らわしく、実際にはモデルIDではなくモデル**バージョン**IDを受け取ります。
  Example: `"1983308862240288769"`.
- `prompt` (string, required)
  生成したいコンテンツを説明するメインプロンプトです。Tsubaki.2 と Tsubaki.3 では最大 10,000 文字、その他のモデルでは最大 4,096 文字です。
  Length: 1 to 10000 characters.
  Example: `"1girl, green hair, solo, standing"`.
- `negativePrompt` (string, optional)
  生成画像に含めたくない要素を説明するテキストです。
  Length: 0 to 4096 characters.
  Example: `"nsfw, lowres, bad anatomy"`.
- `aspectRatio` (string, optional)
  生成画像のアスペクト比。`aspectRatio`/`size` も `width`/`height` も指定しない場合のデフォルトは `1:1` です。`width`・`height` とは併用できません。

  利用可能な比率: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `3:5`, `5:3`, `9:16`, `16:9`, `1:3`, `3:1`

  すべての比率はすべてのモデルタイプ（SDXL、DiT、Tsubaki.2）で利用可能です。

  サイズティアごとの完全な解像度マッピングは[対応解像度](https://platform.pixai.art/ja/docs/references/supported-resolutions)を参照してください。
  Allowed values: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `3:5`, `5:3`, `9:16`, `16:9`, `1:3`, `3:1`.
  Example: `"1:1"`.
- `size` (string, optional)
  出力解像度のティア。`aspectRatio`/`size` も `width`/`height` も指定しない場合のデフォルトは `1k` です。`width`・`height` とは併用できません。`1.5k` の最長辺は 1536 px です。
  - `1k`: 約 1 メガピクセル（例: 1:1 で 1024×1024）。
  - `1.5k`: 約 2.36 メガピクセル（例: 1:1 で 1536×1536）。

  完全なマッピングテーブルは[対応解像度](https://platform.pixai.art/ja/docs/references/supported-resolutions)を参照してください。
  Allowed values: `1k`, `1.5k`.
  Example: `"1k"`.
- `width` (integer, optional)
  正確な出力幅（ピクセル）です。`aspectRatio`/`size` のプリセットにないサイズ（Tsubaki.3 の大きい出力など）に使います。`height` と一緒に指定し、`aspectRatio` と `size` は指定しないでください。

  サイズはモデルのサイズ範囲のいずれかに収まり、その `step` の倍数である必要があります。範囲は `GET https://api.pixai.art/v2/generation-model/{modelVersionId}/size-config`（認証不要）で取得できます。`ranges` の各要素に `minWidth`/`maxWidth`、`minHeight`/`maxHeight`、`step` と既定の `presets` が含まれます。どの範囲にも収まらないサイズは `400 IMAGE_SIZE_NOT_ALLOWED` になります。
  Range: 1 to 10240.
  Example: `1024`.
- `height` (integer, optional)
  正確な出力の高さ（ピクセル）です。`width` と一緒に指定します。指定できるサイズは `width` を参照してください。
  Range: 1 to 10240.
  Example: `1024`.
- `mode` (string, optional)
  生成品質と速度を制御する推論プロファイルです。
  - `lite`: 最速、基本品質。
  - `standard`: 速度と品質のバランス。
  - `pro`: 高品質、低速。
  - `ultra`: 最高品質、最低速。

  すべてのモデル・プランですべてのモードが使えるわけではありません。使えないモードを指定すると、そのモード名を含む `422 INVALID_INPUT` が返ります。
  Note: **Tsubaki.2** および **Tsubaki.3** モデルファミリーのみ有効です。他のモデルタイプでは `400 INVALID_ARGUMENT` で拒否されます。
  Allowed values: `lite`, `standard`, `pro`, `ultra`.
  Example: `"standard"`.
- `style` (object (one of the variants below), optional)
  生成中に適用するスタイルです。名前付きプリセットまたはカスタムスタイル文字列を指定できます。
  Note: **Tsubaki.2** および **Tsubaki.3** モデルファミリーのみ有効です。他のモデルタイプでは無視されます。
  - Variant 1:
    - `style.type` (string, required)
      Allowed values: `preset`.
    - `style.key` (string, required)
      プリセットスタイルキー。利用可能なプリセット:
      - `anime-watercolor-impasto` — 水彩グロー
      - `art-crayon` — アートクレヨン
      - `bold-line-soft-color` — グリント＆グルーム
      - `chibi` — ちびキャラ
      - `classic-japanese` — クラシックアニメ
      - `clean-flat-illustration` — シンプル平塗り
      - `colored-pencil-grain` — カラフル色鉛筆
      - `cool-warm-oil-contrast` — 四季の光彩
      - `desaturated-cool` — 寒色系ソフトライト
      - `flat-anime-pastel` — パステルフラット
      - `glossy-glass-anime` — ガラス風アニメ
      - `grey-blocks-lineless` — グレーウォッシュ
      - `hard-line-monochrome-accent` — シャープ・インク
      - `high-contrast-retro-vivid` — ビビッドネオン
      - `holographic` — ハイパーポップ
      - `korean-style` — 綺麗な韓国漫画風
      - `lineart-watercolor-airy` — 潤いのあるレンダリング
      - `low-saturation-expressive-eyes` — 透明感・淡彩
      - `lucid-dreamy` — 透明感のある夢幻
      - `luminous-retro-impasto` — 明るい厚塗り
      - `minimal-flat-color` — ミニマル・フラット
      - `modern-oil-glamour` — モダン・ムチムチ感
      - `moe-pastel` — 透明感のある萌え
      - `oil-watercolor-blend` — 水彩風厚塗り
      - `painterly-doodle` — 優しいタッチ
      - `paper-watercolor` — 水彩ソフトフォーカス
      - `pencil-sketch` — 鉛筆スケッチ
      - `poster-graffiti` — ネオンポスター
      - `retro-comic-fusion` — レトロフュージョン
      - `retro-oil-glamour` — レトロ・ムチムチ感
      - `retro-tv-anime` — 90年代レトロセル画
      - `semi-realistic` — セミリアル
      - `stable-vaporwave` — ネオン・ヴェイパーウェイヴ
      - `tinted-sketch` — 淡彩スケッチ
      - `vintage-collage` — ヴィンテージコラージュ
      Allowed values: `anime-watercolor-impasto`, `art-crayon`, `bold-line-soft-color`, `chibi`, `classic-japanese`, `clean-flat-illustration`, `colored-pencil-grain`, `cool-warm-oil-contrast`, `desaturated-cool`, `flat-anime-pastel`, `glossy-glass-anime`, `grey-blocks-lineless`, `hard-line-monochrome-accent`, `high-contrast-retro-vivid`, `holographic`, `korean-style`, `lineart-watercolor-airy`, `low-saturation-expressive-eyes`, `lucid-dreamy`, `luminous-retro-impasto`, `minimal-flat-color`, `modern-oil-glamour`, `moe-pastel`, `oil-watercolor-blend`, `painterly-doodle`, `paper-watercolor`, `pencil-sketch`, `poster-graffiti`, `retro-comic-fusion`, `retro-oil-glamour`, `retro-tv-anime`, `semi-realistic`, `stable-vaporwave`, `tinted-sketch`, `vintage-collage`.
  - Variant 2:
    - `style.type` (string, required)
      Allowed values: `custom`.
    - `style.custom` (string, required)
      生成プロンプトの前置詞として直接注入される生のスタイルプロンプト文字列です。上級オプションです。誤った値を指定すると出力品質が低下する可能性があります。
- `loras` (object[], optional)
  出力スタイルやコンテンツを微調整するための LoRA アダプターです。組み合わせられる数はプランによって異なり（メンバーシップなしで 3 つ、最大 15 つ）、超えると `403 LORA_NUM_EXCEEDED` が返ります。

  生成モデルと同じベースモデル向けの LoRA を使用してください。LoRA のベースモデルは PixAI の LoRA ページに表示されています。

  LoRA modelId の見つけ方:
  1. PixAI で LoRA モデルページを開きます。
  2. 使用したい LoRA バージョンをクリックします。
  3. URL の末尾のパスセグメントをコピーします。これが LoRA バージョン ID です。

  URL 例: `https://pixai.art/model/<loraModelId>/<loraVersionId>` → LoRA バージョン ID は `<loraVersionId>` です。
  Items: 0 to 15.
- `loras[].modelId` (string, required)
  PixAI モデルマーケットの LoRA モデルバージョン ID です。
  Example: `"1744880666293972790"`.
- `loras[].weight` (number, optional)
  LoRA アダプターの影響度（重み）です。範囲は 0.0〜1.0 です。
  Default: `1`.
  Range: 0 to 1.
  Example: `0.7`.
- `loras[].triggerWords` (string, optional)
  この LoRA のカスタムトリガーワードです。省略した場合は LoRA のデフォルトのトリガーワードが自動的に追加され、空文字列を指定すると何も追加されません。
- `contextImages` (string[], optional)
  インコンテキスト生成用の参照画像です。キャラクターの一貫性を保つ、別の画像のポーズを使う、といった用途に使います。

  各要素はメディア ID です。完了したタスクの `outputs.mediaIds` の ID、または[画像・動画のアップロード](https://platform.pixai.art/ja/docs/api-v2/media/getImageUploadUrl)で返される ID を指定します。各画像は縦横とも 4000 px 未満である必要があります。
  Note: **Tsubaki.3**（`modelVersionId` `2024383379556065549`）のみ有効です。その他のモデルでは `400 BAD_REQUEST`（"This feature is not yet supported for this model"）が返ります。
  Items: 0 to 3.
  Example: `["1943547603237249965"]`.
- `seed` (integer, optional)
  再現性のある生成のためのランダムシードです。省略するとランダムに生成されます。
  Example: `42`.
- `batchSize` (integer, optional)
  1つのタスクで生成する画像の枚数です。指定できる値は `1` または `4` で、デフォルトは `1` です。
  Allowed values: `1`, `4`.
  Default: `1`.
  Example: `4`.
- `sampling` (object, optional)
  拡散プロセスを微調整するための高度なサンプリングパラメータです。すべてのフィールドは省略可能で、省略した場合はモデルのデフォルト値が使用されます。

  モデルごとの対応サンプリングメソッドは[モデル一覧](https://platform.pixai.art/ja/docs/references/models)ページを参照してください。
  Note: **SDXL** および **SD v1** モデルファミリーのみ使用可能です。
- `sampling.method` (string, optional)
  生成時に使用されるサンプラーアルゴリズムです。対応するメソッドはモデルによって異なります — [モデル一覧](https://platform.pixai.art/ja/docs/references/models)ページを参照してください。
  Example: `"DPM++ 2M Karras"`.
- `sampling.steps` (integer, optional)
  拡散ステップ数です。値を高くするとディテールが向上しますが、生成時間とコストが増加します。
  Range: 1 to 100.
  Example: `25`.
- `sampling.cfgScale` (number, optional)
  Classifier-Free Guidance (CFG) スケール。プロンプトへの忠実度と創造的自由度のバランスを制御します。値が高いほどプロンプトに忠実に従います。
  Example: `7`.
- `promptHelper` (string, optional)
  生成前にプロンプトを自動強化する組み込みプロンプトヘルパーを使用するかどうかを指定します。
  - `enable`: プロンプトを自動的に強化します（デフォルト）。
  - `disable`: プロンプトをそのまま使用します。
  - `low` / `medium`: Tsubaki.2 と Tsubaki.3 で、ヘルパーがプロンプトを書き換える度合いを指定します。その他のモデルではどちらも `enable` と同じ扱いです。
  Note: 有効化すると追加料金が発生します。
  Allowed values: `enable`, `disable`, `low`, `medium`.
  Default: `"enable"`.
- `callbackUrl` (string, optional)
  タスクのステータス更新を受け取るための公開 URL（Webhook）です。

  タスクのステータスが変化した際に、この URL に POST リクエストが送信されます。
  Example: `"https://your-server.example.com/webhook"`.
- `colorPalette` (object, optional)
  画像の配色を指定します。`GET /v2/color-palettes/presets` のプリセットを 1 件そのまま送り、`"source": "preset"` を追加してください。
  Note: **Tsubaki.3**（`modelVersionId` `2024383379556065549`）のみ有効です。その他のモデルでは `400 BAD_REQUEST`（"This feature is not yet supported for this model"）が返ります。
- `colorPalette.source` (string, required)
  Allowed values: `preset`, `user`.
- `colorPalette.id` (string, required)
- `colorPalette.name` (string, required)
- `colorPalette.palette` (object, required)
  画像全体の色と、必要に応じて背景とキャラクターの色です。`overall` または `background` が必須です。
- `colorPalette.palette.overall` (object, optional)
- `colorPalette.palette.overall.colors` (object[], required)
  Items: 1 to 12.
- `colorPalette.palette.overall.colors[].hex` (string, required)
  `#RRGGBB` 形式です。
- `colorPalette.palette.overall.colors[].ratio` (number, required)
  画像に占める割合（パーセント）です。
  Range: 0 to 100.
- `colorPalette.palette.background` (object, optional)
- `colorPalette.palette.background.colors` (object[], required)
  Items: 1 to 12.
- `colorPalette.palette.background.colors[].hex` (string, required)
  `#RRGGBB` 形式です。
- `colorPalette.palette.background.colors[].ratio` (number, required)
  画像に占める割合（パーセント）です。
  Range: 0 to 100.
- `colorPalette.palette.character` (object, optional)
- `colorPalette.palette.character.colors` (object[], required)
  Items: 1 to 12.
- `colorPalette.palette.character.colors[].hex` (string, required)
  `#RRGGBB` 形式です。
- `colorPalette.palette.character.colors[].ratio` (number, required)
  画像に占める割合（パーセント）です。
  Range: 0 to 100.
- `colorPalette.createdAt` (string, required)
- `colorPalette.updatedAt` (string, required)

Example:

```json
{
  "modelVersionId": "1983308862240288769",
  "prompt": "1girl, green hair, solo, standing",
  "aspectRatio": "9:16",
  "mode": "standard",
  "batchSize": 4,
  "seed": 12345
}
```

### Example (cURL)

```bash
curl -X POST https://api.pixai.art/v2/image/create \
  -H "Authorization: Bearer $PIXAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "modelVersionId": "1983308862240288769",
    "prompt": "1girl, green hair, solo, standing",
    "aspectRatio": "9:16",
    "mode": "standard",
    "batchSize": 4,
    "seed": 12345
  }'
```

### Responses

- `201`
  画像生成タスクを正常に作成しました。

  レスポンス例:
  ```json
  {
    "id": "1943547603237249965",
    "status": "waiting",
    "createdAt": "2025-11-07T14:54:35.000Z",
    "updatedAt": "2025-11-07T14:54:35.000Z",
    "outputs": { "mediaIds": [], "mediaUrls": [] }
  }
  ```
  Body fields:
  - `id` (string, required)
    タスクの一意の識別子。
  - `status` (string, required)
    タスクの現在のステータス。
    Allowed values: `waiting`, `running`, `completed`, `cancelled`, `failed`.
  - `createdAt` (string, required)
    タスクの作成時刻。
  - `updatedAt` (string, required)
    タスクの最終更新時刻。
  - `startedAt` (string, optional)
    タスクの開始時刻。
  - `endAt` (string, optional)
    タスクの終了時刻。
  - `taskKind` (string, optional)
    タスクが生成するもの。画像は `t2i` または `i2i`、`POST /v2/gen-task/inpaint` は `inpaint`、`POST /v2/frame-video/create` は `i2v-inhouse`、`POST /v2/reference-video/create` は `reference-video` です。
  - `paidQuota` (integer, optional)
    タスクに課金されたクレジット。
  - `taskStatusMsgI18n` (object, optional)
    `failed` になったタスクの失敗理由。
  - `taskStatusMsgI18n.key` (string, optional)
    変わらないメッセージキー。
  - `taskStatusMsgI18n.defaultMessage` (string, optional)
    英語のメッセージ。
  - `outputs` (object, optional)
    タスクで生成された出力。
  - `outputs.videoMediaId` (string, optional)
    動画タスクの場合、動画のメディア ID です。`GET /v2/media/batch?ids=<videoMediaId>` で解決し、`fileUrl` をダウンロードしてください。このとき `mediaIds` にはポスター画像だけが入ります。
  - `outputs.seed` (string, optional)
    使われたシード値（10 進数の文字列）。
  - `outputs.mediaIds` (string[], optional)
    生成された画像のメディア ID です。これらの ID を使用して各生成画像の詳細情報を取得できます。

    生成された画像は通常、恒久的には保持されません。できるだけ早く取得してください。
  - `outputs.mediaUrls` ((string | null)[], optional)
    生成された画像の公開 URL です。

    生成された画像は通常、恒久的には保持されません。できるだけ早く取得してください。画像が利用できない場合、その項目は `null` になることがあります。
- `400`
  タスク作成前にリクエストが拒否されました。理由は `code` で示されます:
  - `BAD_REQUEST`（`data.issues` あり）: ボディの検証に失敗しました（各 issue の `path` に該当フィールドが入ります）。または、このモデルが対応していないフィールドが指定されました（`message` に記載）。
  - `INVALID_ARGUMENT`: このモデルファミリーでは使えないフィールドです（SDXL モデルでの `mode`、Tsubaki での `sampling` など）。チェック対象は `mode` と `sampling` のみで、`mode` は Tsubaki モデル、`sampling` は SDXL と SD v1 でのみ使えます。モデルが受け付けない方を外してください。
  - `IMAGE_SIZE_NOT_ALLOWED`: `width`/`height` がモデルのサイズ範囲外です（`data.reason`）。`GET /v2/generation-model/{modelVersionId}/size-config` のサイズを使うか、代わりに `aspectRatio`/`size` を指定してください。
  - `INPUT_IMAGE_TOO_LARGE`: `contextImages` のいずれかの辺が 4000 px 以上です。
- `401`
  認証が必要です。有効な Bearer トークンを指定してください。
- `403`
  現在このタスクを実行できません。理由は `code` で示されます:
  - `INSUFFICIENT_BALANCE`: クレジットが不足しています。
  - `WAITING_NUM_EXCEEDED`: `waiting` 状態のタスクが多すぎます。いくつか実行が始まるまで待ってから送信してください（[制限](https://platform.pixai.art/ja/docs/quick-start/limits)を参照）。
  - `LORA_NUM_EXCEEDED`: `loras` がプランの上限を超えています。
- `404`
  `NOT_FOUND`: 指定した `modelVersionId` のモデルバージョンが存在しません。`FILE_NOT_FOUND`: `contextImages` のメディア ID が存在しません。
- `422`
  - `NSFW_PROMPT_REJECTED`: プロンプトがコンテンツモデレーションで拒否されました。表現を変えてください。サポートに問い合わせる際は `data.logId` をお伝えください。
  - `INVALID_INPUT`: このモデルまたはプランでは使えない値です（モデルが提供していない `mode` など）。`message` に該当する値が示されます。
- `500`
  内部サーバーエラーによりタスクの作成に失敗しました。 指数バックオフで再試行してください。
