> ## 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 البرمجية

> دليل واجهة Krea 3 البرمجية: نموذج سريع لتحرير الصور يتبع التعليمات. نقطة النهاية والمعاملات وأوضاع التفكير والتعديلات الموضعية وأمثلة الكود.

Krea 3 نموذج سريع لتحرير الصور. يتبع التعليمات المكتوبة بلغة عادية: تخبره بما يجب أن يتغير وما يجب أن يبقى كما هو، فيُنتج Krea 3 التعديل في ثوانٍ. ويمكنك استخدامه أيضًا لتوليد الصور من النص.

<Info>
  واجهة Krea 3 البرمجية متاحة حاليًا في **وصول مبكر**. لا يمكن استدعاؤها إلا من مساحات العمل المشاركة في النسخة التجريبية من Krea 3. لطلب الوصول، تواصل مع [sales@krea.ai](mailto:sales@krea.ai).
</Info>

## نقطة النهاية (Endpoint)

| النموذج | نقطة النهاية |
| - | - |
| **Krea 3** | `POST /generate/image/krea/krea-3` |

تستخدم نقطة النهاية [دورة حياة المهمة](/docs/ar/developers/job-lifecycle) القياسية: فهي تُرجع `job_id`، ثم تستعلم عن `GET /jobs/{job_id}` (أو تستخدم [ويب هوك](/docs/ar/developers/webhooks)) حتى تكتمل المهمة. تجد الصورة الناتجة في `result.urls[0]`.

## البدء السريع: أول تعديل لصورة

تتطلب جميع الطلبات رمز Bearer. راجع [مفاتيح API والفوترة](/docs/ar/developers/api-keys-and-billing) إذا لم يكن لديك واحد بعد.

<Steps>
  <Step title="ارفع صورة مرجعية">
    أرسل `POST /assets` مع صورة الإدخال. تُرجع الاستجابة `image_url`. يمكنك أيضًا تمرير رابط صورة خارجي أو URI بيانات بترميز base64 مباشرةً في `image_urls`.
  </Step>

  <Step title="أنشئ تعديلًا">
    أرسل `POST /generate/image/krea/krea-3` مع الموجِّه والصورة المرجعية. احفظ `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 على خادمك. لا تضعه أبدًا في كود يعمل على جانب العميل.
</Tip>

## المعاملات

| الحقل | النوع | ملاحظات |
| - | - | - |
| `prompt` | string | **مطلوب.** تعليمات التعديل. صِف ما يجب أن يتغير وما يجب أن يبقى كما هو. |
| `image_urls` | array of strings | اختياري. مراجع صور الإدخال، حتى 8 صور. أضف صورة واحدة على الأقل لإجراء تعديل، واحذفه لتوليد الصور من النص. يقبل `image_url` من `POST /assets` أو رابطًا خارجيًا أو 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 | اختياري. احذفه لاختيار بذرة عشوائية. |
| `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`، تستخدم الواجهة البرمجية `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 محرر يتبع التعليمات. اكتب التعديل بلغة عادية:

* ابدأ بالتغيير المطلوب. أضف فقط التفاصيل التي تساعد على تنفيذه.
* اختم بجملة واحدة للحفاظ على الصورة عندما يجب أن تبقى بقيتها كما هي. لا تسرد كل ما يجب أن يبقى كما هو.
* عندما يستخدم الموجِّه أكثر من صورة، أشر إلى كل صورة بما تعرضه. على سبيل المثال: "ضع الحذاء الرياضي من الصورة الثانية على الشخص في الصورة الأولى."

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

## الصور المرجعية

* يستخدم Krea 3 كل صورة مرجعية بالدقة التي رُفعت بها. تُصغَّر أي صورة مرجعية أكبر من 4 ميغابكسل إلى 4 ميغابكسل.
* دقة تقارب 1 ميغابكسل كافية لمعظم التعديلات. لا تكبّر دقة الصورة المرجعية قبل إرسالها.
* عندما تكون التفاصيل الدقيقة مهمة (النصوص الصغيرة أو الشعارات أو الأقمشة أو الوجوه في لقطة واسعة)، أرسل أعلى نسخة دقة متاحة لديك من الصورة.
* عند استخدام خمس صور مرجعية أو أكثر في طلب واحد، تُصغَّر كل صورة بحيث لا يتجاوز ضلعها الأطول 1536 بكسل. للحصول على صور مرجعية بكامل تفاصيلها، أرسل أربع صور أو أقل.

## Zero Data Retention

يدعم Krea 3 ميزة [Zero Data Retention](/docs/ar/developers/zdr) (عدم الاحتفاظ بالبيانات) لمساحات عمل المؤسسات. أرسل الترويسة `X-Api-Zero-Data-Retention: 1`. مع Zero Data Retention:

* يجب أن تكون كل صورة في `image_urls` بصيغة 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/ar/developers/job-lifecycle">
    حالات المهمة والاستعلام والنتائج.
  </Card>

  <Card title="الويب هوك" icon="bell" href="/docs/ar/developers/webhooks">
    احصل على إشعار عند اكتمال المهمة بدلًا من الاستعلام المتكرر.
  </Card>
</CardGroup>


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