> ## 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'sine genel bakış

> Krea 3 API kılavuzu: talimatları izleyen hızlı bir görüntü düzenleme modeli. Endpoint, parametreler, düşünme modları, bölgesel düzenlemeler ve kod örnekleri.

Krea 3, hızlı bir görüntü düzenleme modelidir. Sade bir dille yazılmış talimatları izler: neyin değişmesi ve neyin aynı kalması gerektiğini söylersiniz, Krea 3 de düzenlemeyi saniyeler içinde üretir. Metinden görüntü üretimi için de kullanabilirsiniz.

<Info>
  Krea 3 API'si **erken erişim** aşamasındadır. Yalnızca Krea 3 betasındaki workspace'ler bu API'yi çağırabilir. Erişim talep etmek için [sales@krea.ai](mailto:sales@krea.ai) adresiyle iletişime geçin.
</Info>

## Endpoint

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

Endpoint, standart [iş yaşam döngüsünü](/docs/tr/developers/job-lifecycle) kullanır: bir `job_id` döndürür, siz de iş tamamlanana kadar `GET /jobs/{job_id}` adresini yoklarsınız (veya bir [webhook](/docs/tr/developers/webhooks) kullanırsınız). Çıktı görüntüsü `result.urls[0]` içindedir.

## Hızlı başlangıç: ilk görüntü düzenlemeniz

Tüm istekler bir Bearer token gerektirir. Henüz almadıysanız [API Anahtarları ve Faturalandırma](/docs/tr/developers/api-keys-and-billing) sayfasına bakın.

<Steps>
  <Step title="Bir referans yükleyin">
    Girdi görüntünüzle `POST /assets` isteği gönderin. Yanıt `image_url` değerini döndürür. Harici bir görüntü URL'sini veya base64 data URI'sini doğrudan `image_urls` içinde de iletebilirsiniz.
  </Step>

  <Step title="Bir düzenleme oluşturun">
    Prompt'unuz ve referansınızla `POST /generate/image/krea/krea-3` isteği gönderin. Yanıttaki `job_id` değerini kaydedin.
  </Step>

  <Step title="Sonucu alın">
    `status` değeri `completed` olana kadar `GET /jobs/{job_id}` adresini yoklayın. Çıktı `result.urls[0]` içindedir.
  </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 token'ınızı sunucunuzda tutun. Asla istemci tarafı kodda yayınlamayın.
</Tip>

## Parametreler

| Alan | Tür | Notlar |
| - | - | - |
| `prompt` | string | **Zorunlu.** Düzenleme talimatı. Neyin değişmesi ve neyin aynı kalması gerektiğini açıklayın. |
| `image_urls` | array of strings | İsteğe bağlı. En fazla 8 girdi görüntüsü referansı. Düzenleme için en az bir tane ekleyin; metinden görüntü üretimi için boş bırakın. `POST /assets` kaynağından bir `image_url`, harici bir URL veya base64 data URI kabul eder. |
| `thinking_mode` | enum | İsteğe bağlı. `fast` (varsayılan) veya `high`. Bkz. [Düşünme modları](#thinking-modes). |
| `resolution` | enum | `1k` veya `2k`. `width` ve `height` değerlerinin ikisini birden vermediğiniz sürece zorunludur. `width` ve `height` ile birlikte kullanmayın. |
| `aspect_ratio` | enum | İsteğe bağlı. `1:1`, `4:5`, `3:4`, `2:3`, `9:16`, `5:4`, `4:3`, `3:2`, `16:9`, `21:9` değerlerinden biri. `resolution` ile birlikte kullanın. Otomatik kadrajlama için boş bırakın. |
| `width` / `height` | integers | İsteğe bağlı. İstenen boyutlar; her biri en fazla 4096 olan pozitif tam sayılar. İkisini birlikte, `resolution` veya `aspect_ratio` olmadan verin. |
| `seed` | integer | İsteğe bağlı. Rastgele bir seed seçilmesi için boş bırakın. |
| `negative_prompt` | string | İsteğe bağlı. Kaçınılacak öğeler, en fazla 1,024 karakter. |
| `regional_edit` | boolean | İsteğe bağlı. Görüntünün geri kalanını birebir koruyan yerel bir düzenleme için `true` olarak ayarlayın. `image_urls` içinde en az bir görüntü gerektirir. Bkz. [Bölgesel düzenlemeler](#regional-edits). |

<Note>
  `width` ve `height` kullanıldığında çıktı, desteklenen en yakın en boy oranına ve 1k veya 2k tuvale yuvarlanır. Piksel boyutlarının birebir tutacağı garanti edilmez.

  Aynı `seed` değerini yeniden kullanmak aynı sonuçları garanti etmez, çünkü prompt genişletme adımı çalıştırmalar arasında farklılık gösterebilir.
</Note>

<h2 id="thinking-modes">
  Düşünme modları
</h2>

Krea 3, üretimden önce prompt'unuzu yorumlar. `thinking_mode`, modelin ne kadar planlama yapacağını belirler.

| Mod | Ne olur | Ne için kullanılır |
| - | - | - |
| `fast` | Krea prompt'u hızla genişletir, ardından üretir. En hızlı mod. **Varsayılan ve önerilen.** | Açık, basit düzenlemeler ve günlük isteklerin çoğu. |
| `high` | Krea, prompt'tan ve referans görüntülerden daha karmaşık düzenlemeleri planlamak için daha güçlü bir akıl yürütme motoru kullanır, ardından üretir. Daha yavaştır. | Karmaşık veya çok adımlı düzenlemeler, birleştirilecek birden fazla referans ya da isteği karşılamayan bir `fast` sonucu. |

`thinking_mode` belirtmezseniz API `fast` kullanır. Her iki mod da `regional_edit` destekler.

<h2 id="regional-edits">
  Bölgesel düzenlemeler
</h2>

`regional_edit: true` ile Krea 3 yalnızca görüntünün değişmesi gereken kısımlarını yeniden üretir. Geri kalan her şey olduğu gibi kalır; böylece aynı görüntüyü kalite kaybı olmadan tekrar tekrar düzenleyebilirsiniz.

**Yerel düzenlemeler için kullanın**: görüntünün geri kalanının piksel düzeyinde aynı kalması gereken durumlarda bir nesneyi yeniden renklendirmek veya değiştirmek, bir öğe eklemek veya kaldırmak, bir ayrıntıyı düzeltmek ya da bir tabeladaki metni değiştirmek gibi. En son çıktı üzerinde düzenlemeleri zincirlemenin güvenli yolu budur.

**Global düzenlemelerde kullanmayın**: stili veya ışığı değiştirmek, mevsimi ya da günün saatini değiştirmek, yeniden kadrajlamak veya birden fazla görüntüyü yeni bir sahnede birleştirmek gibi tüm görüntünün yeniden oluşturulması gereken durumlar. Normal düzenlemeler tüm görüntüyü yeniden oluşturur; bu nedenle en son çıktıyı düzenlemeye devam ettikçe artefaktlar birikebilir.

Bölgesel düzenlemeler için `image_urls` içinde en az bir görüntü gerekir.

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

## Prompt yazma

Krea 3, talimatları izleyen bir düzenleyicidir. Düzenlemeyi sade bir dille yazın:

* Değişiklikle başlayın. Yalnızca uygulanmasına yardımcı olan ayrıntıları ekleyin.
* Görüntünün geri kalanı aynı kalmalıysa, bunu belirten tek bir cümleyle bitirin. Aynı kalması gereken her şeyi tek tek listelemeyin.
* Prompt birden fazla görüntü kullandığında, her görüntüden içinde ne olduğuyla bahsedin. Örneğin: "İkinci görüntüdeki spor ayakkabıyı birinci görüntüdeki kişiye giydir."

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

## Görüntü referansları

* Krea 3 her referansı yüklendiği çözünürlükte kullanır. 4 MP'den büyük bir referans 4 MP'ye yeniden boyutlandırılır.
* Çoğu düzenleme için yaklaşık 1 MP yeterlidir. Bir referansı göndermeden önce büyütmeyin.
* İnce ayrıntılar önemli olduğunda (küçük metinler, logolar, kumaş, geniş çekimdeki yüzler), elinizdeki en yüksek çözünürlüklü görüntüyü gönderin.
* Tek bir istekte beş veya daha fazla referans olduğunda, her referans en uzun kenarı en fazla 1536 px olacak şekilde yeniden boyutlandırılır. Tam ayrıntılı referanslar için dört veya daha az referans gönderin.

## Zero Data Retention

Krea 3, kurumsal workspace'ler için [Zero Data Retention](/docs/tr/developers/zdr) desteği sunar. `X-Api-Zero-Data-Retention: 1` başlığını gönderin. Zero Data Retention ile:

* `image_urls` içindeki her görüntü bir base64 data URI olmalıdır.
* `thinking_mode`, `fast` veya `high` olabilir.
* Bir istek en fazla 4 görüntü referansı kullanabilir.

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

## Fiyatlandırma

Görüntü başına fiyat; çıktı çözünürlüğüne, düşünme moduna ve görüntü referanslarına bağlıdır.

| Fiyatlandırma bileşeni | 1K çıktı | 2K çıktı |
| - | - | - |
| Temel fiyat | \$0.03 | \$0.06 |
| Her 1K referans görüntü | +\$0.02 | +\$0.02 |
| Her 2K referans görüntü | +\$0.07 | +\$0.07 |
| `high` düşünme modu | Üretim başına +\$0.02 | Üretim başına +\$0.02 |

## İlgili

<CardGroup cols={2}>
  <Card title="İş yaşam döngüsü" icon="arrows-rotate" href="/docs/tr/developers/job-lifecycle">
    İş durumları, yoklama ve sonuçlar.
  </Card>

  <Card title="Webhooks" icon="bell" href="/docs/tr/developers/webhooks">
    Yoklama yapmak yerine bir iş tamamlandığında bildirim alın.
  </Card>
</CardGroup>


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