openapi: 3.1.0
info:
  title: PixAI API - OpenAPI 2.0
  description: |
    ユーザーは、API を通じて生成された画像の著作権を保有します。PixAI はユーザー生成作品に対して著作権を主張しません。ただし、生成内容が第三者の権利を侵害しないこと、および適用される法令・規制に準拠することはユーザーの責任となります。

    PixAI の公式モデル（例：Haruka、Tsubaki）の著作権は PixAI に帰属します。承認済みユーザーに対して、商用利用を含むモデルの使用権を付与しますが、モデルファイル自体の転売や再配布は禁止されています。
  termsOfService: https://pixai.art/terms
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: 2.0.0
servers:
  - url: https://api.pixai.art/v2
tags:
  - name: image
    description: 画像の生成・編集エンドポイント
  - name: video
    description: 動画生成エンドポイント
  - name: task
    description: タスクとその結果の取得
  - name: media
    description: 入力ファイルのアップロードと、メディア ID から URL への変換
  - name: model
    description: モデル、LoRA、サイズ、カラーパレットの検索
paths:
  /image/create:
    post:
      tags:
        - image
      summary: 画像生成タスクの作成
      description: |
        簡略化された v2 API で非同期の画像生成タスクを開始します。レスポンスには作成されたタスクの ID が含まれます。

        v2 API は `aspectRatio`（アスペクト比）、`mode`（品質モード）、名前付き `style` プリセットなど、ユーザーフレンドリーなパラメータを提供します。v1 の生ピクセル寸法や内部パラメータ名を置き換えます。
      operationId: createImage
      x-codeSamples:
        - id: curl
          lang: bash
          label: cURL
          source: |
            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
              }'
        - id: js
          lang: javascript
          label: JavaScript (fetch)
          source: |
            const response = await fetch("https://api.pixai.art/v2/image/create", {
              method: "POST",
              headers: {
                "Authorization": `Bearer ${PIXAI_API_KEY}`,
                "Content-Type": "application/json",
              },
              body: JSON.stringify({
                modelVersionId: "1983308862240288769",
                prompt: "1girl, green hair, solo, standing",
                aspectRatio: "9:16",
                mode: "standard",
                batchSize: 4,
                seed: 12345,
              }),
            });
            const task = await response.json();
            console.log(task);
        - id: python
          lang: python
          label: Python (requests)
          source: |
            import requests

            response = requests.post(
                "https://api.pixai.art/v2/image/create",
                headers={
                    "Authorization": f"Bearer {PIXAI_API_KEY}",
                    "Content-Type": "application/json",
                },
                json={
                    "modelVersionId": "1983308862240288769",
                    "prompt": "1girl, green hair, solo, standing",
                    "aspectRatio": "9:16",
                    "mode": "standard",
                    "batchSize": 4,
                    "seed": 12345,
                },
            )
            task = response.json()
            print(task)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateImageRequest"
            example:
              modelVersionId: "1983308862240288769"
              prompt: "1girl, green hair, solo, standing"
              aspectRatio: "9:16"
              mode: "standard"
              batchSize: 4
              seed: 12345
      responses:
        "201":
          description: |
            画像生成タスクを正常に作成しました。

            レスポンス例:
            ```json
            {
              "id": "1943547603237249965",
              "status": "waiting",
              "createdAt": "2025-11-07T14:54:35.000Z",
              "updatedAt": "2025-11-07T14:54:35.000Z",
              "outputs": { "mediaIds": [], "mediaUrls": [] }
            }
            ```
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        "400":
          description: |
            タスク作成前にリクエストが拒否されました。理由は `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 以上です。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
              example:
                defined: false
                code: BAD_REQUEST
                status: 400
                message: Input validation failed
                data:
                  issues:
                    - code: custom
                      path: []
                      message: Either modelId or modelVersionId must be provided
        "401":
          description: 認証が必要です。有効な Bearer トークンを指定してください。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: |
            現在このタスクを実行できません。理由は `code` で示されます:
            - `INSUFFICIENT_BALANCE`: クレジットが不足しています。
            - `WAITING_NUM_EXCEEDED`: `waiting` 状態のタスクが多すぎます。いくつか実行が始まるまで待ってから送信してください（[制限](/ja/docs/quick-start/limits)を参照）。
            - `LORA_NUM_EXCEEDED`: `loras` がプランの上限を超えています。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "404":
          description: |
            `NOT_FOUND`: 指定した `modelVersionId` のモデルバージョンが存在しません。`FILE_NOT_FOUND`: `contextImages` のメディア ID が存在しません。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "422":
          description: |
            - `NSFW_PROMPT_REJECTED`: プロンプトがコンテンツモデレーションで拒否されました。表現を変えてください。サポートに問い合わせる際は `data.logId` をお伝えください。
            - `INVALID_INPUT`: このモデルまたはプランでは使えない値です（モデルが提供していない `mode` など）。`message` に該当する値が示されます。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          description: 内部サーバーエラーによりタスクの作成に失敗しました。 指数バックオフで再試行してください。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - bearerAuth: []
  /frame-video/create:
    post:
      tags:
        - video
      summary: 画像から動画を生成するタスクの作成
      description: |
        PixAI の Tsubaki 動画モデルで画像を動画にします。動画は `firstFrameMediaId` から始まり、`lastFrameMediaId` を指定した場合はその画像で終わります。出力は最初のフレームのアスペクト比を維持します。

        フレームには画像のメディア ID を指定します。`POST /v2/media/image/upload-url` で自分の画像をアップロードするか、生成済みの画像を再利用してください。他のユーザーが所有するメディアは拒否されます。

        画像から動画への生成には PixAI メンバーシップが必要です。クレジットはタスク作成時に消費されます。結果は `GET /v2/task/{id}` をポーリングして取得します。完了したタスクの動画は `outputs.videoMediaId` です。
      operationId: createFrameVideo
      x-codeSamples:
        - id: curl
          lang: bash
          label: cURL
          source: |
            curl -X POST https://api.pixai.art/v2/frame-video/create \
              -H "Authorization: Bearer $PIXAI_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "model": "tbkv1.0.1",
                "firstFrameMediaId": "1943547603237249965",
                "prompt": "she turns around and smiles, hair blowing in the wind",
                "duration": 5
              }'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                model:
                  enum:
                    - tbkv1.0.1
                    - tbkv1.0
                  type: string
                  description: 動画モデルです。`tbkv1.0.1` が最新の Tsubaki 動画モデルです。
                firstFrameMediaId:
                  type: string
                  description: 最初のフレームの画像メディア ID です。
                lastFrameMediaId:
                  type: string
                  description: 最後のフレームの画像メディア ID です。最初のフレームと同じ画像を指定するとループ動画になります。
                prompt:
                  default: null
                  type:
                    - string
                    - "null"
                  description: 動画の中で起こる内容です。
                duration:
                  type: integer
                  minimum: 5
                  maximum: 15
                  default: 5
                  description: 長さ（秒、整数）です。
                mode:
                  enum:
                    - basic
                    - professional
                  type: string
                  default: basic
                  description: "`professional` は `tbkv1.0.1` で 1080p へのアップスケールを追加し、料金が高くなります。`tbkv1.0` では効果がありません。"
                generateAudio:
                  type: boolean
                  default: true
                  description: サウンドトラックを生成するかどうか。
                audioLanguage:
                  default: null
                  enum:
                    - none
                    - chinese
                    - english
                    - japanese
                    - korean
                    - null
                  type:
                    - string
                    - "null"
                  description: サウンドトラック内の音声の言語です。音声なしは `none` です。
              required:
                - model
                - firstFrameMediaId
              additionalProperties: false
            example:
              model: tbkv1.0.1
              firstFrameMediaId: "1943547603237249965"
              prompt: she turns around and smiles, hair blowing in the wind
              duration: 5
      responses:
        "201":
          description: タスクを作成しました。その `id` で `GET /v2/task/{id}` をポーリングしてください。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        "400":
          description: |
            - `INVALID_REFERENCE_MEDIA`: フレームが存在しない、画像ではない、または他のユーザーのものです。`data.code` は `invalid_input` または `media_not_owned` で、`data.mediaId` に該当するフレームが示されます。
            - `BAD_REQUEST`（`data.issues` あり）: ボディの検証に失敗しました。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/CannotRun"
        "500":
          $ref: "#/components/responses/CreationFailed"
      security:
        - bearerAuth: []
  /reference-video/create:
    post:
      tags:
        - video
      summary: 参照動画生成タスクの作成
      description: |
        参照画像に基づいて動画を生成します。モデルによっては参照動画と参照音声も使用できます。

        受け付ける参照はモデルごとに異なります:

        - `tbkv1.0.1`、`tbkv1.0`（Tsubaki）: 画像 1〜6、動画不可、音声クリップ最大 3、`duration` 5〜15。
        - `v4.0`、`v4.0.1`（Seedance 2、Seedance 2 Fast）: 画像最大 9、動画最大 3、音声クリップ最大 3、`duration` 4〜15。
        - `v4.0.3`（Seedance 2.5）: 画像最大 30、動画最大 10、音声クリップ最大 10、`duration` 4〜30。
        - `v3.3`（Vidu）: 画像 1〜7、動画・音声不可、`duration` 3〜16。

        どのモデルでも画像または動画が 1 つ以上必要です。ただし `v4.0.3` は音声のみでも受け付けます。

        参照ファイルは次の制限を満たす必要があります:

        - 動画: MP4 または MOV、H.264 または HEVC、24〜60 fps、1 クリップ 2〜15 秒・合計 15 秒（`v4.0.3` では 30 秒）、最大 50 MB（`v4.0.3` では 200 MB）。
        - 音声: WAV または MP3、1 クリップ 2〜15 秒・合計 15 秒（`v4.0.3` では 30 秒）、15 MiB 未満。

        送信前に `GET /v2/media/{mediaId}/info` でファイルを確認してください。`v4.0` と `v4.0.1` では、数やクリップの長さはタスクの課金後にチェックされます。制限に違反したタスクは拒否されずに失敗します。

        クレジットはタスク作成時に消費されます。結果は `GET /v2/task/{id}` をポーリングして取得します。完了したタスクの動画は `outputs.videoMediaId` です。
      operationId: createReferenceVideo
      x-codeSamples:
        - id: curl
          lang: bash
          label: cURL
          source: |
            curl -X POST https://api.pixai.art/v2/reference-video/create \
              -H "Authorization: Bearer $PIXAI_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "model": "tbkv1.0.1",
                "prompt": "the girl walks through the city at night",
                "referenceImageMediaIds": ["1943547603237249965"],
                "ratio": "9:16",
                "duration": 5
              }'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                model:
                  type: string
                  minLength: 1
                  enum:
                    - tbkv1.0.1
                    - tbkv1.0
                    - v4.0
                    - v4.0.1
                    - v4.0.3
                    - v3.3
                  description: 動画モデルです。各モデルが受け付ける参照は上の表を参照してください。不明な値には `403 MODEL_VERSION_NOT_EXISTS` が返ります。
                prompt:
                  default: null
                  type:
                    - string
                    - "null"
                  description: 動画の中で起こる内容です。参照の使い方を記述してください。
                referenceImageMediaIds:
                  type: array
                  items:
                    type: string
                  default: []
                  description: 画像のメディア ID です。
                referenceVideoMediaIds:
                  type: array
                  items:
                    type: string
                  default: []
                  description: 動画のメディア ID です。Tsubaki と Vidu では使えません。
                referenceAudioMediaIds:
                  type: array
                  items:
                    type: string
                  default: []
                  description: "`POST /v2/media/audio/upload-url` でアップロードした音声のメディア ID です。Vidu では使えません。"
                duration:
                  type: integer
                  default: 5
                  description: 長さ（秒、整数）です。指定できる範囲は `model` によって異なります。
                ratio:
                  enum:
                    - adaptive
                    - 1:1
                    - 2:3
                    - 3:2
                    - 3:4
                    - 4:3
                    - 9:16
                    - 16:9
                    - 21:9
                  type: string
                  description: |
                    出力のアスペクト比です。省略するか `adaptive` を指定すると参照に合わせます。Seedance モデルは `2:3` と `3:2` に対応しておらず、Vidu はこのフィールドを無視します。
                mode:
                  enum:
                    - basic
                    - professional
                  type: string
                  default: basic
                  description: "`professional` はアップスケール（`v4.0` で 1080p、`v4.0.1` で 720p）を追加し、料金が高くなります。`v4.0.3` では使えません。"
                generateAudio:
                  type: boolean
                  default: true
                  description: サウンドトラックを生成するかどうか。
                audioLanguage:
                  default: null
                  enum:
                    - none
                    - chinese
                    - english
                    - japanese
                    - korean
                    - null
                  type:
                    - string
                    - "null"
                  description: サウンドトラック内の音声の言語です。音声なしは `none` です。
              required:
                - model
            example:
              model: tbkv1.0.1
              prompt: the girl walks through the city at night
              referenceImageMediaIds:
                - "1943547603237249965"
              ratio: 9:16
              duration: 5
      responses:
        "201":
          description: タスクを作成しました。その `id` で `GET /v2/task/{id}` をポーリングしてください。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        "400":
          description: |
            - `BAD_REQUEST`（`data.issues` あり）: ボディの検証に失敗しました（`v4.0.3` で参照が多すぎる場合など）。
            - `VALIDATION_ERROR`: このモデルでは無効な組み合わせです（`v4.0.3` での `mode: professional`、Vidu への動画や音声の参照など）。`message` に詳細が示されます。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/CannotRun"
        "422":
          description: |
            `INVALID_INPUT`: タスクの課金前に参照ファイルが拒否されました。`message` は `Invalid reference media: <reason>` の形式で、メディア ID が括弧付きで続くことがあります。理由は `too_many_reference_images`、`reference_video_not_supported`、`unsupported_reference_video_format` などです。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "500":
          $ref: "#/components/responses/CreationFailed"
      security:
        - bearerAuth: []
  /gen-task/inpaint:
    post:
      tags:
        - image
      summary: インペイント・アウトペイント・リドロータスクの作成
      description: |
        既存の画像を編集します:

        - **インペイント**（`fillType: inpaint`）: マスクした領域を描き直します。
        - **アウトペイント**（`fillType: outpaint`）: 画像を外側へ拡張します。元画像をより大きな白いキャンバスに配置し、それを `baseImageMediaId` として送信してください。マスクで新しい領域を指定します。
        - **リドロー**（`fillType: inpaint`、マスクなし）: 画像全体を描き直します。`strength` を下げるほど元画像に近くなります。

        マスクを使う編集には追加の画像が 2 枚必要で、必ず両方を一緒に送信します:

        - `maskMediaId`: ベース画像と同じサイズで、描き直す部分を白、残す部分を黒にした画像です。
        - `maskedImageMediaId`: ベース画像のうち、マスクの白い部分をグレー（`#808080`）で塗りつぶした画像です。

        出力のサイズは、マスクを送信した場合はマスク済み画像、それ以外はベース画像と同じになります。画像はメディア ID で指定します。`POST /v2/media/image/upload-url` を参照してください。

        `modelPreset: "v1"` を使用してください。`GET /v2/gen-task/inpaint/constraints` でプリセットのサイズ制限と `sdeditPreset` 名を確認できます。クレジットはタスク作成時に消費されます。結果は `GET /v2/task/{id}` の `outputs.mediaIds[0]` です。
      operationId: createInpaint
      x-codeSamples:
        - id: curl
          lang: bash
          label: cURL
          source: |
            curl -X POST https://api.pixai.art/v2/gen-task/inpaint \
              -H "Authorization: Bearer $PIXAI_API_KEY" \
              -H "Content-Type: application/json" \
              -d '{
                "modelPreset": "v1",
                "fillType": "inpaint",
                "baseImageMediaId": "1943547603237249965",
                "maskMediaId": "1943547603237249966",
                "prompt": "red scarf"
              }'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                modelPreset:
                  type: string
                  minLength: 1
                  description: インペイントモデルです。`v1` を使用してください。
                  example: v1
                fillType:
                  enum:
                    - inpaint
                    - outpaint
                  type: string
                baseImageMediaId:
                  type: string
                  description: 編集する画像の画像メディア ID です。
                maskMediaId:
                  type: string
                  description: マスクの画像メディア ID です。描き直す部分を白、残す部分を黒にします。`maskedImageMediaId` と一緒に送信するか、両方を省略して画像全体を描き直します。
                maskedImageMediaId:
                  type: string
                  description: マスクの白い部分を `#808080` で塗りつぶしたベース画像の画像メディア ID です。`maskMediaId` と一緒に送信してください。
                prompt:
                  type: string
                  maxLength: 10000
                  default: ""
                  description: 編集する領域に描く内容です。
                strength:
                  type: number
                  minimum: 0
                  maximum: 1
                  multipleOf: 0.01
                  description: 結果が元画像からどれだけ離れてよいかです。低いほど元画像に近くなります。
                seed:
                  type: integer
                  description: ランダムシードです。省略するとランダムに生成されます。
                promptHelper:
                  enum:
                    - enable
                    - disable
                    - low
                    - medium
                  type: string
                  default: enable
                  description: PixAI がプロンプトをどの程度拡張してよいかを指定します。
                sdeditPreset:
                  type: string
                  minLength: 1
                  maxLength: 64
                  description: "`GET /v2/gen-task/inpaint/constraints` で取得したリドロープリセット名です。リドロープリセットのないプリセットに指定すると `SDEDIT_NOT_AVAILABLE` が返ります。"
                sdedit:
                  type: object
                  properties:
                    spectralScale:
                      type: number
                      minimum: 0
                      maximum: 1
                    hfsBlurSigma:
                      type: number
                      minimum: 0
                      maximum: 32
                    hfsEnd:
                      type: number
                      minimum: 0
                      maximum: 1
                    colorCorrection:
                      type: boolean
                      description: 元画像の色に合わせます。
                  description: リドローの微調整です。`sdeditPreset` を指定した場合、ここからは `colorCorrection` のみが使われます。
              required:
                - baseImageMediaId
                - fillType
                - modelPreset
            example:
              modelPreset: v1
              fillType: inpaint
              baseImageMediaId: "1943547603237249965"
              maskMediaId: "1943547603237249966"
              prompt: red scarf
      responses:
        "201":
          description: タスクを作成しました。その `id` で `GET /v2/task/{id}` をポーリングしてください。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        "400":
          description: |
            - `INVALID_MODEL_PRESET`: 不明な `modelPreset` です。
            - `INVALID_MEDIA`: 画像メディア ID が存在しないか、画像ではありません。
            - `INVALID_SDEDIT_PRESET`: 不明な `sdeditPreset` です。
            - `SDEDIT_NOT_AVAILABLE`: この `modelPreset` は `sdeditPreset` も `sdedit` も受け付けません。
            - `BAD_REQUEST`（`data.issues` あり）: ボディの検証に失敗しました。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/CannotRun"
        "500":
          $ref: "#/components/responses/CreationFailed"
      security:
        - bearerAuth: []
  /gen-task/inpaint/constraints:
    get:
      tags:
        - image
      summary: インペイントプリセットの制限の取得
      description: インペイントの `modelPreset` のサイズ制限とリドロープリセットを返します。不明なプリセットの場合はエラーではなく `null` のフィールドを返します。認証は不要です。
      operationId: getInpaintConstraints
      parameters:
        - name: modelPreset
          in: query
          required: true
          schema:
            type: string
            minLength: 1
          example: v1
      responses:
        "200":
          description: プリセットの制限。
          content:
            application/json:
              schema:
                type: object
                properties:
                  modelPreset:
                    type: string
                  constraints:
                    type:
                      - object
                      - "null"
                    description: 画像のサイズ制限です。プリセットに制限がない場合は `null` です。
                    properties:
                      minWidth:
                        type: integer
                      maxWidth:
                        type: integer
                      minHeight:
                        type: integer
                      maxHeight:
                        type: integer
                      maxPixels:
                        type: integer
                        description: 幅 × 高さの最大値です。
                      dimensionStep:
                        type: integer
                        description: 幅と高さはこの値の倍数である必要があります。
                  sdeditPresets:
                    type:
                      - object
                      - "null"
                    description: 名前ごとのリドロープリセットです。`sdeditPreset` に使います。
                    additionalProperties:
                      type: object
                  defaultSdeditPreset:
                    type:
                      - string
                      - "null"
      security:
        - {}
        - bearerAuth: []
  /task/{id}:
    get:
      tags:
        - task
      summary: タスクの取得
      description: |
        任意の v2 エンドポイントで作成したタスクを取得します。`status` が `completed`、`failed`、`cancelled` のいずれかになるまで、数秒ごとにポーリングしてください。

        結果の場所:

        - 画像（`taskKind` が `t2i`、`i2i`、`inpaint`）: `outputs.mediaIds` と `outputs.mediaUrls`。
        - 動画（`taskKind` が `i2v-inhouse`、`reference-video`）: `outputs.videoMediaId`。`GET /v2/media/batch?ids=<videoMediaId>` で解決し、`fileUrl` をダウンロードしてください。この場合 `outputs.mediaIds` にはポスター画像のみが入ります。

        生成されたメディアは恒久的には保持されません。完了後はできるだけ早く結果をダウンロードしてください。
      operationId: getTask
      x-codeSamples:
        - id: curl
          lang: bash
          label: cURL
          source: |
            curl https://api.pixai.art/v2/task/1943547603237249965 \
              -H "Authorization: Bearer $PIXAI_API_KEY"
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: タスク ID です。
        - name: with_parameters
          in: query
          schema:
            type: string
            enum:
              - "true"
          description: "`true` を指定すると、保存されたタスクパラメータが `parameters` に含まれます。"
      responses:
        "200":
          description: タスク。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Task"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: "`NOT_FOUND`: この ID のタスクが存在しないか、閲覧できません。API キーなしのリクエストでは、どのタスクでもこの応答になります。"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - bearerAuth: []
  /media/image/upload-url:
    post:
      tags:
        - media
      summary: 画像のアップロード URL の取得
      description: |
        入力として使う画像（`contextImages` の要素、動画のフレーム、インペイントのベース画像など）をアップロードする手順のステップ 1 です。

        1. このエンドポイントを呼び出して `uploadUrl` と `externalId` を取得します。
        2. 画像の生バイトを、ファイルの実際の `Content-Type`（例: `image/png`）を付けて HTTP `PUT` で `uploadUrl` に送信します。マルチパートフォームは使用しないでください。
        3. `externalId` を指定して `POST /v2/media/image/register` を呼び出します。返される `id` が、他のエンドポイントに渡すメディア ID です。
      operationId: getImageUploadUrl
      x-codeSamples:
        - id: curl
          lang: bash
          label: cURL
          source: |
            # 1. アップロード URL を取得
            UPLOAD=$(curl -s -X POST https://api.pixai.art/v2/media/image/upload-url \
              -H "Authorization: Bearer $PIXAI_API_KEY" \
              -H "Content-Type: application/json" -d '{}')
            URL=$(echo "$UPLOAD" | jq -r .uploadUrl)
            EXTERNAL_ID=$(echo "$UPLOAD" | jq -r .externalId)

            # 2. バイトをアップロード
            curl -X PUT "$URL" -H "Content-Type: image/png" --data-binary @input.png

            # 3. 登録してメディア ID を取得
            curl -s -X POST https://api.pixai.art/v2/media/image/register \
              -H "Authorization: Bearer $PIXAI_API_KEY" \
              -H "Content-Type: application/json" \
              -d "{\"externalId\": \"$EXTERNAL_ID\"}" | jq -r .id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                isEphemeral:
                  type: boolean
                  default: false
                  description: ファイルを短期間だけ使う生成入力としてマークします。エフェメラルファイルは非公開で、その URL は署名付きで有効期限があります。
            example: {}
      responses:
        "200":
          description: アップロード先。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadUrl"
        "401":
          $ref: "#/components/responses/Unauthorized"
      security:
        - bearerAuth: []
  /media/image/register:
    post:
      tags:
        - media
      summary: アップロードした画像の登録
      description: |
        画像アップロードのステップ 3 です。アップロードしたファイルをメディアアイテムにします。`uploadUrl` への `PUT` が成功した後に呼び出してください。返される `id` が、他のエンドポイントに渡すメディア ID です。
      operationId: registerImage
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                externalId:
                  type: string
                  format: uuid
                  description: "`POST /v2/media/image/upload-url` で返された `externalId` です。"
                isEphemeral:
                  type: boolean
                  description: "`upload-url` に送信したものと同じ値を指定してください。"
              required:
                - externalId
            example:
              externalId: 3f2b8c1e-6a4d-4f6e-9b1a-2c7d5e8f9a01
      responses:
        "200":
          description: 登録された画像。処理が終わる数秒後までは `width` と `height` が `0` のことがあります。必要な場合は `GET /v2/media/batch` から取得してください。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Media"
        "401":
          $ref: "#/components/responses/Unauthorized"
      security:
        - bearerAuth: []
  /media/audio/upload-url:
    post:
      tags:
        - media
      summary: 音声ファイルのアップロード URL の取得
      description: |
        `POST /v2/reference-video/create` の `referenceAudioMediaIds` に使う音声クリップをアップロードする手順のステップ 1 です。流れは画像と同じです。ファイルの `Content-Type`（`audio/mpeg` または `audio/wav`）を付けてバイトを `uploadUrl` に `PUT` し、その後 `POST /v2/media/audio/register` を呼び出します。

        受け付けるのは WAV と MP3 のみで、1 クリップあたり 15 MiB 未満です。長さの制限は動画モデルによって異なり、アップロード時ではなく動画タスクの作成時にチェックされます。
      operationId: getAudioUploadUrl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                isEphemeral:
                  type: boolean
                  default: false
                  description: ファイルを短期間だけ使う生成入力としてマークします。エフェメラルファイルは非公開で、その URL は署名付きで有効期限があります。
            example: {}
      responses:
        "200":
          description: アップロード先。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadUrl"
        "401":
          $ref: "#/components/responses/Unauthorized"
      security:
        - bearerAuth: []
  /media/audio/register:
    post:
      tags:
        - media
      summary: アップロードした音声ファイルの登録
      description: 音声クリップのアップロードのステップ 3 です。返される `id` が、`referenceAudioMediaIds` に渡すメディア ID です。
      operationId: registerAudio
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                externalId:
                  type: string
                  minLength: 1
                  description: "`POST /v2/media/audio/upload-url` で返された `externalId` です。"
              required:
                - externalId
            example:
              externalId: 3f2b8c1e-6a4d-4f6e-9b1a-2c7d5e8f9a01
      responses:
        "200":
          description: 登録された音声ファイル。
          content:
            application/json:
              schema:
                type: object
                required:
                  - id
                properties:
                  id:
                    type: string
                    description: メディア ID です。
                  fileUrl:
                    type:
                      - string
                      - "null"
                    description: ファイルの URL です。
                  duration:
                    type:
                      - number
                      - "null"
                    description: 長さ（秒）です。
                  size:
                    type:
                      - number
                      - "null"
                    description: サイズ（バイト）です。
                  codec:
                    type:
                      - string
                      - "null"
        "401":
          $ref: "#/components/responses/Unauthorized"
      security:
        - bearerAuth: []
  /media/{mediaId}/info:
    get:
      tags:
        - media
      summary: 動画・音声ファイルの情報の取得
      description: |
        動画または音声のメディアアイテムの長さ、サイズ、コンテナ、コーデックを返します。参照動画タスクを作成する前に、参照ファイルがモデルの制限を満たしているか確認できます。
      operationId: getMediaInfo
      parameters:
        - name: mediaId
          in: path
          required: true
          schema:
            type: string
          description: 動画または音声のメディア ID です。
      responses:
        "200":
          description: メディアのメタデータ。
          content:
            application/json:
              schema:
                type: object
                properties:
                  mediaId:
                    type: string
                  durationSeconds:
                    type:
                      - number
                      - "null"
                    description: 長さ（秒）です。
                  sizeBytes:
                    type:
                      - string
                      - "null"
                    description: サイズ（バイト）を 10 進数の文字列で表したものです。
                  containers:
                    type: array
                    items:
                      type: string
                    description: "コンテナ形式（小文字）です。例: `mp3`、`mov`。"
                  videoStreams:
                    type: array
                    description: 動画ストリームごとに 1 要素です。
                    items:
                      type: object
                      properties:
                        codec:
                          type: string
                        width:
                          type: integer
                        height:
                          type: integer
                        averageFrameRate:
                          type: number
                  audioStreams:
                    type: array
                    description: 音声ストリームごとに 1 要素です。
                    items:
                      type: object
                      properties:
                        codec:
                          type: string
        "400":
          description: "`NOT_VIDEO_OR_AUDIO`: メディアが画像です。"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "404":
          description: "`MEDIA_NOT_FOUND`: この ID のメディアは存在しません。"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
      security:
        - bearerAuth: []
  /media/batch:
    get:
      tags:
        - media
      summary: ID によるメディア URL の取得
      description: |
        最大 100 件のメディア ID を URL に解決します。完了したタスクの `outputs.mediaIds` や `outputs.videoMediaId` などに使います。公開メディアの場合、認証は不要です。

        存在しない ID は結果から除外され、結果の順序も保証されないため、各アイテムは `id` で照合してください。
      operationId: batchGetMedia
      parameters:
        - name: ids
          in: query
          required: true
          schema:
            anyOf:
              - type: string
              - type: array
                items:
                  type: string
            description: Media IDs to resolve (1–100). Accepts comma-separated (`?ids=1,2,3`), bracket notation (`?ids[]=1&ids[]=2`), or repeated (`?ids=1&ids=2`).
            type: string
          description: "カンマ区切りのメディア ID（1〜100 件）です。例: `?ids=1,2,3`。パラメータを繰り返す形式（`?ids=1&ids=2`）も使えます。"
      responses:
        "200":
          description: 見つかったメディアアイテム。
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Media"
      security:
        - {}
        - bearerAuth: []
  /generation-model/search:
    get:
      tags:
        - model
      summary: モデルと LoRA の検索
      description: |
        [PixAI モデルマーケット](https://pixai.art/model)を検索します。`modelVersionId` に使うベースモデルや、`POST /v2/image/create` の `loras` に使う LoRA を探すのに使います。

        結果を使う際は、`id` ではなく `latestAvailableVersionId` を渡してください。生成エンドポイントは**バージョン** ID を受け取ります。LoRA のデフォルトのトリガーワードは `latestAvailableVersion.extra.triggerWords` にあります。

        ベースモデルで使える LoRA を探すには、`usageType=LORA` と、`loraBaseModelTypes` にベースモデルのタイプ（モデルアイテムの `type`、例: `SDXL_MODEL`）を指定します。

        結果はリクエスト元によって異なります。API キーを送信すると、アカウントと同じコンテンツレーティングが適用されます。匿名リクエストにはより厳しいフィルタリングが適用されます。
      operationId: searchGenerationModels
      parameters:
        - name: usageType
          in: query
          required: true
          schema:
            anyOf:
              - const: ALL
              - const: MODEL
              - const: LORA
            type: string
            enum:
              - ALL
              - MODEL
              - LORA
          description: "`MODEL` はベースモデル、`LORA` は LoRA、`ALL` は両方です。"
        - name: keyword
          in: query
          schema:
            type: string
            minLength: 1
            maxLength: 256
          description: 自由入力の検索語です。結果は関連性と人気順に並びます。キーワードなしの場合は人気順です。
        - name: loraBaseModelTypes
          in: query
          schema:
            type: string
          description: "`usageType=LORA` の場合: LoRA が対応すべきベースモデルタイプをカンマ区切りで指定します。例: `SDXL_MODEL`。"
        - name: baseModelIds
          in: query
          schema:
            type: string
          description: "`usageType=LORA` の場合: LoRA が対応すべきベースモデル ID をカンマ区切りで指定します。"
        - name: source
          in: query
          schema:
            enum:
              - ANY
              - PIXAI
              - EXTERNAL
            type: string
            default: ANY
          description: "`usageType=LORA` の場合: `PIXAI` は PixAI で学習した LoRA、`EXTERNAL` はインポートされた LoRA です。"
        - name: baseModelType
          in: query
          schema:
            type: string
          description: "`usageType=MODEL` の場合: モデルタイプをカンマ区切りで指定します。例: `SDXL_MODEL,MMDIT26B_MODEL`。"
        - name: permittedUse
          in: query
          schema:
            enum:
              - COMMERCIAL
              - PERSONAL
            type: string
          description: ライセンスでこの用途が許可されているモデルのみを返します。
        - name: postedWithin
          in: query
          schema:
            enum:
              - today
              - this-week
              - this-month
            type: string
        - name: authorId
          in: query
          schema:
            type: string
          description: このユーザーのモデルのみを返します。
        - name: size
          in: query
          schema:
            type: integer
            maximum: 50
            exclusiveMinimum: 0
            default: 24
            minimum: 1
          description: ページサイズです。
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            maximum: 10000
            default: 0
          description: スキップする結果の数です。ページ間で結果がわずかに重複することがあるため、`id` で重複を除いてください。
      responses:
        "200":
          description: 結果の 1 ページ。
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - hasMore
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ModelListItem"
                  hasMore:
                    type: boolean
                    description: 次のページがある可能性があるかどうか。
      security:
        - {}
        - bearerAuth: []
  /generation-model/{id}:
    get:
      tags:
        - model
      summary: モデルまたは LoRA の取得
      description: "**モデル** ID（検索結果の `id`）で 1 つのモデルを取得します。"
      operationId: getGenerationModel
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: モデル ID です。
      responses:
        "200":
          description: モデル。
          content:
            application/json:
              schema:
                allOf:
                  - $ref: "#/components/schemas/ModelListItem"
                  - type: object
                    properties:
                      triggerWords:
                        type:
                          - string
                          - "null"
                        description: 最新バージョンのデフォルトのトリガーワードです。
        "404":
          $ref: "#/components/responses/ModelNotFound"
      security:
        - {}
        - bearerAuth: []
  /generation-model/{modelId}/versions:
    get:
      tags:
        - model
      summary: モデルのバージョン一覧の取得
      description: モデルのバージョンを新しい順に一覧表示します。古いバージョンを固定して使うには、そのバージョンの `id` を `modelVersionId` または `loras[].modelId` として渡します。
      operationId: listGenerationModelVersions
      parameters:
        - name: modelId
          in: path
          required: true
          schema:
            type: string
          description: モデル ID です。
        - name: baseModelType
          in: query
          schema:
            enum:
              - ANY_LORA
              - ANY_MODEL
              - ANY_NON_SDXL_LORA
              - ANY_NON_USER_LORA
              - ANY_SDXL_LORA
              - ANY_USER_LORA
              - ANY_VAE
              - CHAT
              - DIT5A_MODEL_INTERNAL
              - DIT7A_LORA
              - DIT7A_MODEL
              - DIT7A_VAE
              - DIT7B_LORA
              - DIT7B_MODEL
              - DIT7B_VAE
              - DIT7C_LORA
              - DIT7C_MODEL
              - DIT7C_VAE
              - DIT7D_LORA
              - DIT7D_MODEL
              - DIT7D_VAE
              - DIT7_LORA
              - DIT7_MODEL
              - DIT7_VAE
              - DIT9_LORA
              - DIT9_MODEL
              - DIT9_VAE
              - LORA
              - MMDIT26A_MODEL
              - MMDIT26B_MODEL
              - MULTI_LORA
              - SD3_MEDIUM_MODEL
              - SDXL_LORA
              - SDXL_MODEL
              - SDXL_VAE
              - SD_V1_MODEL
              - UNKNOWN_LORA
              - UNKNOWN_MODEL
              - USER_DIT26A_MODEL
              - USER_DIT26B_MODEL
              - USER_LORA
              - USER_MULTI_LORA
              - USER_SDXL_LORA
              - VAE
              - VIDEO_MODEL
              - VIDEO_MODEL_LORA
              - Z_IMAGE_V1_MODEL
            type: string
          description: このベースモデルタイプ向けのバージョンのみを返します。
      responses:
        "200":
          description: バージョン一覧。
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ModelVersion"
        "404":
          $ref: "#/components/responses/ModelNotFound"
      security:
        - {}
        - bearerAuth: []
  /generation-model-version/{id}:
    get:
      tags:
        - model
      summary: モデルバージョンの取得
      description: "**バージョン** ID（生成エンドポイントが受け取る ID）で 1 つのモデルバージョンを取得します。生成前に LoRA のトリガーワードやベースモデルを調べるのに使います。"
      operationId: getGenerationModelVersion
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          description: モデルバージョン ID です。
      responses:
        "200":
          description: バージョン。
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ModelVersion"
        "404":
          $ref: "#/components/responses/ModelNotFound"
      security:
        - {}
        - bearerAuth: []
  /generation-model/{modelVersionId}/size-config:
    get:
      tags:
        - model
      summary: モデルバージョンが受け付けるサイズの取得
      description: |
        `POST /v2/image/create` の `width`/`height` にモデルバージョンが受け付けるサイズを一覧表示します。パスの名前に反して、パラメータは**バージョン** ID です。

        カスタムの `width`/`height` は、いずれかの範囲の `minWidth`〜`maxWidth` と `minHeight`〜`maxHeight` に収まり、その `step` の倍数である必要があります。プリセットは既定のサイズで、これらの範囲外にある場合もあります。`accessStatus` が `membership_required` の項目は、アカウントより上位のメンバーシップが必要です。
      operationId: getModelSizeConfig
      parameters:
        - name: modelVersionId
          in: path
          required: true
          schema:
            type: string
          description: モデルバージョン ID です。
      responses:
        "200":
          description: サイズの範囲。
          content:
            application/json:
              schema:
                type: object
                properties:
                  ranges:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        minWidth:
                          type: integer
                        maxWidth:
                          type: integer
                        minHeight:
                          type: integer
                        maxHeight:
                          type: integer
                        step:
                          type: integer
                          description: 幅と高さはこの値の倍数である必要があります。
                        accessStatus:
                          type: string
                          enum:
                            - available
                            - membership_required
                        presets:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              width:
                                type: integer
                              height:
                                type: integer
                              ratioLabel:
                                type: string
                                description: "例: `9:16`。"
                              accessStatus:
                                type: string
                                enum:
                                  - available
                                  - membership_required
        "404":
          $ref: "#/components/responses/ModelNotFound"
      security:
        - {}
        - bearerAuth: []
  /color-palettes/presets:
    get:
      tags:
        - model
      summary: カラーパレットプリセット一覧の取得
      description: |
        `POST /v2/image/create` の `colorPalette` に使う PixAI 公式カラーパレットを一覧表示します。使用するには、プリセットオブジェクト全体に `"source": "preset"` を追加して送信します。

        `name` はローカライズされています。`?lang=ja`（または `ko`、`en`）か `Accept-Language` ヘッダーを指定してください。
      operationId: listColorPalettePresets
      responses:
        "200":
          description: プリセット一覧。
          content:
            application/json:
              schema:
                type: object
                properties:
                  palettes:
                    type: array
                    items:
                      allOf:
                        - $ref: "#/components/schemas/ColorPalette"
                        - type: object
                          properties:
                            coverUrl:
                              type:
                                - string
                                - "null"
                              description: プレビュー画像です。
      security:
        - {}
        - bearerAuth: []

components:
  schemas:
    CreateImageRequest:
      type: object
      required:
        - modelVersionId
        - prompt
      additionalProperties: false
      properties:
        modelVersionId:
          type: string
          minLength: 1
          description: |
            生成に使用するモデルバージョンの一意の識別子です。非推奨の `modelId` フィールドの代替として推奨されます。

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

            URL 例: `https://pixai.art/model/<id>-<slug>/<modelVersionId>` → modelVersionId は `<modelVersionId>` です。

            <img src="/images/find-modelid.png" alt="modelVersionId の見つけ方" />
          example: "1983308862240288769"
        modelId:
          type: string
          minLength: 1
          x-fold: true
          x-badge:
            - type: deprecated
              info: |
                代わりに `modelVersionId` を使用してください。`modelId` は名前が紛らわしく、実際にはモデルIDではなくモデル**バージョン**IDを受け取ります。
          description: |
            生成に使用するモデルバージョンの一意の識別子です。PixAI のモデルバージョンの URL から取得します。

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

            URL 例: `https://pixai.art/model/<id>-<slug>/<modelVersionId>` → modelId は `<modelVersionId>` です。

            <img src="/images/find-modelid.png" alt="modelId の見つけ方" />
          example: "1983308862240288769"
        prompt:
          type: string
          minLength: 1
          maxLength: 10000
          description: |
            生成したいコンテンツを説明するメインプロンプトです。Tsubaki.2 と Tsubaki.3 では最大 10,000 文字、その他のモデルでは最大 4,096 文字です。
          example: "1girl, green hair, solo, standing"
        negativePrompt:
          type: string
          maxLength: 4096
          description: |
            生成画像に含めたくない要素を説明するテキストです。
          example: "nsfw, lowres, bad anatomy"
        aspectRatio:
          type: string
          enum:
            - "1:1"
            - "2:3"
            - "3:2"
            - "3:4"
            - "4:3"
            - "3:5"
            - "5:3"
            - "9:16"
            - "16:9"
            - "1:3"
            - "3:1"
          description: |
            生成画像のアスペクト比。`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）で利用可能です。

            サイズティアごとの完全な解像度マッピングは[対応解像度](/ja/docs/references/supported-resolutions)を参照してください。
          example: "1:1"
        size:
          type: string
          enum:
            - "1k"
            - "1.5k"
          description: |
            出力解像度のティア。`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）。

            完全なマッピングテーブルは[対応解像度](/ja/docs/references/supported-resolutions)を参照してください。
          example: "1k"
        width:
          type: integer
          minimum: 1
          maximum: 10240
          description: |
            正確な出力幅（ピクセル）です。`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` になります。
          example: 1024
        height:
          type: integer
          minimum: 1
          maximum: 10240
          description: |
            正確な出力の高さ（ピクセル）です。`width` と一緒に指定します。指定できるサイズは `width` を参照してください。
          example: 1024
        mode:
          type: string
          x-badge:
            - type: tsubaki2
              info: |
                **Tsubaki.2** および **Tsubaki.3** モデルファミリーのみ有効です。他のモデルタイプでは `400 INVALID_ARGUMENT` で拒否されます。
          enum:
            - lite
            - standard
            - pro
            - ultra
          description: |
            生成品質と速度を制御する推論プロファイルです。
            - `lite`: 最速、基本品質。
            - `standard`: 速度と品質のバランス。
            - `pro`: 高品質、低速。
            - `ultra`: 最高品質、最低速。

            すべてのモデル・プランですべてのモードが使えるわけではありません。使えないモードを指定すると、そのモード名を含む `422 INVALID_INPUT` が返ります。
          example: standard
        style:
          x-badge:
            - type: tsubaki2
              info: |
                **Tsubaki.2** および **Tsubaki.3** モデルファミリーのみ有効です。他のモデルタイプでは無視されます。
          description: |
            生成中に適用するスタイルです。名前付きプリセットまたはカスタムスタイル文字列を指定できます。
          oneOf:
            - type: object
              additionalProperties: false
              required:
                - type
                - key
              properties:
                type:
                  type: string
                  enum:
                    - preset
                key:
                  type: string
                  enum:
                    - 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
                  description: |
                    プリセットスタイルキー。利用可能なプリセット:
                    - `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` — ヴィンテージコラージュ
            - type: object
              additionalProperties: false
              required:
                - type
                - custom
              properties:
                type:
                  type: string
                  enum:
                    - custom
                custom:
                  type: string
                  description: |
                    生成プロンプトの前置詞として直接注入される生のスタイルプロンプト文字列です。上級オプションです。誤った値を指定すると出力品質が低下する可能性があります。
          discriminator:
            propertyName: type
        loras:
          type: array
          maxItems: 15
          description: |
            出力スタイルやコンテンツを微調整するための 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:
            $ref: "#/components/schemas/LoraItem"
        contextImages:
          type: array
          maxItems: 3
          x-badge:
            - type: tsubaki3
              info: |
                **Tsubaki.3**（`modelVersionId` `2024383379556065549`）のみ有効です。その他のモデルでは `400 BAD_REQUEST`（"This feature is not yet supported for this model"）が返ります。
          description: |
            インコンテキスト生成用の参照画像です。キャラクターの一貫性を保つ、別の画像のポーズを使う、といった用途に使います。

            各要素はメディア ID です。完了したタスクの `outputs.mediaIds` の ID、または[画像・動画のアップロード](/ja/docs/api-v2/media/getImageUploadUrl)で返される ID を指定します。各画像は縦横とも 4000 px 未満である必要があります。
          items:
            type: string
            description: "メディア ID。"
          example: [ "1943547603237249965" ]
        seed:
          type: integer
          description: |
            再現性のある生成のためのランダムシードです。省略するとランダムに生成されます。
          example: 42
        batchSize:
          type: integer
          enum:
            - 1
            - 4
          default: 1
          description: |
            1つのタスクで生成する画像の枚数です。指定できる値は `1` または `4` で、デフォルトは `1` です。
          example: 4
        sampling:
          type: object
          x-badge:
            - type: sdxl-sdv1
              info: |
                **SDXL** および **SD v1** モデルファミリーのみ使用可能です。
          description: |
            拡散プロセスを微調整するための高度なサンプリングパラメータです。すべてのフィールドは省略可能で、省略した場合はモデルのデフォルト値が使用されます。

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

            タスクのステータスが変化した際に、この URL に POST リクエストが送信されます。
          example: "https://your-server.example.com/webhook"
        colorPalette:
          x-badge:
            - type: tsubaki3
              info: |
                **Tsubaki.3**（`modelVersionId` `2024383379556065549`）のみ有効です。その他のモデルでは `400 BAD_REQUEST`（"This feature is not yet supported for this model"）が返ります。
          description: |
            画像の配色を指定します。`GET /v2/color-palettes/presets` のプリセットを 1 件そのまま送り、`"source": "preset"` を追加してください。
          allOf:
            - $ref: "#/components/schemas/ColorPalette"
            - type: object
              required:
                - source
              properties:
                source:
                  type: string
                  enum:
                    - preset
                    - user
    LoraItem:
      type: object
      required:
        - modelId
      additionalProperties: false
      properties:
        modelId:
          type: string
          description: PixAI モデルマーケットの LoRA モデルバージョン ID です。
          example: "1744880666293972790"
        weight:
          type: number
          minimum: 0
          maximum: 1
          default: 1
          description: LoRA アダプターの影響度（重み）です。範囲は 0.0〜1.0 です。
          example: 0.7
        triggerWords:
          type: string
          description: |
            この LoRA のカスタムトリガーワードです。省略した場合は LoRA のデフォルトのトリガーワードが自動的に追加され、空文字列を指定すると何も追加されません。
    Error:
      type: object
      required:
        - code
        - status
        - message
      properties:
        code:
          type: string
          description: "機械可読なエラーコードです（`BAD_REQUEST`、`INSUFFICIENT_BALANCE` など）。`message` ではなくこの値で分岐してください。"
        status:
          type: integer
          description: "HTTP ステータスコード。"
        message:
          type: string
          description: "人が読むための詳細です。多くの場合、問題のフィールドや値が示されます。"
        data:
          type: object
          description: "コードごとの詳細です（検証エラーの `issues`、`IMAGE_SIZE_NOT_ALLOWED` の `reason` など）。"
        defined:
          type: boolean
          description: "`code` がこのエンドポイントで定義されたコードかどうか。"
    Task:
      type: object
      required:
        - id
        - status
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
          description: "タスクの一意の識別子。"
        status:
          type: string
          description: "タスクの現在のステータス。"
          enum:
            - waiting
            - running
            - completed
            - cancelled
            - failed
        createdAt:
          type: string
          description: "タスクの作成時刻。"
          format: date-time
        updatedAt:
          type: string
          description: "タスクの最終更新時刻。"
          format: date-time
        startedAt:
          type: string
          description: "タスクの開始時刻。"
          format: date-time
        endAt:
          type: string
          description: "タスクの終了時刻。"
          format: date-time
        taskKind:
          type: string
          description: |
            タスクが生成するもの。画像は `t2i` または `i2i`、`POST /v2/gen-task/inpaint` は `inpaint`、`POST /v2/frame-video/create` は `i2v-inhouse`、`POST /v2/reference-video/create` は `reference-video` です。
        paidQuota:
          type: integer
          description: タスクに課金されたクレジット。
        taskStatusMsgI18n:
          type: object
          description: "`failed` になったタスクの失敗理由。"
          properties:
            key:
              type: string
              description: 変わらないメッセージキー。
            defaultMessage:
              type: string
              description: 英語のメッセージ。
        outputs:
          type: object
          description: "タスクで生成された出力。"
          properties:
            videoMediaId:
              type: string
              description: |
                動画タスクの場合、動画のメディア ID です。`GET /v2/media/batch?ids=<videoMediaId>` で解決し、`fileUrl` をダウンロードしてください。このとき `mediaIds` にはポスター画像だけが入ります。
            seed:
              type: string
              description: 使われたシード値（10 進数の文字列）。
            mediaIds:
              type: array
              description: |
                生成された画像のメディア ID です。これらの ID を使用して各生成画像の詳細情報を取得できます。

                生成された画像は通常、恒久的には保持されません。できるだけ早く取得してください。
              items:
                type: string
                description: 生成されたメディアアイテムの一意の識別子。
            mediaUrls:
              type: array
              description: |
                生成された画像の公開 URL です。

                生成された画像は通常、恒久的には保持されません。できるだけ早く取得してください。画像が利用できない場合、その項目は `null` になることがあります。
              items:
                type:
                  - string
                  - "null"
                description: メディアアイテムの URL、または利用不可の場合は null。
    UploadUrlRequest:
      type: object
      properties:
        isEphemeral:
          type: boolean
          default: false
          description: ファイルを短期間だけ使う生成入力としてマークします。エフェメラルファイルは非公開で、その URL は署名付きで有効期限があります。
    UploadUrl:
      type: object
      required:
        - uploadUrl
        - externalId
      properties:
        uploadUrl:
          type: string
          description: 署名付き URL です。ファイルの `Content-Type` を付けて、生のファイルバイトを `PUT` してください。
        externalId:
          type: string
          description: アップロード後、対応する `register` エンドポイントにこの値を渡してください。
    Media:
      type: object
      required:
        - id
        - type
      properties:
        id:
          type: string
          description: メディア ID です。
        type:
          type: string
          enum:
            - IMAGE
            - VIDEO
            - AUDIO
        urls:
          type: array
          description: バリアントごとの画像 URL です。`PUBLIC` がフルサイズの画像です。
          items:
            type: object
            properties:
              variant:
                type: string
                enum:
                  - PUBLIC
                  - THUMBNAIL
                  - STILL_THUMBNAIL
              url:
                type: string
        width:
          type:
            - number
            - "null"
        height:
          type:
            - number
            - "null"
        fileUrl:
          type:
            - string
            - "null"
          description: ファイル自体の URL です（動画の MP4 など）。
        hlsUrl:
          type:
            - string
            - "null"
          description: 動画の HLS ストリームです。生成された動画では `null` のことが多いため、`fileUrl` を使ってください。
        thumbnailUrl:
          type:
            - string
            - "null"
          description: 動画のポスター画像です。生成された動画では `null` のことが多く、ポスターはタスクの `outputs.mediaIds` にあります。
        duration:
          type:
            - number
            - "null"
          description: 動画または音声ファイルの長さ（秒）です。生成された動画では `0` のことがあります。
    ModelVersion:
      type: object
      required:
        - id
        - modelId
      properties:
        id:
          type: string
          description: バージョン ID です。`modelVersionId` として、LoRA の場合は `loras[].modelId` として渡します。
        modelId:
          type: string
          description: このバージョンが属するモデルの ID です。
        modelTitle:
          type: string
        name:
          type: string
          description: バージョン名です。
        modelType:
          type:
            - string
            - "null"
          description: "例: `SDXL_MODEL`、`MMDIT26B_MODEL`、`SDXL_LORA`。"
        loraBaseModelType:
          type:
            - string
            - "null"
          description: LoRA の場合、学習対象のベースモデルタイプです。このタイプのベースモデルと組み合わせてください。
        loraBaseModelId:
          type:
            - string
            - "null"
          description: LoRA の場合、学習に使われたベースモデルです。
        status:
          type:
            - string
            - "null"
          description: 生成に使えるのは `available` のバージョンのみです。
        extra:
          type: object
          description: バージョンの詳細です。`triggerWords` には LoRA のデフォルトのトリガーワードが入ります。
          properties:
            triggerWords:
              type: string
        mediaId:
          type:
            - string
            - "null"
          description: カバー画像のメディア ID です。
    ModelListItem:
      type: object
      required:
        - id
        - title
        - type
      properties:
        id:
          type: string
          description: モデル ID です。生成エンドポイントはバージョン ID を受け取るため、代わりに `latestAvailableVersionId` を使用してください。
        title:
          type: string
        type:
          type: string
          description: "例: `SDXL_MODEL`、`MMDIT26B_MODEL`、`SDXL_LORA`。"
        category:
          type:
            - string
            - "null"
        loraBaseModelTypes:
          type: array
          items:
            type: string
          description: LoRA の場合、対応するベースモデルタイプです。
        permittedUse:
          type: string
          enum:
            - PERSONAL
            - COMMERCIAL
          description: ライセンスで許可されている用途です。
        mediaId:
          type:
            - string
            - "null"
          description: カバー画像のメディア ID です。
        latestAvailableVersionId:
          type:
            - string
            - "null"
          description: 使用可能な最新バージョンです。`modelVersionId` として、LoRA の場合は `loras[].modelId` として渡します。
        latestAvailableVersion:
          type:
            - object
            - "null"
          description: 使用可能な最新バージョンです。
          properties:
            id:
              type: string
              description: "`latestAvailableVersionId` と同じです。"
            name:
              type: string
            modelType:
              type:
                - string
                - "null"
            loraBaseModelType:
              type:
                - string
                - "null"
              description: LoRA の場合、学習対象のベースモデルタイプです。
            extra:
              type: object
              description: "`triggerWords` には LoRA のデフォルトのトリガーワードが入ります。"
              properties:
                triggerWords:
                  type: string
    ColorPalette:
      type: object
      required:
        - id
        - name
        - palette
        - createdAt
        - updatedAt
      properties:
        id:
          type: string
        name:
          type: string
        palette:
          type: object
          description: 画像全体の色と、必要に応じて背景とキャラクターの色です。`overall` または `background` が必須です。
          properties:
            overall:
              $ref: "#/components/schemas/PaletteColors"
            background:
              $ref: "#/components/schemas/PaletteColors"
            character:
              $ref: "#/components/schemas/PaletteColors"
        createdAt:
          type: string
          format: date-time
        updatedAt:
          type: string
          format: date-time
    PaletteColors:
      type: object
      required:
        - colors
      properties:
        colors:
          type: array
          minItems: 1
          maxItems: 12
          items:
            type: object
            required:
              - hex
              - ratio
            properties:
              hex:
                type: string
                description: "`#RRGGBB` 形式です。"
              ratio:
                type: number
                minimum: 0
                maximum: 100
                description: 画像に占める割合（パーセント）です。
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API-Key
      description: |
        認証が必要なすべてのリクエストでは、HTTP ヘッダーに次を追加してください
  headers:
    X-Trace-Id:
      description: "リクエストの一意の識別子。デバッグやリクエストのトレースに役立ちます。"
      schema:
        type: string
  responses:
    Unauthorized:
      description: '`UNAUTHORIZED`: API キーが送られていません。無効、失効済み、期限切れのキーの場合は、数値の `code` を持つ `{"message": "invalid token", "code": 40100001}` が返ります。'
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    CannotRun:
      description: |
        現在このアカウントではこのタスクを実行できません。理由は `code` で示されます:

        - `INSUFFICIENT_BALANCE`: タスクに必要なクレジットが不足しています。
        - `WAITING_NUM_EXCEEDED`: `waiting` 状態のタスクが多すぎます（`data.currentWaitingTasks`）。いくつか実行が始まるまで待ってから送信してください。
        - `REQUIRE_MEMBERSHIP`: この機能には PixAI メンバーシップが必要です（画像から動画への生成）。
        - `NSFW_PROMPTS_DETECTED`: アカウントがセーフモードのため、プロンプトが拒否されました。
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    CreationFailed:
      description: "`CREATION_FAILED`: タスクを作成できませんでした。指数バックオフで再試行してください。"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    ModelNotFound:
      description: "`NOT_FOUND`: モデルまたはバージョンが存在しないか、非公開です。この 2 つのケースは区別されません。"
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
