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

# Обзор API Krea 3

> API Krea 3: быстрая модель редактирования изображений, точно следующая инструкциям. Endpoint, параметры, режимы мышления, локальные правки и тарифы.

Krea 3 — быстрая модель редактирования изображений. Она понимает инструкции на обычном языке: вы описываете, что нужно изменить и что должно остаться прежним, и Krea 3 выполняет правку за считаные секунды. Модель также можно использовать для генерации изображений по тексту.

<Info>
  API Krea 3 находится в **раннем доступе**. Вызывать его могут только workspace, участвующие в бета-тестировании Krea 3. Чтобы запросить доступ, напишите на [sales@krea.ai](mailto:sales@krea.ai).
</Info>

## Endpoint

| Модель | Endpoint |
| - | - |
| **Krea 3** | `POST /generate/image/krea/krea-3` |

Endpoint работает по стандартному [жизненному циклу задания](/docs/ru/developers/job-lifecycle): он возвращает `job_id`, после чего вы опрашиваете `GET /jobs/{job_id}` (или используете [webhook](/docs/ru/developers/webhooks)), пока задание не завершится. Итоговое изображение находится в `result.urls[0]`.

## Быстрый старт: ваша первая правка изображения

Все запросы требуют Bearer token. Если у вас его ещё нет, см. [API Keys & Billing](/docs/ru/developers/api-keys-and-billing).

<Steps>
  <Step title="Загрузите референс">
    Отправьте `POST /assets` с входным изображением. В ответе вернётся `image_url`. Также можно передать в `image_urls` напрямую URL внешнего изображения или data URI в base64.
  </Step>

  <Step title="Создайте правку">
    Отправьте `POST /generate/image/krea/krea-3` с prompt и референсом. Сохраните `job_id` из ответа.
  </Step>

  <Step title="Получите результат">
    Опрашивайте `GET /jobs/{job_id}`, пока `status` не станет `completed`. Результат находится в `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 token на своём сервере. Никогда не включайте его в клиентский код.
</Tip>

## Параметры

| Поле | Тип | Примечания |
| - | - | - |
| `prompt` | string | **Обязательный.** Инструкция для правки. Опишите, что нужно изменить и что должно остаться прежним. |
| `image_urls` | array of strings | Необязательный. Входные изображения-референсы, не более 8. Для правки укажите хотя бы одно; для генерации по тексту не указывайте. Принимает `image_url` из `POST /assets`, внешний URL или data URI в base64. |
| `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 | Необязательный. Если не указан, seed выбирается случайно. |
| `negative_prompt` | string | Необязательный. Чего следует избегать, не более 1,024 символов. |
| `regional_edit` | boolean | Необязательный. Установите `true` для локальной правки, при которой остальная часть изображения остаётся неизменной. Требует хотя бы одного изображения в `image_urls`. См. [Локальные правки](#regional-edits). |

<Note>
  При использовании `width` и `height` результат округляется до ближайшего поддерживаемого соотношения сторон и холста 1k или 2k. Точные размеры в пикселях не гарантируются.

  Повторное использование `seed` не гарантирует идентичных результатов, поскольку этап расширения prompt может отличаться от запуска к запуску.
</Note>

<h2 id="thinking-modes">
  Режимы мышления
</h2>

Перед генерацией Krea 3 интерпретирует ваш prompt. `thinking_mode` определяет, насколько тщательно модель планирует правку.

| Режим | Что происходит | Когда использовать |
| - | - | - |
| `fast` | Krea быстро расширяет prompt, а затем генерирует изображение. Самый быстрый режим. **Используется по умолчанию и рекомендуется.** | Понятные простые правки и большинство повседневных запросов. |
| `high` | Krea использует более мощный механизм рассуждений, чтобы спланировать сложную правку на основе prompt и референсов, а затем генерирует изображение. Работает медленнее. | Сложные или многоэтапные правки, объединение нескольких референсов или случаи, когда результат `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
}
```

## Составление prompt

Krea 3 — редактор, который следует инструкциям. Описывайте правку обычным языком:

* Начните с самого изменения. Добавляйте только те детали, которые помогают его выполнить.
* Если остальная часть изображения должна остаться прежней, завершите prompt одним предложением об этом. Не перечисляйте всё, что должно сохраниться.
* Если в prompt используется несколько изображений, называйте каждое по тому, что на нём изображено. Например: «Надень кроссовок со второго изображения на человека с первого изображения».

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

## Изображения-референсы

* Krea 3 использует каждый референс в том разрешении, в котором он был загружен. Референс больше 4 MP уменьшается до 4 MP.
* Для большинства правок достаточно около 1 MP. Не увеличивайте разрешение референса перед отправкой.
* Если важны мелкие детали (мелкий текст, логотипы, ткань, лица на общем плане), отправляйте версию изображения с максимальным доступным разрешением.
* Если в одном запросе пять или более референсов, каждый уменьшается до 1536 px по длинной стороне. Чтобы сохранить все детали, отправляйте не более четырёх референсов.

## Zero Data Retention

Krea 3 поддерживает [Zero Data Retention](/docs/ru/developers/zdr) для enterprise-workspace. Передайте заголовок `X-Api-Zero-Data-Retention: 1`. В режиме Zero Data Retention:

* Каждое изображение в `image_urls` должно быть data URI в base64.
* `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/ru/developers/job-lifecycle">
    Статусы заданий, опрос и результаты.
  </Card>

  <Card title="Webhooks" icon="bell" href="/docs/ru/developers/webhooks">
    Получайте уведомление о завершении задания вместо опроса.
  </Card>
</CardGroup>


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