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

# Ikhtisar API Krea 3

> Panduan API Krea 3: model pengeditan gambar yang cepat dan patuh pada instruksi. Endpoint, parameter, mode berpikir, edit regional, dan contoh kode.

Krea 3 adalah model pengeditan gambar yang cepat. Model ini mengikuti instruksi dalam bahasa sehari-hari: Anda cukup menyebutkan apa yang perlu diubah dan apa yang harus tetap sama, lalu Krea 3 menghasilkan editnya dalam hitungan detik. Anda juga dapat menggunakannya untuk menghasilkan gambar dari teks.

<Info>
  API Krea 3 sedang dalam tahap **akses awal**. Hanya workspace yang tergabung dalam beta Krea 3 yang dapat memanggilnya. Untuk meminta akses, hubungi [sales@krea.ai](mailto:sales@krea.ai).
</Info>

## Endpoint

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

Endpoint ini menggunakan [siklus hidup job](/docs/id/developers/job-lifecycle) standar: endpoint mengembalikan `job_id`, lalu Anda melakukan polling ke `GET /jobs/{job_id}` (atau menggunakan [webhook](/docs/id/developers/webhooks)) hingga job selesai. Gambar output ada di `result.urls[0]`.

## Mulai cepat: edit gambar pertama Anda

Semua permintaan memerlukan token Bearer. Lihat [API Keys & Billing](/docs/id/developers/api-keys-and-billing) jika Anda belum memilikinya.

<Steps>
  <Step title="Unggah referensi">
    `POST /assets` dengan gambar input Anda. Respons mengembalikan `image_url`. Anda juga dapat langsung meneruskan URL gambar eksternal atau data URI base64 di `image_urls`.
  </Step>

  <Step title="Buat edit">
    `POST /generate/image/krea/krea-3` dengan prompt dan referensi Anda. Simpan `job_id` dari respons.
  </Step>

  <Step title="Ambil hasilnya">
    Lakukan polling ke `GET /jobs/{job_id}` hingga `status` bernilai `completed`. Output ada di `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>
  Simpan token API Anda di server. Jangan pernah menyertakannya dalam kode sisi klien.
</Tip>

## Parameter

| Field | Tipe | Catatan |
| - | - | - |
| `prompt` | string | **Wajib.** Instruksi pengeditan. Jelaskan apa yang perlu diubah dan apa yang harus tetap sama. |
| `image_urls` | array of strings | Opsional. Referensi gambar input, maksimal 8. Sertakan setidaknya satu untuk edit; hilangkan untuk menghasilkan gambar dari teks. Menerima `image_url` dari `POST /assets`, URL eksternal, atau data URI base64. |
| `thinking_mode` | enum | Opsional. `fast` (default) atau `high`. Lihat [Mode berpikir](#thinking-modes). |
| `resolution` | enum | `1k` atau `2k`. Wajib kecuali Anda menyertakan `width` dan `height` sekaligus. Jangan menggabungkannya dengan `width` dan `height`. |
| `aspect_ratio` | enum | Opsional. Salah satu dari `1:1`, `4:5`, `3:4`, `2:3`, `9:16`, `5:4`, `4:3`, `3:2`, `16:9`, `21:9`. Gunakan bersama `resolution`. Hilangkan untuk pembingkaian otomatis. |
| `width` / `height` | integers | Opsional. Dimensi yang diminta, bilangan bulat positif hingga 4096 masing-masing. Sertakan keduanya, tanpa `resolution` atau `aspect_ratio`. |
| `seed` | integer | Opsional. Hilangkan untuk memilih seed acak. |
| `negative_prompt` | string | Opsional. Hal yang ingin dihindari, maksimal 1,024 karakter. |
| `regional_edit` | boolean | Opsional. Atur ke `true` untuk edit lokal yang menjaga bagian lain gambar tetap persis sama. Memerlukan setidaknya satu gambar di `image_urls`. Lihat [Edit regional](#regional-edits). |

<Note>
  Dengan `width` dan `height`, output dibulatkan ke rasio aspek terdekat yang didukung dan kanvas 1k atau 2k. Dimensi piksel yang persis tidak dijamin.

  Menggunakan ulang `seed` tidak menjamin hasil yang identik, karena tahap perluasan prompt dapat berbeda di setiap proses.
</Note>

<h2 id="thinking-modes">
  Mode berpikir
</h2>

Sebelum menghasilkan gambar, Krea 3 menafsirkan prompt Anda. `thinking_mode` menentukan seberapa banyak perencanaan yang dilakukannya.

| Mode | Yang terjadi | Gunakan untuk |
| - | - | - |
| `fast` | Krea dengan cepat memperluas prompt, lalu menghasilkan gambar. Paling cepat. **Default dan direkomendasikan.** | Edit yang jelas dan sederhana serta sebagian besar permintaan sehari-hari. |
| `high` | Krea menggunakan mesin penalaran yang lebih kuat untuk merencanakan edit yang lebih kompleks dari prompt dan gambar referensi, lalu menghasilkan gambar. Lebih lambat. | Edit yang kompleks atau bertahap, beberapa referensi yang perlu digabungkan, atau hasil `fast` yang tidak sesuai permintaan. |

Jika Anda tidak menyertakan `thinking_mode`, API menggunakan `fast`. Kedua mode mendukung `regional_edit`.

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

Dengan `regional_edit: true`, Krea 3 hanya membuat ulang bagian gambar yang perlu diubah. Semua bagian lain tetap persis seperti semula, sehingga Anda dapat mengedit gambar yang sama berulang kali tanpa kehilangan kualitas.

**Gunakan untuk edit lokal** ketika bagian lain gambar harus tetap sama hingga ke tingkat piksel: mengubah warna atau mengganti objek, menambah atau menghapus elemen, memperbaiki detail, atau mengubah teks pada papan tanda. Ini adalah cara aman untuk merangkai edit pada output terbaru.

**Jangan gunakan untuk edit global** yang perlu merender ulang seluruh gambar: mengubah gaya, mengubah pencahayaan, mengganti musim atau waktu, mengubah pembingkaian, atau menggabungkan beberapa gambar menjadi adegan baru. Edit biasa merender ulang seluruh gambar, sehingga artefak dapat menumpuk jika Anda terus mengedit output terbaru.

Edit regional memerlukan setidaknya satu gambar di `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
}
```

## Menulis prompt

Krea 3 adalah editor yang mengikuti instruksi. Tuliskan edit Anda dalam bahasa sehari-hari:

* Awali dengan perubahan yang diinginkan. Tambahkan hanya detail yang membantu mewujudkannya.
* Tutup dengan satu kalimat pelestarian jika bagian lain gambar harus tetap sama. Jangan mendaftar semua hal yang harus tetap sama.
* Jika prompt menggunakan lebih dari satu gambar, sebut setiap gambar berdasarkan isinya. Contoh: "Pakaikan sepatu sneaker dari gambar kedua pada orang di gambar pertama."

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

## Referensi gambar

* Krea 3 menggunakan setiap referensi pada resolusi saat diunggah. Referensi yang lebih besar dari 4 MP akan diubah ukurannya menjadi 4 MP.
* Sekitar 1 MP sudah cukup untuk sebagian besar edit. Jangan memperbesar resolusi referensi sebelum mengirimnya.
* Jika detail halus penting (teks kecil, logo, kain, wajah dalam bidikan lebar), kirim versi gambar dengan resolusi tertinggi yang Anda miliki.
* Dengan lima referensi atau lebih dalam satu permintaan, setiap referensi diubah ukurannya menjadi maksimal 1536 px pada sisi terpanjangnya. Untuk referensi dengan detail penuh, kirim empat referensi atau kurang.

## Zero Data Retention

Krea 3 mendukung [Zero Data Retention](/docs/id/developers/zdr) untuk workspace enterprise. Kirim header `X-Api-Zero-Data-Retention: 1`. Dengan Zero Data Retention:

* Setiap gambar di `image_urls` harus berupa data URI base64.
* `thinking_mode` dapat bernilai `fast` atau `high`.
* Satu permintaan dapat menggunakan maksimal 4 referensi gambar.

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

## Harga

Harga per gambar bergantung pada resolusi output, mode berpikir, dan referensi gambar.

| Komponen harga | Output 1K | Output 2K |
| - | - | - |
| Harga dasar | \$0.03 | \$0.06 |
| Setiap gambar referensi 1K | +\$0.02 | +\$0.02 |
| Setiap gambar referensi 2K | +\$0.07 | +\$0.07 |
| Mode berpikir `high` | +\$0.02 per generasi | +\$0.02 per generasi |

## Terkait

<CardGroup cols={2}>
  <Card title="Siklus hidup job" icon="arrows-rotate" href="/docs/id/developers/job-lifecycle">
    Status job, polling, dan hasil.
  </Card>

  <Card title="Webhooks" icon="bell" href="/docs/id/developers/webhooks">
    Dapatkan notifikasi saat job selesai alih-alih melakukan polling.
  </Card>
</CardGroup>


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