---
title: "인페인트, 아웃페인트, 다시 그리기 작업 생성"
description: "기존 이미지를 편집합니다:"
canonical: "https://platform.pixai.art/ko/docs/api-v2/image/createInpaint"
last-updated: "2026-11-02"
---

# 인페인트, 아웃페인트, 다시 그리기 작업 생성

기존 이미지를 편집합니다:



* **인페인트**(`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]`입니다.

## POST https://api.pixai.art/v2/gen-task/inpaint

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`)

- `modelPreset` (string, required)
  인페인트 모델입니다. `v1`을 사용하세요.
  Example: `"v1"`.
- `fillType` (string, required)
  Allowed values: `inpaint`, `outpaint`.
- `baseImageMediaId` (string, required)
  편집할 이미지의 이미지 미디어 ID입니다.
- `maskMediaId` (string, optional)
  마스크의 이미지 미디어 ID로, 다시 그릴 곳은 흰색, 유지할 곳은 검은색입니다. `maskedImageMediaId`와 함께 보내거나, 둘 다 생략하면 이미지 전체를 다시 그립니다.
- `maskedImageMediaId` (string, optional)
  마스크의 흰색 영역을 `#808080`으로 칠한 베이스 이미지의 이미지 미디어 ID입니다. `maskMediaId`와 함께 보내세요.
- `prompt` (string, optional)
  편집 영역에 그릴 내용입니다.
  Default: `""`.
  Length: 0 to 10000 characters.
- `strength` (number, optional)
  결과가 원본에서 벗어날 수 있는 정도입니다. 낮을수록 원본에 가깝습니다.
  Range: 0 to 1.
- `seed` (integer, optional)
  랜덤 시드입니다. 생략하면 무작위로 생성됩니다.
- `promptHelper` (string, optional)
  PixAI가 프롬프트를 확장하는 정도입니다.
  Allowed values: `enable`, `disable`, `low`, `medium`.
  Default: `"enable"`.
- `sdeditPreset` (string, optional)
  `GET /v2/gen-task/inpaint/constraints`의 다시 그리기 프리셋 이름입니다. 다시 그리기 프리셋이 없는 `modelPreset`에 보내면 `SDEDIT_NOT_AVAILABLE`이 반환됩니다.
  Length: 1 to 64 characters.
- `sdedit` (object, optional)
  다시 그리기의 세부 조정입니다. `sdeditPreset`과 함께 보내면 여기서는 `colorCorrection`만 적용됩니다.
- `sdedit.spectralScale` (number, optional)
  Range: 0 to 1.
- `sdedit.hfsBlurSigma` (number, optional)
  Range: 0 to 32.
- `sdedit.hfsEnd` (number, optional)
  Range: 0 to 1.
- `sdedit.colorCorrection` (boolean, optional)
  원본의 색상에 맞춥니다.

Example:

```json
{
  "modelPreset": "v1",
  "fillType": "inpaint",
  "baseImageMediaId": "1943547603237249965",
  "maskMediaId": "1943547603237249966",
  "prompt": "red scarf"
}
```

### Example (cURL)

```bash
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"
  }'
```

### Responses

- `201`
  작업이 생성되었습니다. 해당 `id`로 `GET /v2/task/{id}`를 폴링하세요.
  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`
  - `INVALID_MODEL_PRESET`: 알 수 없는 `modelPreset`입니다.
  - `INVALID_MEDIA`: 이미지 미디어 ID가 없거나 이미지가 아닙니다.
  - `INVALID_SDEDIT_PRESET`: 알 수 없는 `sdeditPreset`입니다.
  - `SDEDIT_NOT_AVAILABLE`: 이 `modelPreset`은 `sdeditPreset`이나 `sdedit`을 받지 않습니다.
  - `BAD_REQUEST`(`data.issues` 포함): 본문 검증에 실패했습니다.
- `401`
  `UNAUTHORIZED`: API 키를 보내지 않았습니다. 잘못되었거나 폐기되었거나 만료된 키에는 숫자 `code`를 가진 `{"message": "invalid token", "code": 40100001}`이 반환됩니다.
- `403`
  지금은 이 계정에서 작업을 실행할 수 없습니다. 이유는 `code`로 표시됩니다:

  - `INSUFFICIENT_BALANCE`: 작업에 필요한 크레딧이 부족합니다.
  - `WAITING_NUM_EXCEEDED`: `waiting` 상태의 작업이 너무 많습니다(`data.currentWaitingTasks`). 일부가 시작될 때까지 기다린 후 제출하세요.
  - `REQUIRE_MEMBERSHIP`: 이 기능(이미지 기반 동영상 생성)에는 PixAI 멤버십이 필요합니다.
  - `NSFW_PROMPTS_DETECTED`: 계정이 세이프 모드여서 프롬프트가 거부되었습니다.
- `500`
  `CREATION_FAILED`: 작업을 생성하지 못했습니다. 지수 백오프로 재시도하세요.