---
title: "이미지 생성 작업 생성"
description: "간소화된 v2 API로 비동기 이미지 생성 작업을 시작합니다. 응답에는 생성된 작업의 ID가 포함됩니다."
canonical: "https://platform.pixai.art/ko/docs/api-v2/image/createImage"
last-updated: "2026-11-16"
---

# 이미지 생성 작업 생성

간소화된 v2 API로 비동기 이미지 생성 작업을 시작합니다. 응답에는 생성된 작업의 ID가 포함됩니다.



v2 API는 `aspectRatio`(종횡비), `mode`(품질 모드), 명명된 `style` 프리셋 등 사용자 친화적인 파라미터를 제공하며, v1의 원시 픽셀 치수 및 내부 파라미터명을 대체합니다.

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

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

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

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

- `modelVersionId` (string, required)
  생성에 사용할 모델 버전의 고유 식별자입니다. 더 이상 사용되지 않는 `modelId` 필드의 권장 대체 필드입니다.

  modelVersionId를 찾는 방법:
  1. PixAI 모델 페이지를 엽니다.
  2. 사용하려는 모델 버전을 클릭합니다.
  3. URL의 마지막 경로 세그먼트를 복사합니다 — 이것이 modelVersionId입니다.

  예시 URL: `https://pixai.art/model/<id>-<slug>/<modelVersionId>` → modelVersionId는 `<modelVersionId>`.
  Example: `"1983308862240288769"`.
- `modelId` (string, optional, deprecated)
  생성에 사용할 모델 버전의 고유 식별자입니다. PixAI의 모델 버전 URL에서 확인할 수 있습니다.

  modelId를 찾는 방법:
  1. PixAI 모델 페이지를 엽니다.
  2. 사용하려는 모델 버전을 클릭합니다.
  3. URL의 마지막 경로 세그먼트를 복사합니다 — 이것이 modelId입니다.

  예시 URL: `https://pixai.art/model/<id>-<slug>/<modelVersionId>` → modelId는 `<modelVersionId>`.
  Note: 대신 `modelVersionId`를 사용하세요. `modelId`는 이름이 모호하며, 실제로는 모델 ID가 아닌 모델 **버전** ID를 받습니다.
  Example: `"1983308862240288769"`.
- `prompt` (string, required)
  생성하고 싶은 콘텐츠를 설명하는 메인 프롬프트입니다. Tsubaki.2와 Tsubaki.3에서는 최대 10,000자, 그 외 모델에서는 최대 4,096자입니다.
  Length: 1 to 10000 characters.
  Example: `"1girl, green hair, solo, standing"`.
- `negativePrompt` (string, optional)
  생성 이미지에 포함되지 않기를 원하는 요소를 설명하는 텍스트입니다.
  Length: 0 to 4096 characters.
  Example: `"nsfw, lowres, bad anatomy"`.
- `aspectRatio` (string, optional)
  생성 이미지의 종횡비입니다. `aspectRatio`/`size`와 `width`/`height`를 모두 보내지 않으면 기본값은 `1:1`입니다. `width`·`height`와 함께 사용할 수 없습니다.

  사용 가능한 비율: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `3:5`, `5:3`, `9:16`, `16:9`, `1:3`, `3:1`

  모든 비율은 모든 모델 유형(SDXL, DiT, Tsubaki.2)에서 사용 가능합니다.

  크기 등급별 전체 해상도 매핑은 [지원 해상도](https://platform.pixai.art/ko/docs/references/supported-resolutions)를 참조하세요.
  Allowed values: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `3:5`, `5:3`, `9:16`, `16:9`, `1:3`, `3:1`.
  Example: `"1:1"`.
- `size` (string, optional)
  출력 해상도 등급입니다. `aspectRatio`/`size`와 `width`/`height`를 모두 보내지 않으면 기본값은 `1k`입니다. `width`·`height`와 함께 사용할 수 없습니다. `1.5k`의 최장변은 1536 px입니다.
  - `1k`: 약 1메가픽셀 (예: 1:1에서 1024×1024).
  - `1.5k`: 약 2.36메가픽셀 (예: 1:1에서 1536×1536).

  전체 매핑 테이블은 [지원 해상도](https://platform.pixai.art/ko/docs/references/supported-resolutions)를 참조하세요.
  Allowed values: `1k`, `1.5k`.
  Example: `"1k"`.
- `width` (integer, optional)
  정확한 출력 너비(픽셀)입니다. `aspectRatio`/`size` 프리셋에 없는 크기(Tsubaki.3의 큰 출력 등)에 사용합니다. `height`와 함께 보내고 `aspectRatio`와 `size`는 보내지 마세요.

  크기는 모델의 크기 범위 중 하나에 들어가고 그 `step`의 배수여야 합니다. 범위는 `GET https://api.pixai.art/v2/generation-model/{modelVersionId}/size-config`(인증 불필요)로 확인할 수 있습니다. `ranges`의 각 항목에 `minWidth`/`maxWidth`, `minHeight`/`maxHeight`, `step`과 미리 정의된 `presets`가 있습니다. 어느 범위에도 맞지 않으면 `400 IMAGE_SIZE_NOT_ALLOWED`가 반환됩니다.
  Range: 1 to 10240.
  Example: `1024`.
- `height` (integer, optional)
  정확한 출력 높이(픽셀)입니다. `width`와 함께 보냅니다. 허용 크기는 `width`를 참고하세요.
  Range: 1 to 10240.
  Example: `1024`.
- `mode` (string, optional)
  생성 품질과 속도를 제어하는 추론 프로파일입니다.
  - `lite`: 가장 빠름, 기본 품질.
  - `standard`: 속도와 품질의 균형.
  - `pro`: 높은 품질, 느림.
  - `ultra`: 최고 품질, 가장 느림.

  모든 모델과 플랜에서 모든 모드를 사용할 수 있는 것은 아닙니다. 사용할 수 없는 모드를 지정하면 해당 모드 이름이 포함된 `422 INVALID_INPUT`이 반환됩니다.
  Note: **Tsubaki.2** 및 **Tsubaki.3** 모델 패밀리에서만 사용 가능합니다. 다른 모델 유형에서는 `400 INVALID_ARGUMENT`로 거부됩니다.
  Allowed values: `lite`, `standard`, `pro`, `ultra`.
  Example: `"standard"`.
- `style` (object (one of the variants below), optional)
  생성 중 적용할 스타일입니다. 명명된 프리셋이나 커스텀 스타일 문자열을 지정할 수 있습니다.
  Note: **Tsubaki.2** 및 **Tsubaki.3** 모델 패밀리에서만 사용 가능합니다. 다른 모델 유형에서는 무시됩니다.
  - Variant 1:
    - `style.type` (string, required)
      Allowed values: `preset`.
    - `style.key` (string, required)
      명명된 프리셋 스타일 키입니다. 사용 가능한 프리셋:
      - `anime-watercolor-impasto` — 수채화 글로우
      - `art-crayon` — 아트 크레용
      - `bold-line-soft-color` — 빛과 그림자의 교차
      - `chibi` — 치비
      - `classic-japanese` — 클래식 애니
      - `clean-flat-illustration` — 클린 플랫 일러스트
      - `colored-pencil-grain` — 컬러풀 색연필
      - `cool-warm-oil-contrast` — 사계절 글로우
      - `desaturated-cool` — 쿨톤 소프트라이트
      - `flat-anime-pastel` — 파스텔 플랫
      - `glossy-glass-anime` — 글래시 애니
      - `grey-blocks-lineless` — 그레이 워시
      - `hard-line-monochrome-accent` — 샤프 잉크 스타일
      - `high-contrast-retro-vivid` — 네온 비비드
      - `holographic` — 하이퍼 팝
      - `korean-style` — 폴리시드 만화
      - `lineart-watercolor-airy` — 윤기 있는 렌더링
      - `low-saturation-expressive-eyes` — 투명한 담채
      - `lucid-dreamy` — 투명한 몽환
      - `luminous-retro-impasto` — 루미너스 임파스토
      - `minimal-flat-color` — 미니멀 플랫
      - `modern-oil-glamour` — 모던 러스터
      - `moe-pastel` — 모에 파스텔
      - `oil-watercolor-blend` — 워터리 오일페인팅
      - `painterly-doodle` — 부드러운 터치
      - `paper-watercolor` — 수채화 소프트 포커스
      - `pencil-sketch` — 연필 스케치
      - `poster-graffiti` — 네온 포스터
      - `retro-comic-fusion` — 레트로 퓨전
      - `retro-oil-glamour` — 레트로 글로시
      - `retro-tv-anime` — 90년대 레트로 셀
      - `semi-realistic` — 세미 리얼
      - `stable-vaporwave` — 네온 베이퍼웨이브
      - `tinted-sketch` — 담채 스케치
      - `vintage-collage` — 빈티지 콜라주
      Allowed values: `anime-watercolor-impasto`, `art-crayon`, `bold-line-soft-color`, `chibi`, `classic-japanese`, `clean-flat-illustration`, `colored-pencil-grain`, `cool-warm-oil-contrast`, `desaturated-cool`, `flat-anime-pastel`, `glossy-glass-anime`, `grey-blocks-lineless`, `hard-line-monochrome-accent`, `high-contrast-retro-vivid`, `holographic`, `korean-style`, `lineart-watercolor-airy`, `low-saturation-expressive-eyes`, `lucid-dreamy`, `luminous-retro-impasto`, `minimal-flat-color`, `modern-oil-glamour`, `moe-pastel`, `oil-watercolor-blend`, `painterly-doodle`, `paper-watercolor`, `pencil-sketch`, `poster-graffiti`, `retro-comic-fusion`, `retro-oil-glamour`, `retro-tv-anime`, `semi-realistic`, `stable-vaporwave`, `tinted-sketch`, `vintage-collage`.
  - Variant 2:
    - `style.type` (string, required)
      Allowed values: `custom`.
    - `style.custom` (string, required)
      생성 프롬프트 앞에 직접 삽입되는 원시 스타일 프롬프트 문자열입니다. 고급 옵션으로, 잘못된 값을 입력하면 출력 품질이 저하될 수 있습니다.
- `loras` (object[], optional)
  출력 스타일이나 콘텐츠를 미세 조정하기 위한 LoRA 어댑터입니다. 조합할 수 있는 개수는 플랜에 따라 다르며(멤버십 없이 3개, 최대 15개), 초과하면 `403 LORA_NUM_EXCEEDED`가 반환됩니다.

  생성 모델과 같은 베이스 모델용 LoRA를 사용하세요. LoRA의 베이스 모델은 PixAI의 LoRA 페이지에 표시됩니다.

  LoRA modelId를 찾는 방법:
  1. PixAI LoRA 모델 페이지를 엽니다.
  2. 사용하려는 LoRA 버전을 클릭합니다.
  3. URL의 마지막 경로 세그먼트를 복사합니다 — 이것이 LoRA 버전 ID입니다.

  예시 URL: `https://pixai.art/model/<loraModelId>/<loraVersionId>` → LoRA 버전 ID는 `<loraVersionId>`.
  Items: 0 to 15.
- `loras[].modelId` (string, required)
  PixAI 모델 마켓의 LoRA 모델 버전 ID입니다.
  Example: `"1744880666293972790"`.
- `loras[].weight` (number, optional)
  LoRA 어댑터의 영향도(가중치)입니다. 범위는 0.0–1.0입니다.
  Default: `1`.
  Range: 0 to 1.
  Example: `0.7`.
- `loras[].triggerWords` (string, optional)
  이 LoRA의 커스텀 트리거 워드입니다. 생략하면 LoRA의 기본 트리거 워드가 자동으로 추가되고, 빈 문자열을 보내면 아무것도 추가되지 않습니다.
- `contextImages` (string[], optional)
  인컨텍스트 생성을 위한 참조 이미지입니다. 캐릭터를 일관되게 유지하거나 다른 이미지의 포즈를 가져오는 데 사용합니다.

  각 항목은 미디어 ID입니다. 완료된 작업의 `outputs.mediaIds`에 있는 ID나 [이미지 또는 동영상 업로드](https://platform.pixai.art/ko/docs/api-v2/media/getImageUploadUrl)가 반환한 ID를 사용하세요. 각 이미지는 가로세로 모두 4000 px 미만이어야 합니다.
  Note: **Tsubaki.3**(`modelVersionId` `2024383379556065549`)에서만 사용할 수 있습니다. 그 외 모델에서는 `400 BAD_REQUEST`("This feature is not yet supported for this model")가 반환됩니다.
  Items: 0 to 3.
  Example: `["1943547603237249965"]`.
- `seed` (integer, optional)
  재현 가능한 생성을 위한 랜덤 시드입니다. 생략하면 무작위로 생성됩니다.
  Example: `42`.
- `batchSize` (integer, optional)
  한 작업에서 생성할 이미지 수입니다. `1` 또는 `4`만 지원하며 기본값은 `1`입니다.
  Allowed values: `1`, `4`.
  Default: `1`.
  Example: `4`.
- `sampling` (object, optional)
  확산 프로세스를 미세 조정하기 위한 고급 샘플링 파라미터입니다. 모든 필드는 선택 사항이며, 생략 시 모델의 기본값이 사용됩니다.

  모델별 지원 샘플링 메서드는 [모델 목록](https://platform.pixai.art/ko/docs/references/models) 페이지를 참조하세요.
  Note: **SDXL** 및 **SD v1** 모델 패밀리에서만 사용 가능합니다.
- `sampling.method` (string, optional)
  생성 시 사용되는 샘플러 알고리즘입니다. 지원되는 메서드는 모델에 따라 다릅니다 — [모델 목록](https://platform.pixai.art/ko/docs/references/models) 페이지를 참조하세요.
  Example: `"DPM++ 2M Karras"`.
- `sampling.steps` (integer, optional)
  확산 스텝 수입니다. 높은 값은 디테일을 향상시키지만 생성 시간과 비용이 증가합니다.
  Range: 1 to 100.
  Example: `25`.
- `sampling.cfgScale` (number, optional)
  Classifier-Free Guidance (CFG) 스케일. 프롬프트 준수도와 창의적 자유도 간의 균형을 제어합니다. 높은 값일수록 프롬프트를 더 엄격하게 따릅니다.
  Example: `7`.
- `promptHelper` (string, optional)
  생성 전 프롬프트를 자동으로 강화하는 내장 프롬프트 도우미 사용 여부입니다.
  - `enable`: 프롬프트를 자동으로 강화합니다(기본값).
  - `disable`: 프롬프트를 그대로 사용합니다.
  - `low` / `medium`: Tsubaki.2와 Tsubaki.3에서 도우미가 프롬프트를 다시 쓰는 정도를 지정합니다. 그 외 모델에서는 둘 다 `enable`과 같이 동작합니다.
  Note: 이 항목을 활성화하면 추가 요금이 부과됩니다.
  Allowed values: `enable`, `disable`, `low`, `medium`.
  Default: `"enable"`.
- `callbackUrl` (string, optional)
  작업 상태 변경 시 POST 요청을 받을 공개 URL(웹훅)입니다.

  작업 상태가 변경될 때 이 URL로 POST 요청이 전송됩니다.
  Example: `"https://your-server.example.com/webhook"`.
- `colorPalette` (object, optional)
  이미지의 색 구성을 지정합니다. `GET /v2/color-palettes/presets`의 프리셋 하나를 그대로 보내고 `"source": "preset"`을 추가하세요.
  Note: **Tsubaki.3**(`modelVersionId` `2024383379556065549`)에서만 사용할 수 있습니다. 그 외 모델에서는 `400 BAD_REQUEST`("This feature is not yet supported for this model")가 반환됩니다.
- `colorPalette.source` (string, required)
  Allowed values: `preset`, `user`.
- `colorPalette.id` (string, required)
- `colorPalette.name` (string, required)
- `colorPalette.palette` (object, required)
  이미지 전체와, 선택적으로 배경 및 캐릭터의 색상입니다. `overall` 또는 `background`가 필요합니다.
- `colorPalette.palette.overall` (object, optional)
- `colorPalette.palette.overall.colors` (object[], required)
  Items: 1 to 12.
- `colorPalette.palette.overall.colors[].hex` (string, required)
  `#RRGGBB`.
- `colorPalette.palette.overall.colors[].ratio` (number, required)
  이미지에서 차지하는 비율(퍼센트).
  Range: 0 to 100.
- `colorPalette.palette.background` (object, optional)
- `colorPalette.palette.background.colors` (object[], required)
  Items: 1 to 12.
- `colorPalette.palette.background.colors[].hex` (string, required)
  `#RRGGBB`.
- `colorPalette.palette.background.colors[].ratio` (number, required)
  이미지에서 차지하는 비율(퍼센트).
  Range: 0 to 100.
- `colorPalette.palette.character` (object, optional)
- `colorPalette.palette.character.colors` (object[], required)
  Items: 1 to 12.
- `colorPalette.palette.character.colors[].hex` (string, required)
  `#RRGGBB`.
- `colorPalette.palette.character.colors[].ratio` (number, required)
  이미지에서 차지하는 비율(퍼센트).
  Range: 0 to 100.
- `colorPalette.createdAt` (string, required)
- `colorPalette.updatedAt` (string, required)

Example:

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

### Example (cURL)

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

### Responses

- `201`
  이미지 생성 작업이 성공적으로 생성되었습니다.

  응답 예시:
  ```json
  {
    "id": "1943547603237249965",
    "status": "waiting",
    "createdAt": "2025-11-07T14:54:35.000Z",
    "updatedAt": "2025-11-07T14:54:35.000Z",
    "outputs": { "mediaIds": [], "mediaUrls": [] }
  }
  ```
  Body fields:
  - `id` (string, required)
    작업의 고유 식별자.
  - `status` (string, required)
    작업의 현재 상태.
    Allowed values: `waiting`, `running`, `completed`, `cancelled`, `failed`.
  - `createdAt` (string, required)
    작업 생성 시간.
  - `updatedAt` (string, required)
    작업 최종 업데이트 시간.
  - `startedAt` (string, optional)
    작업 시작 시간.
  - `endAt` (string, optional)
    작업 종료 시간.
  - `taskKind` (string, optional)
    작업이 만드는 것입니다. 이미지는 `t2i` 또는 `i2i`, `POST /v2/gen-task/inpaint`는 `inpaint`, `POST /v2/frame-video/create`는 `i2v-inhouse`, `POST /v2/reference-video/create`는 `reference-video`입니다.
  - `paidQuota` (integer, optional)
    작업에 청구된 크레딧.
  - `taskStatusMsgI18n` (object, optional)
    `failed`가 된 작업의 실패 이유.
  - `taskStatusMsgI18n.key` (string, optional)
    바뀌지 않는 메시지 키.
  - `taskStatusMsgI18n.defaultMessage` (string, optional)
    영어 메시지.
  - `outputs` (object, optional)
    작업에서 생성된 출력물.
  - `outputs.videoMediaId` (string, optional)
    동영상 작업의 경우 동영상의 미디어 ID입니다. `GET /v2/media/batch?ids=<videoMediaId>`로 조회한 뒤 `fileUrl`을 다운로드하세요. 이때 `mediaIds`에는 포스터 이미지만 들어 있습니다.
  - `outputs.seed` (string, optional)
    사용된 시드 값(10진수 문자열).
  - `outputs.mediaIds` (string[], optional)
    생성된 이미지의 미디어 ID입니다. 이 ID를 사용하여 각 생성 이미지의 상세 정보를 조회할 수 있습니다.

    생성된 이미지는 일반적으로 영구 보관되지 않으므로 가능한 한 빨리 다운로드해 주세요.
  - `outputs.mediaUrls` ((string | null)[], optional)
    생성된 이미지의 공개 URL입니다.

    생성된 이미지는 일반적으로 영구 보관되지 않으므로 가능한 한 빨리 다운로드해 주세요. 이미지가 사용 불가능한 경우 해당 항목이 `null`로 표시될 수 있습니다.
- `400`
  작업이 생성되기 전에 요청이 거부되었습니다. 이유는 `code`로 표시됩니다:
  - `BAD_REQUEST`(`data.issues` 포함): 본문 검증에 실패했거나(각 issue의 `path`가 해당 필드), 이 모델이 지원하지 않는 필드가 있습니다(`message`에 표시).
  - `INVALID_ARGUMENT`: 이 모델 계열에서 사용할 수 없는 필드입니다(SDXL 모델의 `mode`, Tsubaki의 `sampling` 등). 검사 대상은 `mode`와 `sampling`뿐이며, `mode`는 Tsubaki 모델, `sampling`은 SDXL과 SD v1에서만 사용할 수 있습니다. 모델이 받지 않는 필드를 제거하세요.
  - `IMAGE_SIZE_NOT_ALLOWED`: `width`/`height`가 모델의 크기 범위를 벗어났습니다(`data.reason`). `GET /v2/generation-model/{modelVersionId}/size-config`의 크기를 사용하거나 `aspectRatio`/`size`를 보내세요.
  - `INPUT_IMAGE_TOO_LARGE`: `contextImages` 중 한 변이 4000 px 이상인 이미지가 있습니다.
- `401`
  인증이 필요합니다. 유효한 Bearer 토큰을 제공해 주세요.
- `403`
  지금은 이 작업을 실행할 수 없습니다. 이유는 `code`로 표시됩니다:
  - `INSUFFICIENT_BALANCE`: 크레딧이 부족합니다.
  - `WAITING_NUM_EXCEEDED`: `waiting` 상태의 작업이 너무 많습니다. 일부가 시작될 때까지 기다린 후 제출하세요([제한](https://platform.pixai.art/ko/docs/quick-start/limits) 참고).
  - `LORA_NUM_EXCEEDED`: `loras`가 플랜 한도를 초과했습니다.
- `404`
  `NOT_FOUND`: 해당 `modelVersionId`의 모델 버전이 없습니다. `FILE_NOT_FOUND`: `contextImages`의 미디어 ID가 없습니다.
- `422`
  - `NSFW_PROMPT_REJECTED`: 콘텐츠 모더레이션에서 프롬프트가 거부되었습니다. 표현을 바꿔 주세요. 지원팀에 문의할 때는 `data.logId`를 알려 주세요.
  - `INVALID_INPUT`: 이 모델이나 플랜에서 사용할 수 없는 값입니다(모델이 제공하지 않는 `mode` 등). `message`에 해당 값이 표시됩니다.
- `500`
  내부 서버 오류로 인해 작업 생성에 실패했습니다. 지수 백오프로 재시도하세요.
