> ## Documentation Index
> Fetch the complete documentation index at: https://www.krea.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Krea 3 API 개요

> Krea 3 API 가이드: 지시를 정확히 따르는 빠른 이미지 편집 모델입니다. 엔드포인트, 파라미터, 사고 모드, 영역 편집을 다룹니다.

Krea 3는 빠른 이미지 편집 모델입니다. 일상적인 언어로 된 지시를 따릅니다. 무엇을 바꾸고 무엇을 그대로 둘지 말하면 Krea 3가 몇 초 만에 편집 결과를 만들어 냅니다. 텍스트-투-이미지 생성에도 사용할 수 있습니다.

<Info>
  Krea 3 API는 현재 **얼리 액세스** 단계입니다. Krea 3 베타에 참여한 워크스페이스만 호출할 수 있습니다. 액세스를 요청하려면 [sales@krea.ai](mailto:sales@krea.ai)로 문의하세요.
</Info>

## 엔드포인트

| 모델 | 엔드포인트 |
| - | - |
| **Krea 3** | `POST /generate/image/krea/krea-3` |

이 엔드포인트는 표준 [작업 라이프사이클](/docs/ko/developers/job-lifecycle)을 따릅니다. `job_id`를 반환하며, 작업이 완료될 때까지 `GET /jobs/{job_id}`를 폴링하면 됩니다([웹훅](/docs/ko/developers/webhooks)을 사용할 수도 있습니다). 출력 이미지는 `result.urls[0]`에 있습니다.

## 빠른 시작: 첫 번째 이미지 편집

모든 요청에는 Bearer 토큰이 필요합니다. 아직 없다면 [API Keys & Billing](/docs/ko/developers/api-keys-and-billing)을 참고하세요.

<Steps>
  <Step title="참조 이미지 업로드">
    입력 이미지를 `POST /assets`로 보냅니다. 응답으로 `image_url`이 반환됩니다. 외부 이미지 URL이나 base64 데이터 URI를 `image_urls`에 직접 전달할 수도 있습니다.
  </Step>

  <Step title="편집 생성">
    프롬프트와 참조 이미지를 담아 `POST /generate/image/krea/krea-3`를 호출합니다. 응답의 `job_id`를 저장하세요.
  </Step>

  <Step title="결과 가져오기">
    `status`가 `completed`가 될 때까지 `GET /jobs/{job_id}`를 폴링합니다. 출력은 `result.urls[0]`에 있습니다.
  </Step>
</Steps>

<CodeGroup>
  ```bash cURL theme={null}
  # Bash + curl + jq. Set KREA_API_TOKEN to your API token first.
  set -euo pipefail
  : "${KREA_API_TOKEN:?Set your Krea API token}"

  # 1. Upload a reference
  ASSET=$(curl --fail-with-body --silent --show-error --max-time 60 \
    https://api.krea.ai/assets \
    -H "Authorization: Bearer $KREA_API_TOKEN" \
    -F "file=@reference.png")

  IMAGE_URL=$(printf '%s' "$ASSET" | jq -er '.image_url')

  # 2. Create an edit
  PAYLOAD=$(jq -n --arg image "$IMAGE_URL" '{
    prompt: "Place the product on a clean studio background",
    thinking_mode: "fast",
    image_urls: [$image],
    resolution: "2k"
  }')

  JOB=$(curl --fail-with-body --silent --show-error --max-time 60 \
    https://api.krea.ai/generate/image/krea/krea-3 \
    -H "Authorization: Bearer $KREA_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d "$PAYLOAD")

  JOB_ID=$(printf '%s' "$JOB" | jq -er '.job_id')

  # 3. Get the result
  for attempt in $(seq 1 150); do
    JOB=$(curl --fail-with-body --silent --show-error --max-time 30 \
      "https://api.krea.ai/jobs/$JOB_ID" \
      -H "Authorization: Bearer $KREA_API_TOKEN")
    STATUS=$(printf '%s' "$JOB" | jq -er '.status')
    case "$STATUS" in
      completed)
        printf '%s' "$JOB" | jq -er '.result.urls[0]'
        exit 0 ;;
      failed|cancelled)
        printf 'Job ended: %s\n' "$STATUS" >&2; exit 1 ;;
      scheduled|processing|queued|backlogged|sampling|intermediate-complete)
        sleep 2 ;;
      *) printf 'Unexpected status: %s\n' "$STATUS" >&2; exit 1 ;;
    esac
  done
  printf 'Polling timed out\n' >&2
  exit 1
  ```

  ```python Python theme={null}
  # Python 3 + requests: pip install requests
  # Set KREA_API_TOKEN to your API token first.
  import os
  import time
  import requests

  api = "https://api.krea.ai"
  headers = {"Authorization": f"Bearer {os.environ['KREA_API_TOKEN']}"}

  # 1. Upload a reference
  with open("reference.png", "rb") as image:
      response = requests.post(
          f"{api}/assets", headers=headers,
          files={"file": image}, timeout=60,
      )
  response.raise_for_status()
  image_url = response.json()["image_url"]

  # 2. Create an edit
  response = requests.post(
      f"{api}/generate/image/krea/krea-3",
      headers=headers,
      json={
          "prompt": "Place the product on a clean studio background",
          "thinking_mode": "fast",
          "image_urls": [image_url],
          "resolution": "2k",
      },
      timeout=60,
  )
  response.raise_for_status()
  job_id = response.json()["job_id"]

  # 3. Get the result
  pending = {"scheduled", "processing", "queued", "backlogged",
             "sampling", "intermediate-complete"}
  deadline = time.monotonic() + 300

  while time.monotonic() < deadline:
      response = requests.get(
          f"{api}/jobs/{job_id}", headers=headers, timeout=30,
      )
      response.raise_for_status()
      job = response.json()
      if job["status"] == "completed":
          print(job["result"]["urls"][0])
          break
      if job["status"] not in pending:
          raise RuntimeError(f"Job ended: {job['status']}")
      time.sleep(2)
  else:
      raise TimeoutError("Polling timed out")
  ```

  ```javascript Node.js theme={null}
  // Node.js 22+. Save as example.mjs.
  // Set KREA_API_TOKEN to your API token first.
  import { readFile } from "node:fs/promises";

  const token = process.env.KREA_API_TOKEN;
  if (!token) throw new Error("Set your Krea API token");
  const api = "https://api.krea.ai";
  const headers = { Authorization: `Bearer ${token}` };

  async function request(path, options = {}) {
    const response = await fetch(`${api}${path}`, {
      ...options,
      headers: { ...headers, ...options.headers },
      signal: AbortSignal.timeout(60_000),
    });
    if (!response.ok) throw new Error(`HTTP ${response.status}`);
    return response.json();
  }

  // 1. Upload a reference
  const form = new FormData();
  form.append("file", new Blob([await readFile("reference.png")]), "reference.png");
  const asset = await request("/assets", { method: "POST", body: form });

  // 2. Create an edit
  const job = await request("/generate/image/krea/krea-3", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      prompt: "Place the product on a clean studio background",
      thinking_mode: "fast",
      image_urls: [asset.image_url],
      resolution: "2k",
    }),
  });

  // 3. Get the result
  const pending = new Set([
    "scheduled", "processing", "queued", "backlogged",
    "sampling", "intermediate-complete",
  ]);
  const deadline = Date.now() + 300_000;
  let imageUrl;

  while (Date.now() < deadline) {
    const result = await request(`/jobs/${job.job_id}`);
    if (result.status === "completed") {
      imageUrl = result.result.urls[0];
      break;
    }
    if (!pending.has(result.status)) {
      throw new Error(`Job ended: ${result.status}`);
    }
    await new Promise((resolve) => setTimeout(resolve, 2_000));
  }
  if (!imageUrl) throw new Error("Polling timed out");
  console.log(imageUrl);
  ```
</CodeGroup>

<Tip>
  API 토큰은 서버에 보관하세요. 클라이언트 측 코드에 절대 포함하지 마세요.
</Tip>

## 파라미터

| 필드 | 타입 | 설명 |
| - | - | - |
| `prompt` | string | **필수.** 편집 지시입니다. 무엇을 바꾸고 무엇을 그대로 둘지 설명하세요. |
| `image_urls` | array of strings | 선택. 입력 이미지 참조이며 최대 8개입니다. 편집하려면 하나 이상 포함하고, 텍스트-투-이미지 생성에서는 생략하세요. `POST /assets`에서 받은 `image_url`, 외부 URL, base64 데이터 URI를 사용할 수 있습니다. |
| `thinking_mode` | enum | 선택. `fast`(기본값) 또는 `high`. [사고 모드](#thinking-modes)를 참고하세요. |
| `resolution` | enum | `1k` 또는 `2k`. `width`와 `height`를 모두 지정하지 않는 한 필수입니다. `width`, `height`와 함께 사용하지 마세요. |
| `aspect_ratio` | enum | 선택. `1:1`, `4:5`, `3:4`, `2:3`, `9:16`, `5:4`, `4:3`, `3:2`, `16:9`, `21:9` 중 하나입니다. `resolution`과 함께 사용하세요. 자동 프레이밍을 원하면 생략하세요. |
| `width` / `height` | integers | 선택. 요청할 크기이며 각각 4096 이하의 양의 정수입니다. `resolution`이나 `aspect_ratio` 없이 둘 다 지정하세요. |
| `seed` | integer | 선택. 생략하면 무작위 시드가 선택됩니다. |
| `negative_prompt` | string | 선택. 피하고 싶은 요소이며 최대 1,024자입니다. |
| `regional_edit` | boolean | 선택. 이미지의 나머지 부분을 그대로 유지하는 부분 편집을 하려면 `true`로 설정하세요. `image_urls`에 이미지가 하나 이상 필요합니다. [영역 편집](#regional-edits)을 참고하세요. |

<Note>
  `width`와 `height`를 지정하면 출력은 가장 가까운 지원 화면비와 1k 또는 2k 캔버스로 반올림됩니다. 정확한 픽셀 크기는 보장되지 않습니다.

  같은 `seed`를 다시 사용해도 동일한 결과가 보장되지는 않습니다. 프롬프트 확장 단계가 실행할 때마다 달라질 수 있기 때문입니다.
</Note>

<h2 id="thinking-modes">
  사고 모드
</h2>

Krea 3는 생성하기 전에 프롬프트를 해석합니다. `thinking_mode`는 계획을 얼마나 세울지 설정합니다.

| 모드 | 동작 방식 | 용도 |
| - | - | - |
| `fast` | Krea가 프롬프트를 빠르게 확장한 뒤 생성합니다. 가장 빠릅니다. **기본값이자 권장 모드입니다.** | 명확하고 간단한 편집과 대부분의 일상적인 요청. |
| `high` | Krea가 더 강력한 추론 엔진으로 프롬프트와 참조 이미지를 바탕으로 복잡한 편집을 계획한 뒤 생성합니다. 더 느립니다. | 복잡하거나 여러 단계로 이루어진 편집, 여러 참조 이미지를 결합하는 경우, 또는 `fast` 결과가 요청을 제대로 반영하지 못한 경우. |

`thinking_mode`를 생략하면 API는 `fast`를 사용합니다. 두 모드 모두 `regional_edit`를 지원합니다.

<h2 id="regional-edits">
  영역 편집
</h2>

`regional_edit: true`를 사용하면 Krea 3는 이미지에서 바뀌어야 하는 부분만 다시 생성합니다. 나머지는 원래 그대로 유지되므로 품질 저하 없이 같은 이미지를 계속해서 편집할 수 있습니다.

**부분 편집에 사용하세요.** 이미지의 나머지 부분이 픽셀 단위로 정확히 유지되어야 하는 경우입니다. 예를 들어 오브젝트의 색을 바꾸거나 교체하기, 요소 추가 또는 제거, 디테일 수정, 간판의 텍스트 변경 등이 있습니다. 최신 출력에 편집을 이어서 적용할 때도 안전한 방법입니다.

**이미지 전체를 다시 렌더링해야 하는 전체 편집에서는 사용하지 마세요.** 예를 들어 스타일 변경, 조명 변경, 계절이나 시간대 변경, 구도 변경, 여러 이미지를 결합해 새로운 장면 만들기 등이 있습니다. 일반 편집은 이미지 전체를 다시 렌더링하므로 최신 출력을 계속 편집하면 아티팩트가 누적될 수 있습니다.

영역 편집에는 `image_urls`에 이미지가 하나 이상 필요합니다.

```json theme={null}
{
  "prompt": "Change the mug to red, keeping everything else the same",
  "image_urls": ["IMAGE_URL"],
  "thinking_mode": "fast",
  "resolution": "2k",
  "regional_edit": true
}
```

## 프롬프트 작성

Krea 3는 지시를 따르는 편집기입니다. 편집 내용을 일상적인 언어로 작성하세요.

* 변경 사항을 먼저 쓰세요. 실행에 도움이 되는 세부 사항만 덧붙이세요.
* 이미지의 나머지 부분을 그대로 유지해야 한다면 마지막에 유지를 요청하는 문장 하나를 추가하세요. 유지해야 할 것을 모두 나열하지는 마세요.
* 프롬프트에 이미지를 두 개 이상 사용할 때는 각 이미지를 그 내용으로 지칭하세요. 예: "Put the sneaker from the second image on the person in the first image."

```text theme={null}
Change the mug to red, keeping everything else the same.
```

## 이미지 참조

* Krea 3는 각 참조 이미지를 업로드된 해상도 그대로 사용합니다. 4 MP보다 큰 참조 이미지는 4 MP로 크기가 조정됩니다.
* 대부분의 편집에는 약 1 MP면 충분합니다. 보내기 전에 참조 이미지를 업스케일하지 마세요.
* 세밀한 디테일이 중요할 때(작은 텍스트, 로고, 원단, 와이드 숏 속 얼굴 등)는 가지고 있는 가장 높은 해상도의 이미지를 보내세요.
* 한 요청에 참조 이미지가 5개 이상이면 각 이미지는 긴 변이 최대 1536 px가 되도록 크기가 조정됩니다. 디테일을 온전히 유지하려면 4개 이하로 보내세요.

## Zero Data Retention

Krea 3는 엔터프라이즈 워크스페이스에서 [Zero Data Retention](/docs/ko/developers/zdr)을 지원합니다. `X-Api-Zero-Data-Retention: 1` 헤더를 보내세요. Zero Data Retention 사용 시:

* `image_urls`의 모든 이미지는 base64 데이터 URI여야 합니다.
* `thinking_mode`는 `fast` 또는 `high`일 수 있습니다.
* 한 요청에 최대 4개의 이미지 참조를 사용할 수 있습니다.

```bash theme={null}
IMAGE_DATA_URI="data:image/png;base64,$(base64 < ./reference.png | tr -d '\n')"

curl -X POST https://api.krea.ai/generate/image/krea/krea-3 \
  -H "Authorization: Bearer $KREA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Api-Zero-Data-Retention: 1" \
  -d '{
    "prompt": "Change the mug to red, keeping everything else the same",
    "image_urls": ["'"$IMAGE_DATA_URI"'"],
    "thinking_mode": "fast",
    "resolution": "2k"
  }'
```

## 가격

이미지당 가격은 출력 해상도, 사고 모드, 이미지 참조에 따라 달라집니다.

| 가격 구성 요소 | 1K 출력 | 2K 출력 |
| - | - | - |
| 기본 가격 | \$0.03 | \$0.06 |
| 1K 참조 이미지당 | +\$0.02 | +\$0.02 |
| 2K 참조 이미지당 | +\$0.07 | +\$0.07 |
| `high` 사고 모드 | 생성당 +\$0.02 | 생성당 +\$0.02 |

## 관련 문서

<CardGroup cols={2}>
  <Card title="작업 라이프사이클" icon="arrows-rotate" href="/docs/ko/developers/job-lifecycle">
    작업 상태, 폴링, 결과.
  </Card>

  <Card title="웹훅" icon="bell" href="/docs/ko/developers/webhooks">
    폴링 대신 작업이 완료되면 알림을 받으세요.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.