openapi: 3.1.0
info:
  title: PixAI API - OpenAPI 2.0
  description: |
    API를 통해 생성된 이미지의 저작권은 사용자에게 귀속되며, PixAI는 사용자 생성 작품에 대해 어떠한 저작권도 주장하지 않습니다. 단, 사용자는 생성된 콘텐츠가 제3자의 권리를 침해하지 않으며, 적용 가능한 관련 법령을 준수해야 합니다.

    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` 상태의 작업이 너무 많습니다. 일부가 시작될 때까지 기다린 후 제출하세요([제한](/ko/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.

        모든 모델에는 이미지나 동영상이 하나 이상 필요합니다. 단, `v4.0.3`은 오디오만으로도 생성할 수 있습니다.

        참조 파일은 다음 제한을 충족해야 합니다:

        - 동영상: MP4 또는 MOV, H.264 또는 HEVC, 24–60 fps, 클립당 2–15초, 합계 15초(`v4.0.3`은 30초), 최대 50 MB(`v4.0.3`은 200 MB).
        - 오디오: WAV 또는 MP3, 클립당 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가 붙기도 합니다. `<reason>`은 `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`가 낮을수록 원본에 가깝게 유지됩니다.

        마스크 편집에는 항상 함께 보내야 하는 이미지 두 개가 추가로 필요합니다:

        - `maskMediaId`: 베이스 이미지와 같은 크기로, 다시 그릴 곳은 흰색, 유지할 곳은 검은색입니다.
        - `maskedImageMediaId`: 베이스 이미지에서 마스크의 흰색 영역을 회색(`#808080`)으로 칠한 이미지입니다.

        마스크를 보내면 출력은 마스크 적용 이미지의 크기가 되고, 보내지 않으면 베이스 이미지의 크기가 됩니다. 이미지는 미디어 ID로 지정합니다. `POST /v2/media/image/upload-url`을 참고하세요.

        `modelPreset: "v1"`을 사용하세요. 프리셋의 크기 제한과 `sdeditPreset` 이름은 `GET /v2/gen-task/inpaint/constraints`에서 확인할 수 있습니다. 크레딧은 작업 생성 시 차감되며, 결과는 `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`의 다시 그리기 프리셋 이름입니다. 다시 그리기 프리셋이 없는 `modelPreset`에 보내면 `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. 원시 이미지 바이트를 HTTP `PUT`으로 `uploadUrl`에 보내고, 파일의 실제 `Content-Type`(예: `image/png`)을 지정합니다. 멀티파트 폼은 사용하지 마세요.
        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: 파일을 단기 생성 입력용으로 표시합니다. 임시(ephemeral) 파일은 비공개이며, 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만 지원하며 클립당 15 MiB 미만이어야 합니다. 길이 제한은 동영상 모델에 따라 다르며, 업로드 시가 아니라 동영상 작업 생성 시 검사됩니다.
      operationId: getAudioUploadUrl
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                isEphemeral:
                  type: boolean
                  default: false
                  description: 파일을 단기 생성 입력용으로 표시합니다. 임시(ephemeral) 파일은 비공개이며, 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: 동영상 스트림마다 하나의 항목입니다.
                    items:
                      type: object
                      properties:
                        codec:
                          type: string
                        width:
                          type: integer
                        height:
                          type: integer
                        averageFrameRate:
                          type: number
                  audioStreams:
                    type: array
                    description: 오디오 스트림마다 하나의 항목입니다.
                    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: |
        완료된 작업의 `outputs.mediaIds`나 `outputs.videoMediaId` 등 최대 100개의 미디어 ID를 URL로 변환합니다. 공개 미디어는 인증이 필요하지 않습니다.

        존재하지 않는 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`와 함께 베이스 모델의 유형(모델 항목의 `type`, 예: `SDXL_MODEL`)을 `loraBaseModelTypes`에 보내세요.

        결과는 요청자에 따라 다릅니다. 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: 결과 한 페이지.
          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`)로 모델 하나를 조회합니다."
      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로 모델 버전 하나를 조회합니다. 생성 전에 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)에서 사용 가능합니다.

            크기 등급별 전체 해상도 매핑은 [지원 해상도](/ko/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).

            전체 매핑 테이블은 [지원 해상도](/ko/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나 [이미지 또는 동영상 업로드](/ko/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` 또는 `4`만 지원하며 기본값은 `1`입니다.
          example: 4
        sampling:
          type: object
          x-badge:
            - type: sdxl-sdv1
              info: |
                **SDXL** 및 **SD v1** 모델 패밀리에서만 사용 가능합니다.
          description: |
            확산 프로세스를 미세 조정하기 위한 고급 샘플링 파라미터입니다. 모든 필드는 선택 사항이며, 생략 시 모델의 기본값이 사용됩니다.

            모델별 지원 샘플링 메서드는 [모델 목록](/ko/docs/references/models) 페이지를 참조하세요.
          additionalProperties: false
          properties:
            method:
              type: string
              description: |
                생성 시 사용되는 샘플러 알고리즘입니다. 지원되는 메서드는 모델에 따라 다릅니다 — [모델 목록](/ko/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: |
            작업 상태 변경 시 POST 요청을 받을 공개 URL(웹훅)입니다.

            작업 상태가 변경될 때 이 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`의 프리셋 하나를 그대로 보내고 `"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: 파일을 단기 생성 입력용으로 표시합니다. 임시(ephemeral) 파일은 비공개이며, URL은 서명되어 있고 만료됩니다.
    UploadUrl:
      type: object
      required:
        - uploadUrl
        - externalId
      properties:
        uploadUrl:
          type: string
          description: 사전 서명된 URL입니다. 원시 파일 바이트를 파일의 `Content-Type`과 함께 이 URL에 `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`: 해당 모델이나 버전이 없거나 비공개입니다. 두 경우는 구분되지 않습니다."
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
