> ## 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 overview

> Krea 3 API guide: a fast, instruction-following image editing model. Endpoint, parameters, thinking modes, regional edits, and code examples.

Krea 3 is a fast image editing model. It follows plain-language instructions: you say what should change and what should stay the same, and Krea 3 produces the edit in seconds. You can also use it for text-to-image generation.

<Info>
  The Krea 3 API is in **early access**. Only workspaces in the Krea 3 beta can call it. To request access, contact [sales@krea.ai](mailto:sales@krea.ai).
</Info>

## Endpoint

| Model | Endpoint |
| - | - |
| **Krea 3** | `POST /generate/image/krea/krea-3` |

The endpoint uses the standard [job lifecycle](/docs/developers/job-lifecycle): it returns a `job_id`, and you poll `GET /jobs/{job_id}` (or use a [webhook](/docs/developers/webhooks)) until the job completes. The output image is in `result.urls[0]`.

## Quickstart: your first image edit

All requests require a Bearer token. See [API Keys & Billing](/docs/developers/api-keys-and-billing) if you don't have one yet.

<Steps>
  <Step title="Upload a reference">
    `POST /assets` with your input image. The response returns `image_url`. You can also pass an external image URL or a base64 data URI directly in `image_urls`.
  </Step>

  <Step title="Create an edit">
    `POST /generate/image/krea/krea-3` with your prompt and reference. Save the `job_id` from the response.
  </Step>

  <Step title="Get the result">
    Poll `GET /jobs/{job_id}` until `status` is `completed`. The output is in `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>
  Keep your API token on your server. Never ship it in client-side code.
</Tip>

## Parameters

| Field | Type | Notes |
| - | - | - |
| `prompt` | string | **Required.** The editing instruction. Describe what should change and what should stay the same. |
| `image_urls` | array of strings | Optional. Input image references, up to 8. Include at least one for an edit; omit for text-to-image generation. Accepts an `image_url` from `POST /assets`, an external URL, or a base64 data URI. |
| `thinking_mode` | enum | Optional. `fast` (default) or `high`. See [Thinking modes](#thinking-modes). |
| `resolution` | enum | `1k` or `2k`. Required unless you supply both `width` and `height`. Do not combine it with `width` and `height`. |
| `aspect_ratio` | enum | Optional. One of `1:1`, `4:5`, `3:4`, `2:3`, `9:16`, `5:4`, `4:3`, `3:2`, `16:9`, `21:9`. Use it with `resolution`. Omit it for automatic framing. |
| `width` / `height` | integers | Optional. Requested dimensions, positive integers up to 4096 each. Supply both, without `resolution` or `aspect_ratio`. |
| `seed` | integer | Optional. Omit to choose a random seed. |
| `negative_prompt` | string | Optional. What to avoid, up to 1,024 characters. |
| `regional_edit` | boolean | Optional. Set `true` for a local edit that keeps the rest of the image exact. Needs at least one image in `image_urls`. See [Regional edits](#regional-edits). |

<Note>
  With `width` and `height`, the output is rounded to the nearest supported aspect ratio and a 1k or 2k canvas. Exact pixel dimensions are not guaranteed.

  Reusing a `seed` does not guarantee identical results, because the prompt expansion step can vary between runs.
</Note>

<h2 id="thinking-modes">
  Thinking modes
</h2>

Before it generates, Krea 3 interprets your prompt. `thinking_mode` sets how much planning it does.

| Mode | What happens | Use for |
| - | - | - |
| `fast` | Krea quickly expands the prompt, then generates. Fastest. **Default and recommended.** | Clear, simple edits and most everyday requests. |
| `high` | Krea uses a stronger reasoning engine to plan more complex edits from the prompt and the reference images, then generates. Slower. | Complex or multi-step edits, several references to combine, or a `fast` result that missed the request. |

If you omit `thinking_mode`, the API uses `fast`. Both modes support `regional_edit`.

<h2 id="regional-edits">
  Regional edits
</h2>

With `regional_edit: true`, Krea 3 regenerates only the parts of the image that need to change. Everything else stays exactly as it was, so you can edit the same image again and again without quality loss.

**Use it for local edits** where the rest of the image must stay pixel-exact: recolor or swap an object, add or remove an element, fix a detail, or change the text on a sign. It is the safe way to chain edits on the latest output.

**Leave it out for global edits** that should re-render the whole image: restyling, relighting, changing the season or time of day, reframing, or combining several images into a new scene. Regular edits re-render the whole image, so artifacts can build up when you keep editing the latest output.

Regional edits need at least one image in `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
}
```

## Prompting

Krea 3 is an instruction-following editor. Write the edit in plain language:

* Lead with the change. Add only the details that help to execute it.
* Close with one preservation sentence when the rest of the image should stay the same. Do not list everything that should stay the same.
* When the prompt uses more than one image, refer to each image by what it shows. For example: "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.
```

## Image references

* Krea 3 uses each reference at its uploaded resolution. A reference larger than 4 MP is resized to 4 MP.
* Around 1 MP is enough for most edits. Do not upscale a reference before you send it.
* When fine details matter (small text, logos, fabric, faces in a wide shot), send the highest-resolution version of the image you have.
* With five or more references in one request, each reference is resized to at most 1536 px on its longest side. For full-detail references, send four or fewer.

## Zero Data Retention

Krea 3 supports [Zero Data Retention](/docs/developers/zdr) for enterprise workspaces. Send the `X-Api-Zero-Data-Retention: 1` header. With Zero Data Retention:

* Every image in `image_urls` must be a base64 data URI.
* `thinking_mode` can be `fast` or `high`.
* A request can use at most 4 image references.

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

## Pricing

The price per image depends on the output resolution, the thinking mode, and the image references.

| Pricing component | 1K output | 2K output |
| - | - | - |
| Base price | \$0.03 | \$0.06 |
| Each 1K reference image | +\$0.02 | +\$0.02 |
| Each 2K reference image | +\$0.07 | +\$0.07 |
| `high` thinking mode | +\$0.02 per generation | +\$0.02 per generation |

## Related

<CardGroup cols={2}>
  <Card title="Job lifecycle" icon="arrows-rotate" href="/docs/developers/job-lifecycle">
    Job statuses, polling, and results.
  </Card>

  <Card title="Webhooks" icon="bell" href="/docs/developers/webhooks">
    Get notified when a job completes instead of polling.
  </Card>
</CardGroup>


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